Asciinema
Tools and procedures to record, replay, export, sanitize, trim, and manage chapter stop points in terminal sessions using the asciinema ecosystem.
Workflows
Identify the user's objective and choose the matching workflow:
- Record a Terminal Session
- Replay or Inspect a Recording
- Convert and Export (GIF / SVG / Text)
- Sanitize and Redact Sensitive Data
- Trim Exit Sequences, Strip Mid-Stream Sections, and Inspect Timing
- Manage Chapter Markers (
"m"Stop Points) - Embed in Web Applications
- Self-Host an asciinema Server
- Author an Operator Recording Runbook (
RUNSHEET.md/EXPERIMENT_RUNBOOK.md)
1. Record a Terminal Session
Launch an intercepted PTY session using asciinema rec:
# Basic interactive recording
asciinema rec session.cast
# Record with idle-time cap (recommended: 2.0s) and non-interactive overwrite
asciinema rec -i 2.0 --overwrite session.cast
# Record a specific command and exit immediately upon completion
asciinema rec -c "pnpm test" -i 2.0 test-run.cast
# Headless recording in CI/automation with fixed dimensions
asciinema rec --headless --window-size 100x30 -c "./build.sh" build.castCore Flags & Rules:
-i, --idle-time-limit <sec>: Limits pauses between terminal events. Always specify this for tutorials and documentation (recommended:1.5to2.0).-c, --command <cmd>: Executes a command directly and terminates recording when done.--overwrite: Overwrites the target file without an interactive confirmation prompt.--window-size <cols>x<rows>: Sets explicit terminal dimensions (e.g.80x24,120x30).- Security Guardrail: Do not use
-Ior--stdinunless explicitly required. Capturing keyboard input logs raw keystrokes and can expose passwords, tokens, and credentials in plaintext.
Interactive Hotkeys During Recording:
Ctrl+\: Pause and resume recording (acts like a microphone mute).Ctrl+x: Insert chapter marker ("m"event) at current timestamp.Ctrl+dorexit: Terminate session and save recording.
2. Replay or Inspect a Recording
Terminal Replay
# Replay local cast
asciinema play session.cast
# Accelerated playback (2x speed) with 1s max pause
asciinema play -s 2.0 -i 1.0 session.cast
# Pause automatically on markers (slide mode; required to observe "m" stop points in CLI playback)
asciinema play -m session.cast
# Accelerated marker-pause playback (2x speed, 1s idle cap)
asciinema play -m -s 2.0 -i 1.0 session.cast
# Loop continuously
asciinema play -l session.castPlayback Controls: Space (pause/resume), . (step frame), ] (next marker), Ctrl+c (quit).
Fast Inspection & Text Extraction
# Dump raw terminal stdout without timing pauses (pipeable)
asciinema cat session.cast | grep "ERROR"
# Convert cast to plain text (CLI 3.x)
asciinema convert session.cast output.txt -f txt
# Convert format between v3 and v2 (CLI 3.x)
asciinema convert session.v3.cast session.v2.cast -f asciicast-v2For schema details on v1, v2, and v3 files, see FORMAT.md.
3. Convert and Export
A. Compile to Animated GIF (agg)
Use agg (asciinema GIF generator) for high-quality, lightweight GIFs:
# Compact, web-ready documentation GIF
agg --theme monokai --fps-cap 15 --speed 1.5 --idle-time-limit 2 session.cast demo.gifOptimization options:
--theme <name>:dracula(default),monokai,solarized-dark,solarized-light,gruvbox-dark,nord,github-dark,github-light.--fps-cap <num>: Cap FPS to15or12to drastically reduce file size.--font-size <px>: Default14.--last-frame-duration <sec>: Pause on final frame before loop (default3.0).
B. Vector / SVG Export
- Self-contained animated SVG (
svg-termonly parsesasciicast v1/v2, soasciinema3.x recordings must be converted toasciicast-v2first):# asciinema 3.x (v3 default): convert to v2 on stdout and pipe to svg-term asciinema convert -f asciicast-v2 session.cast - | svg-term --out demo.svg --window --width 80 --height 24 # If session.cast is already asciicast v2: cat session.cast | svg-term --out demo.svg --window --width 80 --height 24 - asciinema.org SVG Badge (Safe for GitHub READMEs):
[](https://asciinema.org/a/<id>)
4. Sanitize and Redact Sensitive Data
Before publishing or sharing .cast files, strip secrets and credential keystrokes:
- Verify stdin is stripped: Default recordings do not capture keystrokes, but if
-I/--stdinwas used,"i"events must be deleted. - Scrub Environment Metadata: Verify
envin header line 1 contains only safe values (TERM,SHELL). - Strip Linux/systemd OSC Metadata:
sanitize-cast.pystrips Linux/systemdOSC 3008(machineid,bootid,user,hostname,cwd) andOSC 7escape sequences in-place inside"o"stdout event payloads by default (leaving""rather than deleting event lines; pass--keep-oscto preserve them). Because event lines are preserved in place, 0-based event indices#0000..#NNNNdo not shift between raw and sanitized.castfiles unless-I/--stdin"i"events were removed. - Redact Output Patterns: Replace API keys, tokens, or internal URLs in
"o"events.
Use the bundled utility script scripts/sanitize-cast.py:
# Strip stdin events and clean environment metadata
python3 .agents/skills/asciinema/scripts/sanitize-cast.py session.cast sanitized.cast
# Strip stdin and redact custom sensitive patterns
python3 .agents/skills/asciinema/scripts/sanitize-cast.py session.cast sanitized.cast \
--redact "ghp_123456=REDACTED" "internal.corp=example.com"Quick regex redaction with sed:
sed -E 's/(ghp_[a-zA-Z0-9]{36}|AKIA[0-9A-Z]{16})/REDACTED/g' session.cast > sanitized.cast5. Trim Exit Sequences, Strip Mid-Stream Sections, and Inspect Timing
Interactive recordings frequently capture trailing Ctrl+D keystrokes, warning prompts (e.g. press ctrl+d again to exit), resume text, or dropping back into the shell prompt before session termination, as well as unwanted mid-stream diagnostic commands.
Use the bundled utility script scripts/trim-cast.py for trailing exit cleanup and scripts/mark-cast.py (with uv run --with pyte) for 2D terminal screen simulation and mid-stream range stripping:
A. Inspect Durations and Detect Exit Sequences
Inspect recording duration (both raw elapsed time and idle_time_limit playback time) and auto-detect trailing exit prompts without modifying the file:
# Print timing analysis and trailing pattern detection
python3 .agents/skills/asciinema/scripts/trim-cast.py session.cast --infoB. Strip Exit Sequences and Hold Final Frame
Cut off the trailing exit sequence and append a clean exit event ("x") holding on the final frame (default: 3.0s pause before exit) so that video exports and looping web players don't immediately restart:
# Trim in place with default 3.0s final frame hold
python3 .agents/skills/asciinema/scripts/trim-cast.py session.cast --in-place
# Trim and write to a new file with custom 2.0s hold
python3 .agents/skills/asciinema/scripts/trim-cast.py session.cast trimmed.cast --hold 2.0
# Trim at an explicit pattern or regex
python3 .agents/skills/asciinema/scripts/trim-cast.py session.cast --in-place --cut-at "press ctrl+d"
# Trim and convert asciicast v3 -> v2 for asciinema-player <3.10 web compatibility
python3 .agents/skills/asciinema/scripts/trim-cast.py session.cast --in-place --to-v2- Checkable Completion Criterion: Run
python3 .agents/skills/asciinema/scripts/trim-cast.py <file> --info. Confirm that no trailing exit sequence is detected and duration matches the expected trimmed time.
C. Simulating Terminal State with pyte (via uv) & Stripping Mid-Stream Sections (--verify-strip / --strip-range)
Always use pyte invoked via uv (uv run --with pyte python3 ...) rather than bare python3 (where pyte is typically not installed globally) or custom regex ANSI parsers when inspecting visual screen state or verifying mid-stream cuts. mark-cast.py configures pyte with xterm-ghostty / ECMA-48 extensions so DECST8C (\x1b[?5W), CBT (\x1b[3Z), REP (\x1b[5b), and multi-chunk OSC 8 hyperlinks render accurately.
- Render 2D terminal screens at boundary events:
uv run --with pyte python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \ --render 17272 --render 17756 - Verify a candidate cut before mutating:
--verify-strip START:ENDsimulates the screen before (START - 1) and at (END), confirms(cursor.y, cursor.x)parity, compares the post-cut frame afterENDagainst the original recording, and flags whether TUI viewport redraws (such as\r\x1b[32A...\x1b[J) explicitly re-emit scrollback lines from insideSTART:END:uv run --with pyte python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \ --verify-strip 17274:17757 - Strip the mid-stream event range, relabel remaining markers
1..N, and re-embed HTML:
(Ifpython3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \ --strip-range 17274:17757 \ --relabel "1. ..." "2. ..." \ --in-place \ --embed-html prototypes/session-cast-player.htmlpytereports that subsequent TUI full-viewport redraws explicitly re-paint scrollback text from the excised command, note that scrollback lines remain visible until they scroll off-screen unless those redraw payloads are also rewritten.)
- Checkable Completion Criterion: Run
uv run --with pyte python3 .agents/skills/asciinema/scripts/mark-cast.py <file> --verify-strip START:ENDbefore cutting (confirm cursor match and post-cutIDENTICALor acceptable diff), then run--listand--renderafter cutting to confirm clean sequential markers and uncorrupted display.
6. Manage Chapter Markers ("m" Stop Points)
Use the bundled utility script scripts/mark-cast.py to list, search, inspect, add, move/replace, or remove "m" chapter markers in asciicast v2 and v3 files, and optionally re-embed updated .cast files into standalone HTML players.
A. List Markers & Adaptive Segment Timings
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast --listPrints every "m" event with its 1-based [N] index, 0-based event #idx, raw elapsed time, 1x idle-capped time, adaptive segment speed (>= 2x, <= 30s per segment), and cumulative warped time.
B. Search Output & Inspect Event Boundaries
Before placing or moving a stop point, locate the exact stdout ("o") event index. Both --search and --inspect annotate stdout events with diagnostic tags so shell paste/redraw phases are visible at a glance:
[REV]: Bracketed-paste echo in reverse video (\x1b[7m...\x1b[27minbash,\x1b[7m...inzsh).[UNREV]:Enterkey redraw that strips reverse video (\x08+...<cmd>\r\n\x1b[?2004linbashReadline;\x1b[A...\x1b[27m...\x1b[1B\r\x1b[Kinzsh).[OSC]: Prompt/pre-exec OSC metadata (\x1b]0;,\x1b]2;,\x1b]7;, and Linux systemd\x1b]3008;).
# Search stdout for a pattern and show 2 surrounding events before/after each match
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast --search "flutter create" --context 2
# Inspect one or more event ranges (repeatable) with dt, raw, 1x, code, tags, and ANSI-stripped text
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast --inspect 0:25 --inspect 65:80C. Placement Rules: Command-Entry Hold vs. Command-Completion Hold vs. Two-Stop Prompt/Question Hold
Always place "m" markers ([0.0, "m", "<label>"] in v3, [abs_time, "m", "<label>"] in v2) immediately after the "o" stdout event that finishes drawing the target frame (default behavior of mark-cast.py):
- Command-Entry Hold (pause after a shell command or TUI launcher is typed/pasted and reverse video is cleared, with the cursor still on the command line, before command output or TUI startup): Match the command text itself (e.g.
flutter create --platforms=ios my_app,git init && git add . && git commit -m "Initial scaffold", oragy—not the post-launchAntigravity CLIwelcome banner). With bracketed paste (\x1b[?2004h), pasting and running a command emits[REV](reverse-video paste:\x1b[7m...\x1b[27minbash,\x1b[7m...inzsh) →[UNREV](Enterredraw clearing reverse video:\x08+...<cmd>\r\n\x1b[?2004l\r...inbashReadline, or\x1b[A...\x1b[27m...plus\x1b[1B\r\x1b[Kinzsh) →[OSC](3008/2shell/command metadata). By default,mark-cast.pyadvances from[REV]to[UNREV]and splits trailing\r\n\x1b[?2004l\r...(bash) or\x1b[1B\r\x1b[K(zsh) into a post-marker"o"event (dt=0.02s). Giving the split post-marker"o"event a positivedt(0.02s) ensures itsasciicast-v2timestamp is strictly greater than the marker timestampT_m, preventingasciinema-player(pauseOnMarkersorplayer.seek(T_m)) from executing the newline/cursor-down sequence while paused at the stop point (pass--raw-matchonly if you explicitly want the raw[REV]paste frame). - Command-Completion /
/clearHold (pause after a command or/clearfinishes running): Match the final stdout frame of the command's output (e.g."All done!","root-commit.*Initial scaffold", or the freshAntigravity CLIbanner redraw after/clear). - Two-Stop Interactive Prompt / Question Hold (Before Typing + After Typing Before
Enter):- Stop 1 — Before Typing (
Q: .../Ready for ...): Match the bottom status/footer of the TUI prompt frame (whether anask_userselector widget withenter Submit/enter Selector a prose question ending with? for shortcuts), right before the first typed/pasted character of the user's response (dt > 0). - Stop 2 — After Typing, Before
Enter(Answer: ...//command): Match the final stdout frame that echoes the user's complete typed/pasted response or slash command in the input box, right before theEntersubmission event (\x1b[\d+D\x1b[K,\r\x1b[2C\x1b[KinAntigravity CLI 1.5.9, orThinking.../Generating...spinner). Always verify that every "after typing" stop point has a matching "before typing" stop point preceding the typing sequence.
- When an
agyturn finishes or a modal closes (e.g.Installed plugins),agymay briefly draw a transientLoading...line before settling on the final? for shortcutsprompt frame (dt > 1s); always place the"Ready for ..."/ completion stop point on the settled? for shortcutsframe (not the transientLoading...frame), and verify withuv run --with pyte python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast --render <idx>. - When a synchronized TUI redraw (
\x1b[?2026h…\x1b[?2026l) spans multipledt = 0.0PTY chunks,mark-cast.pyautomatically advances across consecutivedt = 0.0"o"events so the marker sits after the complete frame flush.
- Stop 1 — Before Typing (
D. Move/Replace, Add, or Remove Markers, and Tighten Paste Delays
# Move/replace an existing marker (by 1-based number or label substring) to a command/pattern, @event:IDX, @time:SEC, or @1x:SEC
# (Automatically advances from [REV] bracketed-paste highlight to [UNREV] and splits trailing cursor-down so the cursor stays on the command line)
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
--set 1 "flutter create --platforms=ios my_app" "1. Create Project" \
--set 2 'git init && git add . && git commit -m "Initial scaffold"' "2. Initial Git Commit" \
--set 3 "agy" "3. Launch agy" \
--in-place
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
--set "Create Project" "@event:11" "1. Create Project" --in-place
# Add a new marker right after a stdout pattern (use pattern#2 for 2nd occurrence)
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
--add-pattern "> please fix" "11. Apply Review Fixes" --in-place
# Batch-insert markers by exact 0-based event index in natural chronological order
# (mark-cast.py inserts in descending index order internally so subsequent indices never shift)
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
--add-event 10 "1. Launch agy" \
--add-event 69 "2. Ready for /egm-bootstrap" --in-place
# Auto-inject a batch of markers from a JSON specification file
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
--auto-spec markers.json --in-place
# Remove a specific marker by number or label substring
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast --remove 1 --in-place
# Automatically tighten cut-and-paste delays ([REV]/prompt paste/ask_question ✓ -> 1.0s, [UNREV] Enter -> 0.15s, prompt submit -> 0.20s)
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
--tighten-pastes --in-place --embed-html player.html
# Set the relative delay (dt) of specific event indices directly (shifts subsequent timestamps automatically in v2)
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
--set-dt 7 1.0 --set-dt 8 0.15 --in-place --embed-html player.html
# Update markers AND sync gzip+base64 EMBEDDED_CAST_GZ_B64 in a standalone HTML player in one step
python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
--set 1 "flutter create --platforms=ios my_app" "1. Create Project" \
--set 2 'git init && git add . && git commit -m "Initial scaffold"' "2. Initial Git Commit" \
--set 3 "agy" "3. Launch agy" \
--in-place --embed-html player.html- Checkable Completion Criterion: Run
python3 .agents/skills/asciinema/scripts/mark-cast.py <file> --listand--inspect <idx>around modified markers to confirm every command-entry marker sits immediately after[UNREV](reverse video cleared, cursor on the same line as the command) and before the split\r\n\x1b[?2004l...(bash) or\x1b[1B\r\x1b[K(zsh) newline/cursor-down and command output frames. - Standalone HTML Cast Players (
*-cast-player.html): When editing, reviewing, or scaffolding standalone HTML cast-player harnesses, read../cast-player-html/SKILL.md.
7. Embed in Web Applications
Integrate interactive virtual terminal playback using asciinema-player v3 (WASM/Rust driven).
Consult EMBEDDING.md for complete copy-pasteable code examples:
- Vanilla HTML / JS:
AsciinemaPlayer.create(src, container, options) - React / Next.js / Docusaurus: SSR-safe dynamic import inside
useEffect - Vue 3 / VitePress: Client-only dynamic mount with Vite SSR exclusion
- Hugo: Reusable shortcode
- asciinema.org Embeds: Direct
<script>widget or responsive<iframe>
8. Self-Host an asciinema Server
For private session repositories, air-gapped networks, or corporate compliance:
- Run
asciinema-servervia Docker Compose (Phoenix + PostgreSQL). - Configure CLI clients with
export ASCIINEMA_SERVER_URL="https://asciinema.corp.internal". - Run
asciinema authto link local CLI installations to private accounts.
Full Docker Compose configuration, environment variables, and bootstrap steps are documented in SELF-HOSTING.md.
9. Author an Operator Recording Runbook (RUNSHEET.md / EXPERIMENT_RUNBOOK.md)
Consult references/RUNBOOK-FORMAT.md for full section templates, post-recording checklists, Cast ↔ Trajectory Correlation ledgers, and copy-pasteable /agy-brain-explorer /asciinema audit prompts.
- Inventory Target Recordings & Separate Raw from Final:
Extract every planned
.castfile from the project'sTODO.md, slide blueprint, or experiment specification into a Recording Manifest mappingrecordings/raw/<name>.cast→recordings/final/<name>.cast, target Act/Slide or Phase, Session Trajectory, and"m"stop-point count. - Lock Phase 0 Pre-Flight Checks & Capture Guardrails:
Specify CLI version checks (
asciinema,agy,npx,uv,python3,node), standardisedasciinema rec -i 2.0 --window-size 120x36 --overwrite recordings/raw/<name>.castflags (omitting-I/--stdin), git commit anchors, and camera-visible state resets (uninstalling plugins/skills or clearing directories that must appear fresh on camera). - Script Each Recording with Verbatim Prompts, Paired Markers & Exit Guardrails:
Provide pre-step state checks, copy-pasteable commands/prompts, paired Before / After
"m"stop-point tables (m1..mN), explicit--cut-index <FINAL_EXIT_IDX> --hold 3.0warnings for any cast that exitsagymid-stream, post-recording checklists, and aCast ↔ Trajectory Correlationledger. - Enforce an Incremental
Record → Correlate → Post-Process → VerifyGate: Include a copy-pasteable/agy-brain-explorer /asciinemaaudit prompt after each recording to matchtimestamp+ duration (trim-cast.py --info) against~/.gemini/**/brain/, Trash aborted takes immediately, runsanitize-cast.py→trim-cast.py→mark-cast.pywithuv run --with pyte ... --render, and lock telemetry before recording the next take.
- Checkable Completion Criterion: Every target
.castrecording and paired Before / After"m"stop point from the source spec/TODO.mdappears verbatim in the runbook, everyasciinema reccommand uses-i 2.0 --window-size 120x36 --overwrite recordings/raw/<name>.castwithout-I/--stdin, and multi-session recordings include explicit--cut-indextrim guardrails.