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.
This 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 time