pp-agent-capture

Q: How do I install pp-agent-capture?

Run npx skills add https://github.com/mvanhorn/printing-press-library --skill pp-agent-capture in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/pp-agent-capture/ (personal) or .claude/skills/pp-agent-capture/ (project).

by mvanhornMarketing & SEO

macOS screen capture, window recording, GIF conversion, and agent evidence bundles from the terminal. Built on ScreenCaptureKit for window-level targeting ffmpeg cannot do. Use when the user wants a screenshot of a specific window or app, a screen recording, a GIF conversion, a before/after diff, an evidence bundle for a PR, OCR text from a window, a terminal VHS recording, a Remotion render, or wants to watch a UI for changes. Requires macOS Screen Recording permission on first run.

Installs: 280
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/mvanhorn/printing-press-library --skill pp-agent-capture

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads pp-agent-capture automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Agent Capture - Printing Press CLI

Prerequisites: Install the CLI

This skill drives the agent-capture-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:
```
npx -y @mvanhorn/printing-press-library install agent-capture --cli-only
```
Verify: agent-capture-pp-cli --version
Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):

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

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

When to Use This CLI

Reach for this when the user wants:

screenshot a specific window or app (screenshot, batch for multiple)
record video of a window, app, display, or region (record)
convert a recording to an optimized GIF (convert)
do a full capture + record + GIF pipeline in one command (pipeline)
diff against a baseline screenshot (diff) for before/after evidence
bundle screenshots + recording + GIF as evidence for a PR or bug report (evidence)
find the right window by fuzzy-matching its title (find)
stitch multiple screenshots into an animated GIF (stitch)
extract text from a window using macOS Vision OCR (ocr)
record a terminal session via VHS tape files (vhs)
render Remotion compositions to video or stills (remotion)
monitor a UI by periodic screenshots (watch)
save and replay capture configs (preset)

Skip it on non-macOS hosts; the CLI uses ScreenCaptureKit (macOS only). On first run it will prompt for Screen Recording permission; the permissions command guides that flow.

Argument Parsing

Parse $ARGUMENTS:

Empty, help, or --help -> show agent-capture --help
Starts with install -> CLI installation (no MCP server ships today)
Anything else -> Direct Use (map to the best command and run it)

Direct Use

Check installed: which agent-capture. If missing, offer CLI installation.
If permissions aren't granted, run agent-capture permissions first.
Use agent-capture list to see available capture targets (open windows, displays).
Use agent-capture find <text> to fuzzy-match a window title before capturing.
Execute with --json for structured output (agent-native default):
```
agent-capture <command> [args] --json
```

Notable Commands

Command	What it does
`screenshot`	Capture a window, app, display, or region
`record`	Record video of a window, app, display, or region
`pipeline`	Record + convert + optimize in one command
`convert`	Video -> optimized GIF (two-pass palette)
`diff`	Capture + diff against a baseline
`evidence`	Full bundle (screenshots + recording + GIF) for a PR
`batch`	Screenshot multiple apps in one invocation
`find`	Fuzzy search open window titles
`list`	List available capture targets
`ocr`	Extract text from a window using macOS Vision
`stitch`	Combine screenshots into an animated GIF
`vhs`	Run a VHS tape file for terminal recording
`remotion`	Render Remotion compositions
`watch`	Periodic capture for UI monitoring
`preset`	Save / load capture configs
`permissions`	Guide Screen Recording permission setup
`health`	Machine-readable CI / agent preflight

Run any command with --help for full flag documentation.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

Pipeable — JSON on stdout, errors on stderr
Filterable — --select keeps a subset of fields, with dotted-path support (see below)
Previewable — --dry-run shows the request without sending
Cacheable — GET responses cached for 5 minutes, bypass with --no-cache
Non-interactive — never prompts, every input is a flag

Filtering output

--select accepts dotted paths to descend into nested responses; arrays traverse element-wise:

<cli>-pp-cli <command> --agent --select id,name
<cli>-pp-cli <command> --agent --select items.id,items.owner.name

Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.

Exit Codes

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Target not found (no matching window or display)
4	Permissions missing (Screen Recording not granted)
5	Capture error (ScreenCaptureKit failure, ffmpeg failure)

FAQ

What does the pp-agent-capture skill do?

How do I install pp-agent-capture?

Run npx skills add https://github.com/mvanhorn/printing-press-library --skill pp-agent-capture in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/pp-agent-capture/ (personal) or .claude/skills/pp-agent-capture/ (project).

Which AI agents can use pp-agent-capture?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is pp-agent-capture safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains pp-agent-capture?

It is published by mvanhorn in mvanhorn/printing-press-library. It has 280 recorded installs.