cap-tools

Automation and tooling for Cap (CapSoftware/Cap) screen recordings: drive a recording end to end from an agent or script (with automatic zoom, no Studio required), and turn a finished recording into an illustrated step-by-step guide.

Two complementary halves, one capt CLI:

	Record	Guide
What	Automate a screen recording, with auto-zoom built from real click/keystroke markers	Turn a recording into an illustrated HTML/Markdown guide
When	Before you have a recording	After you have one
Platforms	macOS/Linux (native), WSL (bridges to Windows)	Any platform
Docs	docs/superpowers/specs/	guide/README.md

Quick Start

uv sync
uv run capt --help

capt preflight --marker-source steps+global-capture   # check readiness
capt record https://example.com --out recordings --screen <id> \
  --marker-source steps+global-capture --export-to demo.mp4 --json
capt guide path/to/recording.cap --format both

--screen <id> records the full display; pass --window <id> instead (both from cap targets --json) to capture just one window — the two are mutually exclusive.

For a live, narrated walkthrough (macOS only — no fixed length, no --steps), capt demo is a shortcut that auto-detects the screen and microphone and keeps recording until you stop it from Cap's own UI (menu bar icon) — not a keypress, so nothing you type or press during the demo itself can end the recording early:

capt demo my-walkthrough                     # screen + mic auto-detected
capt demo my-walkthrough --window <id>       # one window instead of the full screen
capt demo my-walkthrough --no-mic            # skip narration audio

That's shorthand for capt record --marker-source global-capture --until-stopped, with --mic "<device>" / --system-audio / --camera <id> also available directly on capt record (device names/ids from cap targets --json) if you want more control than capt demo gives you.

capt record runs in-process on macOS/Linux — no browser-automation hop required. On WSL it bridges to a Windows-hosted Cap Desktop install, since screen capture has to target the Windows desktop (see skills/cap-cli and source skills/cap-cli/setup.sh).

Full command reference: capt <command> --help for any of record, guide, export, assemble, preflight, config, zoom.

Install a skill into any agent

Skills under skills/ follow the open agentskills.io spec — portable across Claude Code, Cursor, Codex, and any other skills-compatible agent. Install one with a single npx call, no local clone required:

npx github:kylebrodeur/cap-tools --list                              # see what's available
npx github:kylebrodeur/cap-tools cap-cli --target claude --dry-run   # preview
npx github:kylebrodeur/cap-tools cap-cli --target claude             # apply
npx github:kylebrodeur/cap-tools --all --target cursor               # install every skill found

--target is one of codex, claude, cursor — the same targets and path convention as Cap's own cap agents install. See bin/install-skill.js.

Structure

├── capt/                             # the capt CLI package
│   ├── cli.py                        # entry point: record/guide/export/assemble/preflight/config/zoom
│   ├── record/                       # shared beat-cycle core (beat.py, steps.py, macos_capture.py)
│   ├── guide/                        # ingest -> (transcribe) -> (structure) -> render pipeline
│   ├── zoom.py, config.py, export.py # zoom-segment building, project-config, cap export wrapper
│   └── preflight*.py                 # readiness gates, platform-dispatched
├── win/                              # Windows-side beat runner (invoked from WSL)
├── skills/cap-cli/                   # agentskills.io-compliant skill: bridges `cap` from WSL
├── bin/install-skill.js              # npx installer for skills/*
├── tests/                            # pytest suite (uv run pytest tests/)
├── docs/                             # design specs, plans, research, and reference material
│   └── superpowers/                  # brainstorming specs + implementation plans
├── guide/                            # earlier guide-pipeline prototype + working projects
└── upstream/                         # draft materials for a potential CapSoftware/Cap contribution

Requirements

• macOS/Linux: Python 3.11+, uv, Cap Desktop installed with its CLI on PATH (curl -fsSL https://cap.so/install-cli.sh | sh).
• WSL: the above, plus Cap Desktop installed on a Windows host and WSL interop enabled — screen capture always targets the Windows desktop.
• Guide tool extras: none required. Frame extraction prefers Cap's own cap export-preview when the CLI is available — it renders through Cap's native pipeline, so screenshots reflect the project's actual zoom/crop/background effects — and falls back automatically to vendored PyAV (no system ffmpeg/ffprobe) when it isn't. A local OpenAI-compatible endpoint (e.g. Ollama) if using --ai step-text generation.
• capt assemble only: ffmpeg on PATH (multi-clip stitching with voiceover/captions still shells out to it).

Run the test suite with uv run pytest tests/.

Contributing

See CONTRIBUTING.md.

License

MIT