agent-capture

agent-capture

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.