Agent Capture CLI

Record, screenshot, and convert macOS windows and screens for AI agent evidence.

Consolidates macOS screen capture, window recording, GIF conversion, frame stitching, and styled code screenshots into one agent-native CLI. Built on ScreenCaptureKit via Swift CoreGraphics bridge.

Quick Start

go install github.com/mvanhorn/printing-press-library/library/developer-tools/agent-capture/cmd/agent-capture-pp-cli@latest
agent-capture doctor

Grant Screen Recording permission when prompted (System Settings > Privacy & Security > Screen Recording).

# Screenshot an app
agent-capture screenshot --app "Preview" demo.png

# Record a window for 10 seconds
agent-capture record --app "Preview" --duration 10 demo.mp4

# Record and convert to GIF in one command
agent-capture pipeline --app "Preview" --duration 5 demo.gif

# Stitch screenshots into animated GIF
agent-capture stitch step1.png step2.png step3.png -o demo.gif

Agent Usage

Every command supports --json for machine-parseable output.

# Discover capture targets
agent-capture list windows --json
agent-capture find "pull request" --json

# Screenshot with metadata
agent-capture screenshot --app "Finder" --json /tmp/shot.png

# Full evidence bundle
agent-capture evidence --app "Preview" --screenshots 3 --record 5 --output evidence/ --json

# Health check for CI preflight
agent-capture health --json

Exit codes: 0 = success, 1 = error.

Health Check

agent-capture doctor

Checks:

• macOS platform
• Screen Recording permission
• ffmpeg availability (optional, for video recording)
• Swift availability (for window enumeration)
• VHS availability (optional, for terminal recording)
• Remotion availability (optional, for simulated demo rendering)

Commands

Command	Description
list	List available windows and displays
screenshot	Capture a window, app, display, or region
record	Record video of a target
convert	Convert video to optimized GIF
stitch	Stitch screenshots into animated GIF
pipeline	Record + convert to GIF in one command
evidence	Full evidence bundle (screenshots + recording + GIF)
find	Fuzzy search window titles
watch	Interval screenshots for monitoring
diff	Visual diff against a baseline
batch	Screenshot multiple apps at once
ocr	Extract text from a window via Vision framework
preset	Save and load capture configurations
vhs	Run a VHS tape file for terminal recording
remotion render	Render a Remotion composition to video or GIF
remotion still	Render a single frame from a Remotion composition
doctor	Check permissions and environment
health	Machine-readable health check
permissions	Permission setup guide

Troubleshooting

"Screen Recording permission not granted"

System Settings > Privacy & Security > Screen Recording > enable your terminal app. Restart the terminal completely after enabling.

"listing windows" returns empty

Run agent-capture permissions for step-by-step setup. The first time you grant Screen Recording permission, you must restart your terminal.

GIF is too large

Use --max-size to auto-reduce: agent-capture convert demo.mp4 demo.gif --max-size 5mb. The tool will skip frames and reduce dimensions until the file fits.

ffmpeg not found

Install with brew install ffmpeg. Required for video recording and video-to-GIF conversion. Not needed for screenshots or frame stitching.

Cookbook

PR Evidence Workflow

# Take 3 screenshots at 2-second intervals
agent-capture watch --app "MyApp" --interval 2 --count 3 --output shots/

# Stitch into a GIF
agent-capture stitch shots/frame-*.png -o evidence.gif --frame-duration 3

# Or do it all at once
agent-capture evidence --app "MyApp" --screenshots 3 --record 8 --output evidence/

Save Common Settings

agent-capture preset save pr-evidence --duration 8 --fps 12 --width 640 --max-size 5mb

Diff Before/After

agent-capture screenshot --app "MyApp" before.png
# ... make changes ...
agent-capture diff --before before.png --app "MyApp" --output diff.png

Batch Multi-App Screenshots

agent-capture batch --apps "Finder,Safari,Terminal" --output screenshots/

Terminal Recording with VHS

# Run a VHS tape and produce a GIF
agent-capture vhs demo.tape

# With auto-reduce to hit a size limit
agent-capture vhs demo.tape output.gif --max-size 5mb

Simulated Demo with Remotion

# Render a Remotion composition as GIF
agent-capture remotion render --entry src/index.ts --comp MyDemo demo.gif

# Render a still frame for approval before full render
agent-capture remotion still --entry src/index.ts --comp MyDemo --frame 90 hero.png

# Render with size limit
agent-capture remotion render --entry src/index.ts --comp MyDemo --max-size 5mb demo.gif

Evidence Bundles by Tier

# Screen capture (default)
agent-capture evidence --app "MyApp" --screenshots 3 --record 5 --output evidence/

# Terminal recording
agent-capture evidence --tier vhs --tape demo.tape --output evidence/

# Simulated demo
agent-capture evidence --tier remotion --entry src/index.ts --comp Demo --output evidence/

Requirements

• macOS 12.3+ (ScreenCaptureKit)
• Xcode Command Line Tools (xcode-select --install)
• ffmpeg (optional, for video recording): brew install ffmpeg
• VHS (optional, for terminal recording): brew install vhs
• Remotion (optional, for simulated demos): npm install remotion @remotion/cli

Acknowledgments

Built with research from Peekaboo, macosrec, SwiftCapture, freeze, termshot, and Aperture.

Install via Hermes

From the Hermes CLI:

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-agent-capture --force

Inside a Hermes chat session:

/skills install mvanhorn/printing-press-library/cli-skills/pp-agent-capture --force

Install via OpenClaw

Tell your OpenClaw agent (copy this):

Install the pp-agent-capture skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-agent-capture. The skill defines how its required CLI can be installed.