# asciinema-tools

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Skills](https://img.shields.io/badge/Skills-6-blue.svg)]()
[![Commands](https://img.shields.io/badge/Commands-18-green.svg)]()
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-purple.svg)]()

Terminal recording, playback, streaming, and analysis plugin for Claude Code. Record sessions, stream to GitHub, convert to searchable text, and extract insights with semantic analysis.

## Skills

| Skill                          | Description                                                        |
| ------------------------------ | ------------------------------------------------------------------ |
| **asciinema-player**           | Play .cast recordings in iTerm2 with speed controls                |
| **asciinema-recorder**         | Record Claude Code sessions with dynamic workspace-based filenames |
| **asciinema-streaming-backup** | Real-time backup to GitHub orphan branch with idle-chunking        |
| **asciinema-cast-format**      | Reference for asciinema v3 NDJSON format (header, events, parsing) |
| **asciinema-converter**        | Convert .cast to .txt for Claude Code analysis (950:1 compression) |
| **asciinema-analyzer**         | Keyword extraction and density analysis for recordings             |

## Commands

| Command                          | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `/asciinema-tools:record`        | Start terminal recording with asciinema                |
| `/asciinema-tools:play`          | Play .cast recordings in iTerm2                        |
| `/asciinema-tools:backup`        | Stream-backup active recordings to GitHub              |
| `/asciinema-tools:format`        | Reference for asciinema v3 .cast format                |
| `/asciinema-tools:convert`       | Convert .cast to .txt for analysis                     |
| `/asciinema-tools:analyze`       | Semantic analysis of converted recordings              |
| `/asciinema-tools:summarize`     | AI-powered iterative deep-dive analysis                |
| `/asciinema-tools:post-session`  | Post-session workflow: finalize + convert + summarize  |
| `/asciinema-tools:full-workflow` | Full workflow: record + backup + convert + analyze     |
| `/asciinema-tools:bootstrap`     | Pre-session setup for automatic streaming (PRE-CLAUDE) |
| `/asciinema-tools:finalize`      | Finalize orphaned recordings (stop, compress, push)    |
| `/asciinema-tools:setup`         | Check and install dependencies                         |
| `/asciinema-tools:tether`         | Install/uninstall auto-backup hooks                    |
| `/asciinema-tools:daemon-setup`  | Set up chunker daemon with interactive wizard          |
| `/asciinema-tools:daemon-start`  | Start the asciinema chunker daemon                     |
| `/asciinema-tools:daemon-stop`   | Stop the asciinema chunker daemon                      |
| `/asciinema-tools:daemon-status` | Check daemon status and unhandled .cast files          |
| `/asciinema-tools:daemon-logs`   | View chunker daemon logs                               |

## Installation

```bash
/plugin marketplace add terrylica/cc-skills
/plugin install asciinema-tools@cc-skills
```

## Usage

Skills are model-invoked based on context. Commands can be invoked directly.

**Skill trigger phrases:**

- "play recording", ".cast file", "terminal recording" -> asciinema-player
- "record session", "asciinema record", "capture terminal" -> asciinema-recorder
- "streaming backup", "orphan branch", "chunked recording" -> asciinema-streaming-backup
- "cast format", "asciicast spec", "event codes" -> asciinema-cast-format
- "convert cast", "cast to txt", "prepare for analysis" -> asciinema-converter
- "analyze cast", "keyword extraction", "density analysis" -> asciinema-analyzer

## Key Features

### Recording & Playback

- **asciinema-player**: Play .cast files in iTerm2 (handles 700MB+ files)
  - Speed controls: 2x, 6x, 16x, custom
  - Clean iTerm2 window via AppleScript
  - Interactive options with AskUserQuestion

- **asciinema-recorder**: Record Claude Code sessions
  - Dynamic filename: `{workspace}_{datetime}.cast`
  - Saves to `$PWD/tmp/` (gitignored)
  - Title, idle limit, quiet mode options

### Streaming Backup

- **asciinema-streaming-backup**: Real-time backup to GitHub orphan branch
  - Per-repository orphan branches
  - Idle-detection chunking (30s default)
  - zstd streaming compression (concatenatable)
  - GitHub Actions auto-recompresses to brotli (~300:1)

- **bootstrap command**: Pre-Claude session setup
  - Runs OUTSIDE Claude Code
  - Sets up asciinema recording + idle-chunker
  - Streams everything to GitHub automatically
  - Cleanup on exit via trap

### Analysis Pipeline

- **asciinema-converter**: Convert .cast to .txt
  - 3.8GB -> 4MB (950:1 compression ratio)
  - ANSI stripped, clean text output
  - Optional timestamp index for navigation

- **asciinema-analyzer**: Semantic analysis
  - Tiered analysis: ripgrep (50-200ms) -> YAKE (1-5s)
  - Curated keyword sets: trading, ML/AI, development, Claude Code
  - Density analysis: find high-concentration sections
  - Auto-discovery with YAKE unsupervised extraction

### Analysis Tiers

| Tier | Tool    | Speed (4MB) | Use Case                  |
| ---- | ------- | ----------- | ------------------------- |
| 1    | ripgrep | 50-200ms    | Curated keyword search    |
| 2    | YAKE    | 1-5s        | Auto-discover keywords    |
| 3    | TF-IDF  | 5-30s       | Topic modeling (optional) |

## Workflow Examples

### Quick Post-Session Analysis

```
/asciinema-tools:post-session session.cast -q -d trading
```

Converts to .txt and runs quick curated keyword analysis for trading domain.

### Full Pre-Claude Workflow

```bash
# 1. In Claude Code: generate bootstrap script
/asciinema-tools:bootstrap

# 2. Exit Claude, run bootstrap
source bootstrap-claude-session.sh

# 3. Start Claude - everything streams automatically
claude

# 4. When done, exit - cleanup runs via trap
exit
```

### Manual Analysis Pipeline

```
/asciinema-tools:convert session.cast --index
/asciinema-tools:analyze session.txt -d trading,ml -t full
```

## Dependencies

| Component       | Required | Installation                 |
| --------------- | -------- | ---------------------------- |
| asciinema CLI   | Yes      | `brew install asciinema`     |
| iTerm2          | Play     | `brew install --cask iterm2` |
| ripgrep         | Analysis | `brew install ripgrep`       |
| YAKE (optional) | Analysis | `uv run --with yake`         |
| fswatch         | Backup   | `brew install fswatch`       |
| gh CLI          | Backup   | `brew install gh`            |

Run `/asciinema-tools:setup` to check and install dependencies.

## Architecture

See [ADR: asciinema-tools Plugin](/docs/adr/2025-12-24-asciinema-tools-plugin.md) for architectural decisions.

## Troubleshooting

| Issue                       | Cause                           | Solution                                                |
| --------------------------- | ------------------------------- | ------------------------------------------------------- |
| Recording not starting      | asciinema not installed         | Run `brew install asciinema`                            |
| Playback black screen       | iTerm2 not active               | Ensure iTerm2 is frontmost application                  |
| Streaming backup failing    | gh CLI not authenticated        | Run `gh auth login` to authenticate                     |
| Orphan branch push rejected | Remote branch doesn't exist     | Create orphan branch first with setup wizard            |
| Conversion produces empty   | .cast file corrupted or empty   | Check .cast file has valid NDJSON content               |
| YAKE not found for analysis | Optional dependency not install | Run `uv pip install yake` for Tier 2 analysis           |
| Chunker daemon not starting | LaunchAgent not loaded          | Check daemon setup with `/asciinema-tools:daemon-setup` |
| Large .cast file issues     | Memory limits                   | Use streaming converter for files >1GB                  |

## License

MIT
