---
name: asciinema
description: 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.
title: asciinema
canonical_url: https://skilld.dev/gh/domesticmouse/skills/asciinema
last_updated: 2026-11-20T07:06:09.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/agents/openai.yaml), [EMBEDDING.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/EMBEDDING.md), [FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/FORMAT.md), [references/RUNBOOK-FORMAT.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/references/RUNBOOK-FORMAT.md), [scripts/mark-cast.py](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/scripts/mark-cast.py), [scripts/sanitize-cast.py](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/scripts/sanitize-cast.py), [scripts/trim-cast.py](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/scripts/trim-cast.py), [SELF-HOSTING.md](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/SELF-HOSTING.md).
>
> If the user asked to install this Skill, run `npx skilld install domesticmouse/skills/asciinema`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/asciinema`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/domesticmouse/skills/asciinema) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/asciinema`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/asciinema --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/asciinema --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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](#1-record-a-terminal-session)
2. [Replay or Inspect a Recording](#2-replay-or-inspect-a-recording)
3. [Convert and Export (GIF / SVG / Text)](#3-convert-and-export)
4. [Sanitize and Redact Sensitive Data](#4-sanitize-and-redact-sensitive-data)
5. [Trim Exit Sequences, Strip Mid-Stream Sections, and Inspect Timing](#5-trim-exit-sequences-strip-mid-stream-sections-and-inspect-timing)
6. [Manage Chapter Markers (`"m"` Stop Points)](#6-manage-chapter-markers-m-stop-points)
7. [Embed in Web Applications](#7-embed-in-web-applications)
8. [Self-Host an asciinema Server](#8-self-host-an-asciinema-server)
9. [Author an Operator Recording Runbook (`RUNSHEET.md` / `EXPERIMENT_RUNBOOK.md`)](#9-author-an-operator-recording-runbook-runsheetmd--experiment_runbookmd)

---

### 1. Record a Terminal Session

Launch an intercepted PTY session using `asciinema rec`:

```bash
# 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
```bash
# 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
```bash
# 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](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/FORMAT.md).

---

### 3. Convert and Export

#### A. Compile to Animated GIF (`agg`)
Use `agg` (asciinema GIF generator) for high-quality, lightweight GIFs:

```bash
# 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):
  ```bash
  # 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):
  ```markdown
  [![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](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/scripts/sanitize-cast.py):

```bash
# 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`:
```bash
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](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/scripts/trim-cast.py) for trailing exit cleanup and [scripts/mark-cast.py](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/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:

```bash
# 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:

```bash
# 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**:
   ```bash
   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`:
   ```bash
   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**:
   ```bash
   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](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/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
```bash
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;`).

```bash
# 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
```bash
# 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`](../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](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/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](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/SELF-HOSTING.md).

---

### 9. Author an Operator Recording Runbook (`RUNSHEET.md` / `EXPERIMENT_RUNBOOK.md`)

Consult [`references/RUNBOOK-FORMAT.md`](https://skilld.dev/api/skills-raw/domesticmouse/skills/asciinema/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.
