Cap
Apps & AutomationcapCap is an Agent Skill for apps & automation published in the CapSoftware/Cap repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Record the screen, capture screenshots, and create shareable video links from the command line using the Cap CLI. Use when the user wants to record a screen demo or bug repro, capture a screenshot of a screen/window, produce a Loom-style shareable video link, or automate/script screen recording. Requires the `cap` command to be installed (Cap Desktop, https://cap.so).
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/CapSoftware/Cap/blob/HEAD/apps/cli/skill/cap/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cap, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Cap CLI
cap is a command-line screen recorder built to be driven by agents. Every command takes --json for
machine-readable output on stdout; stderr stays human-readable; failures exit non-zero and, in --json
mode, print a final object/event with an error field.
cap guide --json is the authoritative contract (output convention, env vars, exit codes, and every
command's output mode + event tags). Prefer it over guessing, and cap <command> --help for flags.
First: check it's available
cap doctor --json
- If
capis not found, it isn't installed. Tell the user to install Cap Desktop from https://cap.so/download, then enable the CLI (Settings → Command Line), or runcurl -fsSL https://cap.so/install-cli.sh | sh(Windows:irm https://cap.so/install-cli.ps1 | iex). - Read
captureReadyandpermissions.screenRecordingfrom the output. On macOS, recording fails until Screen Recording permission is granted in System Settings.
Discover capture targets
cap targets --json # screens, windows, cameras, mics
Use a screen's id (or a window's id) for --screen/--window, a camera's deviceId for --camera,
and a mic's name for --mic.
Record (background lifecycle — the usual agent pattern)
When you don't know the duration in advance: start detached, do the work, then stop.
cap record start --screen <id> --json --detach # -> {"type":"started","recordingId","pid","path"}
# ... perform the actions to capture ...
cap record stop --id <recordingId> --json # -> {"type":"stopped","path","recordingMetaExists":true}
cap record status --json # list active sessions
A stopped event is only a complete recording when recordingMetaExists is true.
Fixed-length alternative (no detach): cap record start --screen <id> --duration 10 --json.
Screenshot
cap screenshot --screen <id> --path shot.png --json # -> {"path","width","height"}
Export and share
cap project validate <path.cap> --json # confirm the recording is complete
cap export <path.cap> --output out.mp4 --json # render (here --format means container: mp4|gif|mov)
cap upload out.mp4 --json # -> {"type":"uploaded","id","link"}
cap upload authenticates automatically by reusing the user's Cap Desktop login — check with
cap auth status --json. If it reports authenticated:false, tell the user to sign into Cap Desktop,
or set CAP_API_KEY (a Cap auth key from Settings) for headless use. cap upload <path.cap> --export --json exports then uploads in one step.
Automations
Automations are trigger -> (conditions) -> actions rules authored in Cap Desktop (Settings →
Automations) and shared with the CLI. After cap screenshot, a cap record finish, and cap upload,
the CLI evaluates the matching rules and runs their actions (save to a folder, run a command, send a
webhook, export, etc.).
cap automations list --json # the rules the CLI will honor
Desktop-only actions (copy to clipboard, OCR, notifications, open editor) are skipped on the CLI; all
others run. cap doctor --json reports the configured rule count under automations.
Conventions to rely on
- Add
--jsonto any command; it overrides each command's--format. - Detect failure with a single check: the process exits non-zero and the JSON carries an
errorfield. recordandexportstream newline-delimited JSON (NDJSON) events; everything else returns one object.doctor,project validate, andrecordings listare reports — branch on their fields (ok/captureReady,valid), not just the exit code.