asciinema-player

# asciinema-player

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)

---

## Why iTerm2 Instead of Browser?

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

---

## Requirements

| 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 play` directly in their terminal.

---

## Workflow Phases (ALL MANDATORY)

**IMPORTANT**: All phases are MANDATORY. Do NOT skip any phase. AskUserQuestion MUST be used at each decision point.

### Phase 0: Preflight Checks

**Purpose**: Verify iTerm2 and asciinema are installed.

#### Step 0.1: Check Dependencies

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

#### Step 0.2: Report Status and Ask for Installation

**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"