Play .cast terminal recordings in iTerm2 with full CLI controls. TRIGGERS - asciinema, .cast file, terminal recording, play cast, recording playback, play recording. Uses AskUserQuestion for speed/options selection, spawns clean iTerm2 window via AppleScript.
/plugin marketplace add terrylica/cc-skills/plugin install asciinema-tools@cc-skillsThis skill is limited to using the following tools:
Play terminal session recordings (.cast files) in a dedicated iTerm2 window with full playback controls. Opens a clean window (bypasses default arrangements) for distraction-free viewing.
Platform: macOS only (requires iTerm2)
| Aspect | Browser Player | iTerm2 CLI |
|---|---|---|
| Large files (>100MB) | Crashes (memory limit) | Streams from disk |
| Memory usage | 2-4GB for 700MB file | Minimal |
| Startup time | Slow (download + parse) | Instant |
| Native feel | Web-based | True terminal |
Decision: iTerm2 CLI is the only reliable method for large recordings.
| Component | Required | Installation |
|---|---|---|
| iTerm2 | Yes | brew install --cask iterm2 |
| asciinema CLI | Yes | brew install asciinema |
Note: This skill is macOS-only. Linux users should run
asciinema playdirectly in their terminal.
IMPORTANT: All phases are MANDATORY. Do NOT skip any phase. AskUserQuestion MUST be used at each decision point.
Purpose: Verify iTerm2 and asciinema are installed.
# Check iTerm2 is installed
ls -d /Applications/iTerm.app 2>/dev/null && echo "iTerm2: OK" || echo "iTerm2: MISSING"
# Check asciinema CLI
which asciinema && asciinema --version
MANDATORY AskUserQuestion if any dependency is missing:
Question: "Required dependencies are missing. Install them?"
Header: "Setup"
Options:
- Label: "Install all (Recommended)"
Description: "Will install: {list of missing: iTerm2, asciinema}"
- Label: "Cancel"
Description: "Abort - cannot proceed without dependencies"
# Install iTerm2
brew install --cask iterm2
# Install asciinema CLI
brew install asciinema
Purpose: Discover and select the recording to play.
# Search for .cast files in common locations
fd -e cast . --max-depth 5 2>/dev/null | head -20
# Also check common locations
ls -lh ~/scripts/tmp/*.cast 2>/dev/null
ls -lh ~/.local/share/asciinema/*.cast 2>/dev/null
ls -lh ./tmp/*.cast 2>/dev/null
# Get file size and line count for selected file
ls -lh {file_path}
wc -l {file_path}
If user provided path directly, confirm:
Question: "Play this recording?"
Header: "Confirm"
Options:
- Label: "Yes, play {filename}"
Description: "{size}, {line_count} events"
- Label: "Choose different file"
Description: "Browse for other recordings"
If no path provided, discover and present options:
Question: "Which recording would you like to play?"
Header: "Recording"
Options:
- Label: "{filename} ({size})"
Description: "{line_count} events"
- ... (up to 4 most recent)
Purpose: Configure playback options before launching iTerm2.
Question: "Select playback speed:"
Header: "Speed"
Options:
- Label: "2x (fast)"
Description: "Good for review, see everything"
- Label: "6x (very fast)"
Description: "Quick scan of long sessions"
- Label: "16x (ultra fast)"
Description: "Rapid skim for 700MB+ files"
- Label: "Custom"
Description: "Enter your own speed multiplier"
If "Custom" selected, ask for speed value (use Other option for numeric input).
Question: "Select additional playback options:"
Header: "Options"
multiSelect: true
Options:
- Label: "Limit idle time (2s)"
Description: "Cap pauses to 2 seconds max (recommended)"
- Label: "Loop playback"
Description: "Restart automatically when finished"
- Label: "Resize terminal"
Description: "Match terminal size to recording dimensions"
- Label: "Pause on markers"
Description: "Auto-pause at marked points (for demos)"
Purpose: Open clean iTerm2 window and start playback.
Construct the asciinema play command based on user selections:
# Example with all options
asciinema play -s 6 -i 2 -l -r /path/to/recording.cast
Option flags:
-s {speed} - Playback speed-i 2 - Idle time limit (if selected)-l - Loop (if selected)-r - Resize terminal (if selected)-m - Pause on markers (if selected)Use AppleScript to open a clean window (bypasses default arrangements):
osascript -e 'tell application "iTerm2"
create window with default profile
tell current window
tell current session
write text "asciinema play -s {speed} {options} {file_path}"
end tell
end tell
end tell'
## Playback Started
**Recording:** `{filename}`
**Speed:** {speed}x
**Options:** {options_summary}
### Keyboard Controls
| Key | Action |
| -------- | --------------------------------- |
| `Space` | Pause / Resume |
| `Ctrl+C` | Stop playback |
| `.` | Step forward (when paused) |
| `]` | Skip to next marker (when paused) |
### Tips
- Press `Space` to pause anytime
- Use `.` to step through frame by frame
- `Ctrl+C` to exit when done
Load this template into TodoWrite before starting:
1. [Preflight] Check iTerm2 installed
2. [Preflight] Check asciinema CLI installed
3. [Preflight] AskUserQuestion: install missing deps (if needed)
4. [Preflight] Install dependencies (if confirmed)
5. [Selection] Get file info (size, events)
6. [Selection] AskUserQuestion: confirm file selection
7. [Settings] AskUserQuestion: playback speed
8. [Settings] AskUserQuestion: additional options (multi-select)
9. [Launch] Build asciinema play command
10. [Launch] Execute AppleScript to open iTerm2
11. [Launch] Display controls reference
| Option | Flag | Values | Description |
|---|---|---|---|
| Speed | -s | 0.5, 1, 2, 6, 16... | Playback speed multiplier |
| Idle limit | -i | seconds (e.g., 2) | Cap idle/pause time |
| Loop | -l | (flag) | Continuous loop |
| Resize | -r | (flag) | Match terminal to recording size |
| Markers | -m | (flag) | Auto-pause at markers |
| Quiet | -q | (flag) | Suppress info messages |
tell application "iTerm2"
create window with default profile
tell current window
tell current session
write text "your command here"
end tell
end tell
end tell
Why this works: create window with default profile creates a fresh window, bypassing any saved window arrangements.
osascript -e 'tell application "iTerm2"
create window with default profile
tell current window
tell current session
write text "asciinema play -s 6 -i 2 /path/to/file.cast"
end tell
end tell
end tell'
Cause: Running asciinema play from a non-TTY context (e.g., Claude Code's Bash tool)
Fix: Use AppleScript to open a real iTerm2 window (this skill does this automatically)
Fix: Use the speed AskUserQuestion to select appropriate speed:
Cause: iTerm2 not installed or AppleScript permissions not granted
Fix:
brew install --cask iterm2The CLI player streams from disk, so file size doesn't cause memory issues. However:
-i 2 to skip idle timeAfter modifying this skill:
This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.