asciinema
Script the session, drive it, gate the cast, prove every scene from the cast, then publish. Never record a live shell.
What this skill is - and isn't
| Situation | Owner |
|---|---|
README or PR demo of a CLI or TUI, .cast + GIF, asciinema.org upload |
this skill |
| Recording a browser flow | agent-browser |
| Produced video, motion graphics, voiceover | video |
| Proving a TUI change frame by frame (no recording) | the project's own screen harness |
Hard rules
- Sample data only. A public demo runs against a fixture server or sandbox account with generic content. The session script points the tool at an isolated config dir (
XDG_CONFIG_HOMEin a temp dir, fake auth) so it cannot read the real one. - Never record an interactive shell. A real prompt and rc files leak user, host, and paths. The session script prints a fake
$prompt and types each command. - The leak gate is not optional.
record.shrewrites the headercommand(asciinema stores the full command line, absolute paths included) and fails on home paths, loopback addresses, token names, and every--denystring. A failure means fix the script, never edit around the gate. - Prove scenes from the cast. Run
cast-check.py --expectwith one marker per scene before calling a recording done. A missing marker means the choreography drifted. - Upload is outward-facing. Confirm with the user before
asciinema uploador any visibility change. Uploads default to unlisted.
Workflow
- Build first. Build the binary under demo before recording; compile output inside the cast is noise. Start the fixture server if the tool needs one.
- Write the session script. Copy
assets/demo-session.sh. Setup must be silent: every byte printed lands in the cast, even ifclearfollows. The script sets its own env from its arguments, because in TUI mode it runs with the tmux server's environment, not the caller's. Onenoteper scene,clearbetween scenes, about 90 seconds in total. - Write the drive script (TUI only). It is sourced once
--readytext is on screen and gets these helpers:k KEY...- one argument per key. A single character is sent literally (/,?,;); longer names are tmux keys (Enter,Escape,Up,C-c).KEY_DELAYpaces it (default 0.28s).lit TEXT- types into an open prompt one character at a time (TYPE_DELAY, default 0.07s).wait_for TEXT [SECS]- blocks until the text is on screen. Wait on stable UI text, thensleeponly for viewer pacing.- The script must end by quitting the TUI, so the session script reaches its closing scene.
- Record.
Withoutbash scripts/record.sh --session demo-session.sh [--drive drive.sh --ready '? help'] \ --out "$TMPDIR/demo" --size 120x32 --title '<tool>: <one line>' \ --deny '<real account name>' --gif docs/assets/demo.gif -- <session args>--driveit records--headlesswith no tmux. It printscast=andgif=paths and exits 1 on a leak. - Verify each scene. Times match the player because the idle limit is applied.
Anyuv run scripts/cast-check.py "$TMPDIR/demo/demo.cast" \ --expect 'timeline=Now · ' --expect 'help=Keys' --at 42.5 --rows 15python3withpytealso works. It exits 1 on a missing marker or a nonzero session exit.--atprints the exact screen at a time; use it to inspect a scene that looks wrong. - Review the GIF. Pull a few frames (
ffmpeg -v error -ss 30 -i demo.gif -frames:v 1 f.png) and read them for font, colors, and wrapping. GIF seeking is approximate; text truth comes from--at. - Publish (after the user confirms):
export ASCIINEMA_SERVER_URL=https://asciinema.org asciinema auth # once per machine asciinema upload "$TMPDIR/demo/demo.cast" --visibility public --title '<tool>: <one line>'authprints a connect URL that links this machine to whichever account opens it. Treat it as a credential: keep it out of chat, logs, and PRs, open it in the user's signed-in browser (or hand it to them), and confirm the signed-in account is the intended one before connecting. - README. GitHub's image proxy fails on asciinema's
.svgpreview (503 "Error Fetching Resource"), so commit the GIF and link it to the player:
Check how GitHub renders it with[](https://asciinema.org/a/<id>)gh api markdown -f text='...' -f mode=gfmand curl thecamo.githubusercontent.comURL it returns. Every upload gets a new id: update the link, and ask before deleting superseded uploads.
Scripts
| Script | Does |
|---|---|
scripts/record.sh |
Records headless or tmux-driven, scrubs the header, runs the leak gate, renders the GIF with agg |
scripts/cast-check.py |
Replays the cast through pyte: --expect LABEL=TEXT timings, --at SECONDS screen dumps, exit status |
assets/demo-session.sh |
Session template: silent setup, note, run with a fake prompt and typed commands |
Gotchas (asciinema 3.x, agg 1.9)
authanduploadsay "No asciinema server configured for this CLI." untilASCIINEMA_SERVER_URLis set.--idle-time-limitonly writes metadata; captured timings stay raw. Players apply it,record.shpasses the same value to agg, andcast-check.pyapplies it.- v3 casts store the interval since the previous event and
term.cols/rows; v2 stores absolute times andwidth/height.cast-check.pyreads both. recrefuses an existing file without--overwrite.- tmux reads a lone
;argument as a command separator;kandlitescape it. - Keep the tmux pane the same size as
--window-sizewith the status bar off (record.shdoes) sowait_forreads the screen the cast records. - State carries across scenes. A CLI scene that ticks an item turns a later TUI toggle key into an untick. Re-run
cast-check.pyafter any scene change. - A TUI on the alternate screen restores the previous screen on quit, so TUI markers only match while it runs.
- About 1 MB of GIF for 80 seconds at 120x32, font 14, 15 fps.
Install: brew install asciinema agg tmux, and uv or pip install pyte for cast-check.py.
