Index of every page on this site: llms.txt
All skills
Run it yourself

Record, replay, convert, sanitize, trim, strip mid-stream sections, simulate terminal screen state with pyte via uv, tighten paste/input delays, manage chapter markers ("m" stop points), and author operator recording runbooks (RUNSHEET.md / EXPERIMENT_RUNBOOK.md) for terminal sessions. Use when planning or writing a RUNSHEET.md or EXPERIMENT_RUNBOOK.md for cast recordings, recording terminal demos, converting .cast files to animated GIF or SVG, embedding asciinema-player in web apps, sanitizing terminal recordings, inspecting cast durations, rendering or verifying terminal screen frames with pyte, removing mid-stream command sections, shortening cut-and-paste or prompt pauses, trimming trailing exit sequences, or adding/moving/inspecting chapter stop-point markers.

Use this Skill: https://skilld.dev/gh/domesticmouse/skills/asciinema

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈197 tokens for metadata: the name and description. ≈5.6k when used: this file. ≈7.4k more on demand in 5 files.

Description uses 9.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈787 characters, or 9.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

  1. Record a Terminal Session
  2. Replay or Inspect a Recording
  3. Convert and Export (GIF / SVG / Text)
  4. Sanitize and Redact Sensitive Data
  5. Trim Exit Sequences, Strip Mid-Stream Sections, and Inspect Timing
  6. Manage Chapter Markers ("m" Stop Points)
  7. Embed in Web Applications
  8. Self-Host an asciinema Server
  9. 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.cast
Core Flags & Rules:
  • -i, --idle-time-limit <sec>: Limits pauses between terminal events. Always specify this for tutorials and documentation (recommended: 1.5 to 2.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 -I or --stdin unless 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+d or exit: 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.cast

Playback 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-v2

For 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.gif

Optimization options:

  • --theme <name>: dracula (default), monokai, solarized-dark, solarized-light, gruvbox-dark, nord, github-dark, github-light.
  • --fps-cap <num>: Cap FPS to 15 or 12 to drastically reduce file size.
  • --font-size <px>: Default 14.
  • --last-frame-duration <sec>: Pause on final frame before loop (default 3.0).
B. Vector / SVG Export
  • Self-contained animated SVG (svg-term only parses asciicast v1/v2, so asciinema 3.x recordings must be converted to asciicast-v2 first):
    # 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):
    [![asciicast](https://asciinema.org/a/<id>.svg)](https://asciinema.org/a/<id>)

4. Sanitize and Redact Sensitive Data

Before publishing or sharing .cast files, strip secrets and credential keystrokes:

  1. Verify stdin is stripped: Default recordings do not capture keystrokes, but if -I/--stdin was used, "i" events must be deleted.
  2. Scrub Environment Metadata: Verify env in header line 1 contains only safe values (TERM, SHELL).
  3. Strip Linux/systemd OSC Metadata: sanitize-cast.py strips Linux/systemd OSC 3008 (machineid, bootid, user, hostname, cwd) and OSC 7 escape sequences in-place inside "o" stdout event payloads by default (leaving "" rather than deleting event lines; pass --keep-osc to preserve them). Because event lines are preserved in place, 0-based event indices #0000..#NNNN do not shift between raw and sanitized .cast files unless -I/--stdin "i" events were removed.
  4. 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.cast

5. 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 --info
B. 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.

  1. 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
  2. Verify a candidate cut before mutating: --verify-strip START:END simulates the screen before (START - 1) and at (END), confirms (cursor.y, cursor.x) parity, compares the post-cut frame after END against the original recording, and flags whether TUI viewport redraws (such as \r\x1b[32A...\x1b[J) explicitly re-emit scrollback lines from inside START:END:
    uv run --with pyte python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
      --verify-strip 17274:17757
  3. Strip the mid-stream event range, relabel remaining markers 1..N, and re-embed HTML:
    python3 .agents/skills/asciinema/scripts/mark-cast.py session.cast \
      --strip-range 17274:17757 \
      --relabel "1. ..." "2. ..." \
      --in-place \
      --embed-html prototypes/session-cast-player.html
    (If pyte reports 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:END before cutting (confirm cursor match and post-cut IDENTICAL or acceptable diff), then run --list and --render after 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 --list

Prints 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[27m in bash, \x1b[7m... in zsh).
  • [UNREV]: Enter key redraw that strips reverse video (\x08+...<cmd>\r\n\x1b[?2004l in bash Readline; \x1b[A...\x1b[27m...\x1b[1B\r\x1b[K in zsh).
  • [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:80
C. 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", or agy—not the post-launch Antigravity CLI welcome banner). With bracketed paste (\x1b[?2004h), pasting and running a command emits [REV] (reverse-video paste: \x1b[7m...\x1b[27m in bash, \x1b[7m... in zsh) → [UNREV] (Enter redraw clearing reverse video: \x08+...<cmd>\r\n\x1b[?2004l\r... in bash Readline, or \x1b[A...\x1b[27m... plus \x1b[1B\r\x1b[K in zsh) → [OSC] (3008/2 shell/command metadata). By default, mark-cast.py advances 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 positive dt (0.02s) ensures its asciicast-v2 timestamp is strictly greater than the marker timestamp T_m, preventing asciinema-player (pauseOnMarkers or player.seek(T_m)) from executing the newline/cursor-down sequence while paused at the stop point (pass --raw-match only if you explicitly want the raw [REV] paste frame).
  • Command-Completion / /clear Hold (pause after a command or /clear finishes running): Match the final stdout frame of the command's output (e.g. "All done!", "root-commit.*Initial scaffold", or the fresh Antigravity CLI banner redraw after /clear).
  • Two-Stop Interactive Prompt / Question Hold (Before Typing + After Typing Before Enter):
    1. Stop 1 — Before Typing (Q: ... / Ready for ...): Match the bottom status/footer of the TUI prompt frame (whether an ask_user selector widget with enter Submit/enter Select or a prose question ending with ? for shortcuts), right before the first typed/pasted character of the user's response (dt > 0).
    2. 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 the Enter submission event (\x1b[\d+D\x1b[K, \r\x1b[2C\x1b[K in Antigravity CLI 1.5.9, or Thinking.../Generating... spinner). Always verify that every "after typing" stop point has a matching "before typing" stop point preceding the typing sequence.
    • When an agy turn finishes or a modal closes (e.g. Installed plugins), agy may briefly draw a transient Loading... line before settling on the final ? for shortcuts prompt frame (dt > 1s); always place the "Ready for ..." / completion stop point on the settled ? for shortcuts frame (not the transient Loading... frame), and verify with uv 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 multiple dt = 0.0 PTY chunks, mark-cast.py automatically advances across consecutive dt = 0.0 "o" events so the marker sits after the complete frame flush.
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> --list and --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-server via Docker Compose (Phoenix + PostgreSQL).
  • Configure CLI clients with export ASCIINEMA_SERVER_URL="https://asciinema.corp.internal".
  • Run asciinema auth to 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.

  1. Inventory Target Recordings & Separate Raw from Final: Extract every planned .cast file from the project's TODO.md, slide blueprint, or experiment specification into a Recording Manifest mapping recordings/raw/<name>.cast → recordings/final/<name>.cast, target Act/Slide or Phase, Session Trajectory, and "m" stop-point count.
  2. Lock Phase 0 Pre-Flight Checks & Capture Guardrails: Specify CLI version checks (asciinema, agy, npx, uv, python3, node), standardised asciinema rec -i 2.0 --window-size 120x36 --overwrite recordings/raw/<name>.cast flags (omitting -I / --stdin), git commit anchors, and camera-visible state resets (uninstalling plugins/skills or clearing directories that must appear fresh on camera).
  3. 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.0 warnings for any cast that exits agy mid-stream, post-recording checklists, and a Cast ↔ Trajectory Correlation ledger.
  4. Enforce an Incremental Record → Correlate → Post-Process → Verify Gate: Include a copy-pasteable /agy-brain-explorer /asciinema audit prompt after each recording to match timestamp + duration (trim-cast.py --info) against ~/.gemini/**/brain/, Trash aborted takes immediately, run sanitize-cast.py → trim-cast.py → mark-cast.py with uv run --with pyte ... --render, and lock telemetry before recording the next take.
  • Checkable Completion Criterion: Every target .cast recording and paired Before / After "m" stop point from the source spec/TODO.md appears verbatim in the runbook, every asciinema rec command uses -i 2.0 --window-size 120x36 --overwrite recordings/raw/<name>.cast without -I/--stdin, and multi-session recordings include explicit --cut-index trim guardrails.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts13d3 checks · Risk SAFE
  • Gen Agent Trust Hub13d

    This skill provides a comprehensive toolkit for managing terminal session recordings using the asciinema ecosystem. It includes utility scripts for sanitizing sensitive information, trimming recording lengths, and managing chapter markers.

  • Socket13d

    No alerts

  • Snyk13d

    Risk: LOW · No issues

Signed by skilld at 606a5d5. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago

README badge

README badge for domesticmouse/skills/asciinema