<h1>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kajisho5/stepcap/main/docs/brand/banner-dark.png">
<img alt="stepcap" src="https://raw.githubusercontent.com/kajisho5/stepcap/main/docs/brand/banner-light.png" width="640">
</picture>
</h1>
**Record once. Get a how-to guide for humans and a SKILL.md for any agent. Local, no account, no Copilot.**
- Do a task once, in a desktop app or a browser: you get a guide for people (`guide.html`)
and a `SKILL.md` your AI agent can follow.
- Runs on your computer only, no account. (The free plans of browser-extension recorders
capture the browser only; see [How it compares](#how-it-compares).)
- The demo images are synthetic: the "Acme Tasks" app is drawn by
[`demos/build.py`](demos/build.py), no real data.
- Planned work lives in [ROADMAP.md](ROADMAP.md); issues are for bugs and questions.
`Fully local · Works offline · No account · Any app, browsers included · Windows, macOS, Linux`
[](https://github.com/kajisho5/stepcap/actions/workflows/tests.yml)
[](https://github.com/kajisho5/stepcap/actions/workflows/codeql.yml)
[](https://pypi.org/project/stepcap/)
[](https://pypistats.org/packages/stepcap)
[](https://github.com/kajisho5/stepcap/stargazers)
[](https://github.com/kajisho5/stepcap/commits/main)
[](.github/workflows/tests.yml)
[](LICENSE)
Do the task once and press F9. stepcap turns the recording into **two things**:
- **a guide for people** — `guide.md`, a single-file `guide.html` and a printable checklist,
with numbered frames, arrows and blur;
- **an Agent Skill for agents** — `SKILL.md` + annotated screenshots in the
[Agent Skills](https://agentskills.io/specification) format, so Claude Code, Codex or any
agent that reads skills can repeat the task, with typed values as `{{inputs}}`.
It is for anyone who writes "how to do X" manuals — IT support, help desks, back office,
trainers — and for anyone who wants their coding agent to do X next time.
- **Fully local**: nothing leaves your machine — no cloud, no sign-up, works with the network
unplugged.
- **Any app, browsers included**: web apps in Chrome / Edge / Firefox and desktop apps
(Excel, Zoom, OBS, device control software ...) in one recording — the free plans of
browser-extension tools cover the browser only.
- **Read in any browser**: `guide.html` is one self-contained file — no viewer, no login; the
editor (`stepcap edit`) also runs in your browser, served from 127.0.0.1.
- **Any agent, no lock-in**: the skill draft needs no LLM. If you want it generalised, stepcap
runs *your own* `claude` or `codex` CLI after showing what it will read — stepcap itself
sends nothing.
[日本語 README](README.ja.md)
## Quick start
```bash
pipx install stepcap # or: pip install stepcap (Python 3.11+)
stepcap doctor # checks permissions / hooks, prints fixes
stepcap record -o my-guide # do the task... then press F9
stepcap export my-guide --format both -o dist
# -> dist/guide/ guide.md, guide.html, checklist.html, images/
# -> dist/skill/<name>/ SKILL.md, references/step-NN.png
```
`stepcap build my-guide` writes the guide inside the session folder instead;
`stepcap skill my-guide -o skills --install claude` writes the skill and installs it for
Claude Code (see [For agents](#for-agents-stepcap-skill)).
Open `my-guide/guide.html` (one self-contained file — email it, or Ctrl+P → Save as PDF),
or paste `guide.md` + `images/` into GitHub, Notion or Confluence. `my-guide/checklist.html`
is a printable A4 tick list of the same steps for use on site.
While recording: **F9** stop · **F8** pause/resume · **F7** add a manual step with a note
(all configurable: `--hotkey-stop ctrl+alt+s`).
Prefer a single binary? Each [release](https://github.com/kajisho5/stepcap/releases)
ships `stepcap` executables for Windows, macOS and Linux (PyInstaller, no Python needed).
The `stepcap-voice-*` editions add voice notes (about 100 MB larger and slower to start);
on Linux they also need `sudo apt install libportaudio2` for the microphone.
### No terminal? Use the window
```bash
stepcap app # or double-click the release binary
```
Pick where to save, press **Start recording**, do the task, press **Stop** on the small
always-on-top bar (F9 / F8 / F7 keep working). Clicks on the bar itself are never steps, and
the bar is painted out of the screenshots. A wrong click? **↶ Undo** on the bar forgets the
newest step (its screenshot is deleted when you stop). When you stop, the window offers the
two results:
- **For AI agents: skill (SKILL.md)**: **Add to Claude Code** (copies it to
`~/.claude/skills/<name>/`; then type `/<name>` or just ask for the task),
**Add to Codex / Gemini CLI / Cursor** (the shared `~/.agents/skills/<name>/`), or
**Create SKILL.md** only. If the `claude`, `codex` or `gemini` CLI is installed, tick
*Generalise first* to let it rewrite the one-run draft into a general procedure (asks
before running). An installed skill with the same name is only replaced after you confirm.
- **For people: guide**: **Open guide**, **Printable checklist**, **Edit steps**.
**Export guide + skill** writes both next to the recording (`<name>-export/`) to share. The
window follows the system language (English / 日本語) and the system's light or dark mode
(`STEPCAP_THEME=light|dark` to override); it uses the bundled Noto Sans JP font.
Under **Recent recordings**, tick two or more recordings of the same task: **One skill from N**
merges them into one skill (the first one ticked is the reference, as in
`stepcap skill A B C`), **Compare the two** writes the `stepcap diff` report
(`<first>-export/diff-<second>.html`) and opens it.
The release binaries are not code-signed yet. Windows may show "Windows protected your PC"
(click **More info → Run anyway**); macOS may block the download (System Settings →
Privacy & Security → **Open Anyway**).
## Demo
**One recording → a guide for people (left) and a SKILL.md for agents (right):**
### Sample output — open it right here
Produced from the same synthetic recording (regenerated by [`demos/build.py`](demos/build.py)):
| | Open it | Made by |
|---|---|---|
| Guide for people | [guide.md](docs/demo/sample/guide/guide.md) · [guide.html](docs/demo/sample/guide/guide.html) · [checklist.html](docs/demo/sample/guide/checklist.html) | `stepcap export --format both` → `guide/` |
| Skill draft (no LLM) | [SKILL.md](docs/demo/sample/skill/create-project-move-card/SKILL.md) + [references/](docs/demo/sample/skill/create-project-move-card/references) | `stepcap skill` (`--agent none`, default) |
| Skill refined by Claude Code | [SKILL.refined-by-claude.md](docs/demo/sample/SKILL.refined-by-claude.md) | one real `stepcap skill --agent claude` run |
GitHub shows `.html` files as source: download `guide.html` / `checklist.html` and open them
in a browser.
<details>
<summary>Excerpt of the refined skill: typed values became inputs, a CLI/API check comes first,
each step says what to verify</summary>
```markdown
## Inputs
- `{{project_name}}` - name for the new project (e.g. "Q3 launch plan").
- `{{template}}` - board template to use, e.g. "Kanban board" (optional; the "Create" button defaults to "Kanban board" if left unset).
- `{{is_private}}` - whether the project should be marked private, true/false (optional; defaults to unchecked/public).
- `{{card_name}}` - name of the card to move (e.g. "Draft brief").
- `{{source_column}}` - the column the card currently sits in, e.g. "To do" (helps you find it; not otherwise needed).
- `{{target_column}}` - the column to move the card into, e.g. "In progress".
## Steps
Check first whether Acme Tasks exposes a CLI or API for creating projects and
moving cards (e.g. from its Settings or developer docs) - if so, prefer that
over the UI steps below. Otherwise, use the UI:
1. **Open Projects and start a new project.** In the Acme Tasks sidebar, click
"Projects", then click "+ New project" (top right).
[step 1](references/step-01.png)
- Check: a "New project" dialog opens with a "Project name" field, a
"Template" dropdown, and a "Private project" checkbox.
```
</details>
Real output (long file lists cut, prompt and paths shortened):
```console
$ stepcap export demo --format both -o dist --name create-project-move-card
Guide dist/guide: 15 files
Skill 'create-project-move-card': 12 steps -> dist/skill/create-project-move-card (62 lines, ~698 tokens)
valid (Agent Skills spec + no secrets)
$ stepcap skill demo -o skills --name create-project-move-card --agent claude
claude will be able to read these files (secrets already masked):
skills/create-project-move-card/SKILL.md
skills/create-project-move-card/_context/INSTRUCTIONS.md
skills/create-project-move-card/_context/events.jsonl
skills/create-project-move-card/_context/steps.json
skills/create-project-move-card/references/step-01.png ...
Command: claude -p '...' --permission-mode acceptEdits --allowedTools Read,Edit,Write
Run it? [y/N] y
Skill 'create-project-move-card': 12 steps -> skills/create-project-move-card (98 lines, ~1223 tokens)
valid (Agent Skills spec + no secrets)
$ stepcap shell demo # second terminal, while `stepcap record -o demo` runs
stepcap: commands in this bash are added to demo (secrets masked, output not recorded). Type `exit` to finish.
[stepcap] ~/work$ git status --short
fatal: not a git repository (or any of the parent directories): .git
[stepcap] ~/work$ export GITHUB_TOKEN=ghp_Q1w2...
[stepcap] ~/work$ exit
stepcap: 2 command(s) recorded in demo/terminal.jsonl
$ cat demo/terminal.jsonl
{"kind":"terminal","time":1790262966.16,"command":"git status --short","cwd":"/home/you/work","exit":128}
{"kind":"terminal","time":1790262966.162,"command":"export GITHUB_TOKEN=[REDACTED:github-token]","cwd":"/home/you/work","exit":0}
```
| Generated `guide.html` (light / dark, TOC, print CSS) | `stepcap edit` (reorder, rename, blur) |
|---|---|
|  |  |
The clicked button, field or card gets a numbered frame around it. stepcap finds the
element's edges in the screenshot itself: no OCR, no accessibility API. When it can't tell
(text on a plain page, gradients), it falls back to a numbered ring on the click point, and
you can draw or remove frames in `stepcap edit` (`--marker ring` always uses rings). Small
targets such as checkboxes also get an arrow pointing at them, `--spotlight` dims
everything except the target, and you can draw extra arrows in `stepcap edit`. Drags get
an arrow, scrolls a direction arrow, shortcuts a key-cap label. `--zoom 640` makes the crop
around the click the main image and adds a full-screen thumbnail:
| Frame on the clicked button (`step-click`) | Drag (`step-drag`) | `--zoom 640` |
|---|---|---|
|  |  |  |
| `--spotlight` + automatic arrow on a small checkbox | Printable `checklist.html` |
|---|---|
|  |  |
All images above are generated by [`demos/build.py`](demos/build.py) from a synthetic
session (`stepcap simulate`), so they are reproducible and contain no real data.
## What it does
- **Records the whole desktop**, not just a browser tab: clicks (single / double /
right), drags, scrolls (aggregated), typing, Enter/Esc, shortcuts like Ctrl+S, plus
manual notes (F7). Multi-monitor, HiDPI/Retina aware.
- **Screenshot per step** of the monitor under the cursor (`--monitor all` for every
screen), taken on mouse-down so it shows what the reader must find. Saved on a
background thread; click→saved latency is measured and logged (target < 300 ms).
- **Titles steps from the clicked element** on Windows (UI Automation) and macOS
(Accessibility): `Click the "Save" button`, `Type into the "Project name" field`,
`Choose "Rename"` — and frames the element with its exact rectangle. Where the app gives
no name (or on Linux), `stepcap build` reads the text of the clicked control from the
screenshot on this computer — Windows and macOS built-in OCR, `tesseract` on Linux — so
the step still says `Click "Create"`; for a text field it uses the label above it.
`build --no-ocr` turns this off; the window name (`Click in "Settings"`) is the last
resort. Password fields never report a name and typing into them is always masked.
English or Japanese (`--lang ja`).
- **Reuses identical screenshots**: consecutive steps on the same screen (≥ 98 % same
area) share one image, so blurring it once covers all of them.
- **Outputs** `guide.md` + `images/`, a single-file `guide.html` (table of contents,
light/dark, print CSS), a printable A4 `checklist.html` (tick box, small crop around the
target, notes column, date / operator / sign-off fields) and `steps.json` — the editable
source of truth.
- **Share with a password** (`stepcap share`, or *Share with a password* in the window): one
HTML file encrypted with AES-256-GCM (key from the password via PBKDF2-SHA256, 600,000
rounds). It opens in any browser, offline, after the password (decrypted with the
browser's WebCrypto). No expiry date: a standalone file cannot enforce one.
- **Compare two recordings** (`stepcap diff A B -o report.html`): steps are matched in
order by what they did (the element's name, else app + window), so moved buttons and
reworded titles still match. It lists steps only in A, only in B, and matched steps whose
screen looks different or where a different value was typed, plus URLs and terminal
commands that differ; the HTML report puts the screenshots side by side. Use it when the
app changed (record again, see which steps to update) or to check what an agent did.
- **How-to video, optional** (`stepcap video SESSION_DIR`): an MP4 of the guide, each
step's image on screen for a few seconds (`--seconds`, longer for long texts) with its
title and description as a caption below it, Japanese included (the bundled Noto Sans JP
font). Every media step is done by [ffmpeg-skill](https://github.com/kajisho5/ffmpeg-skill)
(its `sequence` and `caption` tools, then its `check` on the file); stepcap never runs
FFmpeg itself. It is the only command that needs ffmpeg-skill: clone it and pass
`--ffmpeg-skill DIR` or set `STEPCAP_FFMPEG_SKILL_DIR` (FFmpeg 6.1+ on PATH); without it
`stepcap video` stops with that message and nothing else changes. No audio track.
- **Rebuilds are idempotent**: edits in `steps.json` (by you, `stepcap edit` or an AI
agent) are never overwritten; `--reset` starts over.
- **Frames the clicked element** (button, input, checkbox, card) detected from the
screenshot; falls back to a ring when unsure.
- **Arrows and spotlight**: automatic arrow to small targets, optional `--spotlight` that
dims the rest of the screen, hand-drawn arrows in the editor.
- **Local editor** (`stepcap edit`): drag to reorder, delete, rename, describe, draw or
remove highlight frames, draw arrows, toggle frames / auto arrows / spotlight, blur
rectangles (applied to `work/` copies — `raw/` originals stay untouched), rebuild.
- **Context for agents**: app / window switches are always logged; with `--record-urls` the
front browser tab's URL (Windows: Chrome, Edge and other Chromium browsers via UI
Automation, not Firefox; macOS: Safari, Chrome, Edge, Arc; query strings dropped unless `--keep-query`), with `--record-clipboard` copied text (length + first 80 characters).
These never become steps; `stepcap skill` uses them ("Browser at ...", "Then: copied ...").
- **Voice notes** (`--voice`, off by default): say what you are doing and why while you
record. The microphone is transcribed **on this computer** (faster-whisper, CPU) when
you stop; the text lands in each step's description and in the skill ("Narration: ...",
and the Goal when you explained it before the first click). `audio.wav` is deleted after
transcription unless `--keep-audio`; nothing said while paused is kept. Needs
`pip install "stepcap[voice]"` or the voice edition of the binary; the speech model
(`--voice-model base`, ~150 MB; `small` is better for Japanese) is downloaded once from
Hugging Face and then works offline.
- **Private by default**: typed text is *not* stored unless `--record-typing`;
always masked in password/login windows; `--exclude-app` skips apps entirely
(no screenshot). No network access at all (except the one-time speech model download
with `--voice`).
### What it doesn't do (v0.1)
- **Wayland** (Linux) — X11 only; stepcap stops with an explanation on Wayland.
- **AI-written sentences** — titles come from element names (accessibility APIs, else OCR
of the clicked control); for full sentences use the bundled agent skill or
`stepcap skill --agent claude|codex`. Linux accessibility names (AT-SPI) are not
supported yet (OCR is).
- **Screen video**: no screen recording or narration audio (`stepcap video` turns the
screenshots into a captioned slideshow); no cloud sharing or team workspaces.
- Direct PDF export — print `guide.html` to PDF from any browser.
- **Transcripts** — voice notes only become step descriptions; for a transcript (JSON, SRT/VTT,
word timings) of a recording or any audio/video file, use
[transcription-skill](https://github.com/kajisho5/transcription-skill) (why: [docs/DECISIONS.md](docs/DECISIONS.md)).
## Why
- Windows' built-in **Steps Recorder** (psr.exe) is deprecated by Microsoft (banner since the
February 2024 update; still starts as of 2026-09, no removal date). Its replacements
(Snipping Tool, Game Bar, Clipchamp) record video, not steps.
- Microsoft's **skill-recorder** proved that "record once → agent skill" is useful, but it needs
a GitHub account with Copilot access, sends the event timeline and screen images to GitHub's
cloud when you analyze, and targets Microsoft Scout / Copilot Cowork / Copilot Studio.
stepcap fills both gaps: the guide *and* the skill from one local recording, on any OS, for
any agent.
## How it compares
Facts as published by each project (checked 2026-09-24, Claude row 2026-09-25; follow the links).
| | Runs on | Guide for people | SKILL.md for agents | Account | Sends data |
|---|---|---|---|---|---|
| **stepcap** | Windows, macOS, Linux (X11) | ✅ MD, HTML, checklist | ✅ any agent (Claude Code, Codex, ...) | none | nothing (the optional agent step is your own CLI) |
| [skill-recorder](https://github.com/microsoft/skill-recorder) | macOS, Windows 11, Ubuntu | — (skills and automations) | ✅ for Microsoft Scout / Copilot Cowork / Copilot Studio | GitHub account with Copilot | events and screen images to GitHub's cloud on Analyze |
| [Claude "Record a skill"](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills) | Claude for Mac (Cowork); not on Windows | — | ✅ for Claude (saved to your Claude skills) | Pro, Max or Team plan | the recording (screen, input, voice) is reviewed by Claude; video and audio are not retained, screenshots are |
| [OpenSteps](https://github.com/ebanez8/openstep) | Windows 10+ | ✅ MD, HTML | — | none | none (local) |
| [BetterStepsRecorder](https://github.com/Mentaleak/BetterStepsRecorder) | Windows | ✅ HTML, RTF, ODT | — | none | none documented |
| [Scribe](https://scribe.com/pricing) | browser; desktop apps on Pro | ✅ (PDF/HTML/Markdown export on Pro) | — | required | cloud |
| [Tango](https://www.tango.ai/pricing) | browser; desktop on Pro | ✅ (export on Pro) | — | required | cloud |
| [Windows Steps Recorder](https://support.microsoft.com/en-us/windows/apps/steps-recorder-deprecation) | Windows | ✅ .zip with an .mht file (last 25 screenshots by default) | — | none | none; **deprecated** |
Free plans of Scribe (Basic) and Tango capture web apps in the browser only and have no
export; paid plans start at $25 / $22 per user per month (yearly).
## Commands
```text
stepcap record [-o SESSION_DIR] [--monitor all|active] [--record-typing]
[--exclude-app NAME ...] [--hotkey-stop F9] [--hotkey-pause F8]
[--hotkey-manual F7] [--note-prompt auto|gui|terminal|none]
[--record-urls] [--keep-query] [--record-clipboard]
[--voice [--voice-model base] [--voice-language ja] [--keep-audio]]
[--dry-run] [--json]
stepcap build SESSION_DIR [-f md,html,checklist] [--zoom 800] [--width 1600] [--lang en|ja]
[--title "..."] [--marker box|ring] [--[no-]spotlight] [--[no-]auto-arrows]
[--image-format webp|jpeg|png] [--quality 85] [--reset]
[--dry-run] [--json]
stepcap edit SESSION_DIR [--port 8765] [--host 127.0.0.1] [--no-browser]
stepcap skill SESSION_DIR [SESSION_DIR ...] -o OUT_DIR [--name NAME] [--agent none|claude|codex|gemini|AGENT]
[--install none|claude|agents|codex|gemini|cursor|AGENT] [--scope user|project] [--yes] [--force]
[--dry-run] [--json]
stepcap export SESSION_DIR --format guide|skill|both -o OUT_DIR [--name NAME]
[--agent none|claude|codex|gemini|AGENT] [--lang en|ja] [--yes] [--force] [--dry-run] [--json]
stepcap share SESSION_DIR -o FILE.html [--file guide|checklist] [--password-stdin]
stepcap check-skill SKILL_DIR [--session SESSION_DIR [--min-coverage 0.8]] [--json]
stepcap diff SESSION_A SESSION_B [-o report.html] [--fail-on none|missing|any] [--json]
stepcap transcribe SESSION_DIR [--model base] [--language ja] [--keep-audio] [--json]
stepcap schema [session|event|steps|terminal|voice] [--path]
stepcap video SESSION_DIR [-o FILE.mp4] [--seconds 4] [--size 1920x1080] [--fps 10]
[--platform youtube] [--fast] [--lang en|ja] [--ffmpeg-skill DIR] [--json]
stepcap contract [--json] # machine-readable contract
stepcap agents [--json] # agents you can --install / --agent
stepcap mcp [--root DIR ...] # MCP server for agents (stdio)
stepcap shell SESSION_DIR [--shell bash|zsh] [--json] # macOS / Linux
stepcap simulate EVENTS.json -o SESSION_DIR [--record-typing] [--json]
stepcap app [--lang en|ja] # window: start / stop / edit / export
stepcap doctor [--json]
```
Every command exits non-zero on failure. `--json` gives machine-readable output.
stepcap never overwrites an existing, non-empty session directory, and `build`
never touches `raw/`.
Session layout:
```
SESSION_DIR/
session.json metadata (start/end, OS, monitors, options, latency)
events.jsonl one event per line: ts, x/y (absolute + monitor-relative + image px),
monitor, button, click_type, window_title, app_name, screenshot
raw/ original PNG screenshots (never modified)
work/ editable copies (blur)
steps.json canonical steps (titles, descriptions, image paths, coordinates)
guide.md, images/, guide.html
```
The formats are documented as JSON Schemas (draft 2020-12) shipped with stepcap:
`stepcap schema steps` prints one, `stepcap schema --path` shows where they are
([source](src/stepcap/schemas/)). Other tools can read and validate sessions with them;
unknown keys are allowed so newer versions can add fields.
## Permissions
`stepcap doctor` tells you exactly what is missing. Short version:
- **macOS** — give the terminal app *Accessibility*, *Input Monitoring* and
*Screen Recording* permission, then restart it.
- **Windows** — nothing to grant. Input from elevated ("Run as administrator")
windows is only visible if stepcap is elevated too.
- **Linux** — X11 session required (not Wayland). `xdotool` is optional for better
window names.
Details: [docs/permissions.md](docs/permissions.md).
## For agents: `stepcap skill`
```bash
stepcap skill my-guide -o skills # draft, no LLM: skills/<name>/SKILL.md
stepcap skill my-guide -o skills --agent claude # let your Claude Code CLI generalise it
stepcap skill my-guide -o skills --install claude --scope project # + .claude/skills/<name>/
stepcap skill my-guide -o skills --install agents # + ~/.agents/skills/ (Codex, Gemini CLI, Cursor)
stepcap check-skill skills/<name> # validate after editing by hand
```
- **Draft (`--agent none`, default)**: deterministic, offline. Frontmatter (`name`,
`description`), `## Goal` (from your F7 notes, else `TODO`), `## Inputs` (every typed value
becomes a variable named after its field, e.g. `{{project_name}}`, else `{{input_N}}`;
rename it or mark it as a fixed value in `stepcap edit`),
numbered `## Steps` with app, window and `references/step-NN.png` (annotated, blur applied),
and `## Notes for the agent` (prefer CLI/API over clicks; confirm before deleting, sending,
paying).
- **Refine (`--agent claude|codex|gemini`)**: runs `claude -p`, `codex exec` or `gemini -p`
in the skill folder with [`prompts/skill_refine.md`](src/stepcap/prompts/skill_refine.md).
Before it runs, stepcap lists every file the agent can read and asks `y/N` (`--yes` skips,
`--dry-run` only lists). stepcap makes no network request itself; where your agent sends
data depends on your agent's settings.
- **Install (`--install ...`)**: copies the folder to where the agent loads skills from
(`--scope user` = your home folder, `project` = the current folder). Never overwrites an
existing skill without `--force`.
| `--install` | Folder | Loaded by |
|---|---|---|
| `claude` | `.claude/skills/` | Claude Code (Cursor reads it too) |
| `agents` (= `codex`) | `.agents/skills/` | Codex, Gemini CLI, Cursor |
| `gemini` | `.gemini/skills/` | Gemini CLI |
| `cursor` | `.cursor/skills/` | Cursor |
Folders as documented by [Claude Code](https://code.claude.com/docs/en/skills),
[Codex](https://learn.chatgpt.com/docs/build-skills),
[Gemini CLI](https://geminicli.com/docs/cli/skills/) and
[Cursor](https://cursor.com/docs/skills) (checked 2026-09-25).
- **Other agents (`agents.toml`)**: add your own, or change a built-in command, without
touching stepcap. `stepcap agents` lists them and prints where the file goes
(`~/.config/stepcap/agents.toml`, `%APPDATA%\stepcap\agents.toml` on Windows, or
`$STEPCAP_AGENTS_FILE`):
```toml
[agents.myagent]
label = "My agent"
user_dir = "~/.myagent/skills" # --install myagent
project_dir = ".myagent/skills" # --install myagent --scope project
refine = ["myagent", "run", "{prompt}"] # --agent myagent (optional)
```
`{prompt}` points the agent at `_context/INSTRUCTIONS.md`; `{skill_dir}` and `{images}`
(comma-separated annotated screenshots; the argument is dropped when there are none) are
also available. Agents from this file get their own "Add to …" button in `stepcap app`.
- **Always validated**: Agent Skills frontmatter rules, name = folder name, < 500 lines,
~5000 tokens, every `references/` link exists, and no secret patterns (GitHub / AWS /
OpenAI / Anthropic keys, JWTs, passwords in URLs, card numbers). Exit code 1 if not.
- **Checked against the recording**: after a rewrite (by you or `--agent`), stepcap lists
what the recording showed but SKILL.md no longer mentions: apps, clicked buttons and
fields, `{{inputs}}`, URL hosts, terminal commands and F7 notes. It is a review hint
(a skill may rightly replace clicks with a CLI call), shown after `--agent` runs, in the
window, and by `stepcap check-skill SKILL_DIR --session SESSION_DIR` (`--min-coverage 0.8`
makes it fail below 80 %).
- **Terminal steps**: run `stepcap shell my-guide` in a second terminal while recording.
Commands typed there (not their output) are added with their exit status, secrets
masked, and show up as "Ran in a terminal: `...`" in the skill. bash and zsh on macOS /
Linux; Windows PowerShell is not supported yet. Start a command with a space to keep it
out (when your shell ignores such commands in history).
- **Press F7 while recording** to add notes like "why": they become the skill's Goal and are
the most useful thing you can give an agent.
- **Several recordings of the same task**: `stepcap skill run1 run2 run3 -o skills`. The
first is the reference (its steps and screenshots); the others are matched with it the
way `stepcap diff` does. Steps done in only some runs get "Optional: done in 2 of 3
recordings", each input lists what was typed in every run (or "the same in all 3
recordings", a hint that it may be a fixed value), and steps only the other runs did are
listed under "Differences between recordings" with their position. The skill is checked
against every recording. Typed values appear only when recorded with `--record-typing`.
### Check what an agent did: `stepcap diff`
Record while the agent does the task, then compare with the recording its skill came from:
```bash
stepcap record -o agent-run # start before the agent, stop (F9) after it
stepcap shell agent-run # optional, macOS / Linux: the terminal the agent uses
stepcap diff my-guide agent-run -o report.html --fail-on missing
```
- `stepcap record` sees the mouse and keyboard input the agent's automation sends (checked
with XTEST input on Linux; not checked with agents on Windows / macOS). An agent that
uses an API or CLI instead shows up only through `stepcap shell` commands, as extra
commands and missing clicks.
- `--fail-on missing` exits 1 when a step of your recording was not done; `--fail-on any`
on any difference. Different screens and values are normal when the agent worked on
other data: read the report rather than expecting "identical".
### For agents over MCP: `stepcap mcp`
Let an agent use your recordings directly. `stepcap mcp` is an MCP server (stdio) with seven
tools: `list_sessions`, `get_steps` (titles, clicked elements, inputs, URLs, commands,
narration), `step_image` (the annotated screenshot of a step, as an image),
`build_guide`, `make_skill` (write and optionally install a skill, from one or several
recordings), `check_skill` (validate + compare with the recording) and `compare_recordings`
(what `stepcap diff` reports). Starting a recording is not a tool: capturing your
screen stays your decision. The agent can only use folders under `--root` (default:
`~/Documents/stepcap`, where the window saves, and the current folder).
```bash
pip install "stepcap[mcp]"
claude mcp add stepcap -- stepcap mcp # Claude Code
codex mcp add stepcap -- stepcap mcp # Codex
gemini mcp add stepcap stepcap mcp # Gemini CLI
# Cursor: ~/.cursor/mcp.json -> {"mcpServers": {"stepcap": {"command": "stepcap", "args": ["mcp"]}}}
```
Then ask, for example: *"Look at my latest stepcap recording and turn it into a skill that
uses the CLI where possible."* Commands from each tool's MCP docs
([Claude Code](https://code.claude.com/docs/en/mcp),
[Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli),
[Gemini CLI](https://geminicli.com/docs/tools/mcp-server/),
[Cursor](https://cursor.com/docs/context/mcp), checked 2026-09-25). Verified with Claude
Code: it listed the recordings, read the steps and described step 2 from `step_image`.
## Let your coding agent write the guide text
Automatic titles are template based (`Click in "Settings"`). For human-quality text,
point Claude Code, Codex or Cursor at the session: the agent looks at each annotated
screenshot, writes a title and a 1–2 sentence description into `steps.json`, and runs
`stepcap build`. The instructions are in [`skills/stepcap/SKILL.md`](skills/stepcap/SKILL.md).
```bash
# Claude Code: install the skill for your user
mkdir -p ~/.claude/skills && cp -r skills/stepcap ~/.claude/skills/
# then ask: "Use the stepcap skill on ./my-guide"
```
For other agents, reference `skills/stepcap/SKILL.md` in your prompt or rules file.
No OCR or API key is needed: the agent reads the images itself.
## FAQ
**Is anything uploaded?** No. stepcap makes no network requests (`--agent claude|codex` runs
your own agent CLI, only after you confirm); the editor listens
on 127.0.0.1 only (with Host/Origin checks). Your screenshots stay in the session folder.
**Are my passwords recorded?** Typed text is not stored by default — only
"typed 12 characters". Screenshots can still show what is on screen: blur it in
`stepcap edit`, or use `--exclude-app` for password managers.
**Are secrets masked?** In text, yes: typed text (with `--record-typing`), window titles,
notes and everything in the skill are scanned for GitHub / AWS / OpenAI / Anthropic keys,
JWTs, passwords in URLs and card numbers and saved as `[REDACTED:kind]`. Pixels are not
scanned — blur screenshots that show secrets in `stepcap edit`.
**Does it run in the browser, without installing?** The editor and the guides do; the
recorder cannot. A web page can only see clicks inside its own tab, so desktop-wide
recording needs a small local program (`pipx install stepcap` or the release binary).
Web apps are recorded like any other window.
**Can I get a PDF?** Open `guide.html` and print to PDF; the print stylesheet keeps
each step on one page where possible.
**Can I try it without recording?** Yes:
`python tests/fixtures/make_events.py > ev.json && stepcap simulate ev.json -o demo && stepcap build demo`.
**Why is a step titled just "Click"?** The window name could not be read (see
`stepcap doctor`; on macOS grant Screen Recording). Edit it in `stepcap edit` or let an
agent do it.
**`pip install` fails on Linux building `evdev`.** Install `python3-dev` and `gcc`, or
use the release binary.
## Roadmap
See [ROADMAP.md](ROADMAP.md) (PDF export, Wayland via portals, redaction presets,
localization and more). An issue is opened when an item is being discussed.
## Contributing
```bash
git clone https://github.com/kajisho5/stepcap && cd stepcap
python -m pip install -e ".[dev]"
python -m pytest && ruff check . && ruff format --check .
python demos/build.py # regenerate README images (add --browser for UI shots)
```
CI never uses real input hooks: `stepcap simulate` drives the same event pipeline with
synthetic input. Decisions are logged in [docs/DECISIONS.md](docs/DECISIONS.md).
## Credits
The "record once, get an agent skill" idea was popularised by Microsoft's
[skill-recorder](https://github.com/microsoft/skill-recorder). stepcap shares no code with
it (different language and design); it only credits the idea.
## License
[MIT](LICENSE). Runtime dependencies: Pillow (MIT-CMU), mss (MIT), pynput (LGPL-3.0,
used as an unmodified library), sv-ttk (MIT); the window's Noto Sans JP font is SIL Open Font
License 1.1 — see [docs/THIRD_PARTY.md](docs/THIRD_PARTY.md).