Record Claude Code sessions with asciinema. TRIGGERS - record session, asciinema record, capture terminal, record claude, demo recording, record ASCII, ASCII terminal, terminal screen capture, shell screen capture, ASCII screen capture, screen recording. Generates ready-to-copy commands with dynamic workspace-based filenames.
This skill is limited to using the following tools:
Generate ready-to-copy commands for recording Claude Code sessions with asciinema. Dynamically creates filenames based on workspace and datetime.
Platform: macOS, Linux (requires asciinema CLI)
This skill generates ready-to-copy recording commands with:
| Component | Required | Installation |
|---|---|---|
| asciinema CLI | Yes | brew install asciinema |
Purpose: Verify asciinema is installed.
# Check asciinema CLI
which asciinema && asciinema --version
If asciinema is NOT installed, use AskUserQuestion:
Based on selection:
"Install asciinema" → Run appropriate install command based on OS:
# macOS
brew install asciinema
# Linux (apt)
sudo apt install asciinema
# Linux (pip)
pip install asciinema
Then proceed to Phase 1.0.
"Show manual instructions" → Display the commands above, then exit skill.
"Cancel" → Exit skill without action.
Purpose: Let user choose where to save the recording.
Use AskUserQuestion:
Based on selection:
OUTPUT_DIR="$PWD/tmp"OUTPUT_DIR="$HOME/asciinema" and create if missing: mkdir -p ~/asciinemaOUTPUT_DIRPurpose: Let user configure recording behavior.
Use AskUserQuestion:
Based on selections, build command flags:
-t "title" flag--idle-time-limit 0 flag-q flagIf "Add title" was selected, follow up with:
Based on title selection:
TITLE="${WORKSPACE}"TITLE="${WORKSPACE} ${DATETIME}"TITLEPurpose: Generate a copy-paste ready recording command.
Extract workspace name from $PWD:
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
WORKSPACE=$(basename "$PWD")
echo "Workspace: $WORKSPACE"
SKILL_SCRIPT_EOF
/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
DATETIME=$(date +%Y-%m-%d_%H-%M)
echo "Datetime: $DATETIME"
SKILL_SCRIPT_EOF_2
Create the output directory selected in Phase 1.0:
mkdir -p "${OUTPUT_DIR}"
Build the recording command using:
OUTPUT_DIR from Phase 1.0 (location selection)TITLE if "Add title" was selected# Base command
CMD="asciinema rec"
# Add flags from Phase 1.1 options
# (Claude builds this based on user selections)
# Final command format:
asciinema rec ${FLAGS} "${OUTPUT_DIR}/${WORKSPACE}_${DATETIME}.cast"
Example outputs:
# Default (no options selected):
asciinema rec /home/user/projects/my-app/tmp/my-app_2025-12-21_14-30.cast
# With title + quiet mode:
asciinema rec -t "my-app Demo" -q /home/user/projects/my-app/tmp/my-app_2025-12-21_14-30.cast
# With all options:
asciinema rec -t "my-app 2025-12-21 14:30" -q --idle-time-limit 0 ~/asciinema/my-app_2025-12-21_14-30.cast
Purpose: Explain the recording workflow step-by-step.
Present these instructions:
## Recording Instructions
1. **Exit Claude Code** - Type `exit` or press `Ctrl+D`
2. **Copy the command** shown above
3. **Paste and run** in your terminal (starts a recorded shell)
4. **Run `claude`** to start Claude Code inside the recording
5. Work normally - everything is captured
6. **Exit Claude Code** - Type `exit` or press `Ctrl+D`
7. **Exit the recording shell** - Type `exit` or press `Ctrl+D` again
Your recording will be saved to:
`$PWD/tmp/{workspace}_{datetime}.cast`
Purpose: Provide helpful tips for after recording.
## Tips
- **Environment variable**: `ASCIINEMA_REC=1` is set during recording
- **Playback**: Use `asciinema-player` skill or `asciinema play file.cast`
- **Upload (optional)**: `asciinema upload file.cast` (requires account)
- **Markers**: Add `asciinema marker` during recording for navigation points
1. [Preflight] Check asciinema CLI installed
2. [Preflight] Offer installation if missing
3. [Context] Detect current workspace from $PWD
4. [Context] Generate datetime slug
5. [Context] Ensure tmp/ directory exists
6. [Command] Construct full recording command
7. [Guidance] Display step-by-step instructions
8. [Guidance] Show additional tips (playback, upload)
9. Verify against Skill Quality Checklist
After modifying this skill:
$PWD (no hardcoded paths)| Option | Flag | Description |
|---|---|---|
| Title | -t | Recording title (for asciinema.org) |
| Quiet | -q | Suppress status messages |
| Append | -a | Append to existing recording |
Cause: asciinema must wrap the program, not be started from inside.
Fix: Exit Claude Code first, then run the generated command.
Cause: Long sessions produce large files.
Fix:
asciinema upload to store online instead of locallyCause: Terminal size mismatch.
Fix: Use -r flag during playback to resize terminal.