terrylica asciinema-converter
Convert asciinema .cast recordings to clean .txt files for Claude Code analysis. Achieves 950:1 compression (3.8GB -> 4MB) by stripping ANSI codes and JSON structure.
Platform: macOS, Linux (requires asciinema CLI v2.4+)
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
When to Use This Skill
Use this skill when:
- Converting .cast recordings to searchable .txt format
- Preparing recordings for Claude Code Read/Grep tools
- Batch converting multiple recordings
- Reducing storage size of session archives
- Extracting clean text from ANSI-coded terminal output
Why Convert?
| Format | Size (22h session) | Claude Code Compatible | Searchable |
|---|---|---|---|
| .cast | 3.8GB | No (NDJSON + ANSI) | Via jq |
| .txt | ~4MB | Yes (clean text) | Grep/Read |
Key benefit: Claude Code's Read and Grep tools work directly on .txt output.
Requirements
| Component | Required | Installation | Notes |
|---|---|---|---|
| asciinema | Yes | brew install asciinema |
v2.4+ for convert cmd |
Workflow Overview
IMPORTANT: All phases are MANDATORY. Do NOT skip any phase. AskUserQuestion MUST be used at each decision point.
Single File Mode (Phases 0-6)
| Phase | Purpose | Key Action |
|---|---|---|
| 0 | Preflight check | Verify asciinema CLI v2.4+ |
| 1 | File discovery & selection | AskUserQuestion: file to convert |
| 2 | Output options | AskUserQuestion: conversion opts |
| 3 | Output location | AskUserQuestion: save destination |
| 4 | Execute conversion | asciinema convert -f txt |
| 5 | Timestamp index | Optional [HH:MM:SS] index |
| 6 | Next steps | AskUserQuestion: what's next |
Full implementation details: Workflow Phases
Batch Mode (Phases 7-10)
Activated via --batch flag. Converts all .cast files in a directory with organized output.
| Phase | Purpose | Key Action |
|---|---|---|
| 7 | Source selection | AskUserQuestion (skip if --source) |
| 8 | Output organization | AskUserQuestion (skip if --output-dir) |
| 9 | Execute batch | Convert all with progress reporting |
| 10 | Batch next steps | AskUserQuestion: what's next |
Full implementation details: Batch Workflow
iTerm2 Filename Format
iTerm2 auto-logged files follow this format:
{creationTimeString}.{profileName}.{termid}.{iterm2.pid}.{autoLogId}.cast
Example: 20260118_232025.Claude Code.w0t1p1.70C05103-2F29-4B42-8067-BE475DB6126A.68721.4013739999.cast
| Component | Description | Example |
|---|---|---|
| creationTimeString | YYYYMMDD_HHMMSS | 20260118_232025 |
| profileName | iTerm2 profile (may have dots) | Claude Code |
| termid | Window/tab/pane identifier | w0t1p1 |
| iterm2.pid | iTerm2 process UUID | 70C05103-2F29-4B42-8067-BE475DB6126A |
| autoLogId | Session auto-log identifier | 68721.4013739999 |
CLI Quick Reference
# Basic conversion
asciinema convert -f txt recording.cast recording.txt
# Check asciinema version
asciinema --version
# Verify convert command exists
asciinema convert --help
Reference Documentation
Internal References
- Workflow Phases - Single file mode phases 0-6 with full scripts
- Batch Workflow - Batch mode phases 7-10 with full scripts
- Task Templates - TodoWrite templates for single and batch modes
- Post-Change Checklist - Verification after modifications
- Anti-Patterns - Common mistakes to avoid
- Batch Processing - Patterns for bulk conversion
- Integration Guide - Chaining with analyze/summarize
External References
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| convert command not found | asciinema too old | Upgrade: brew upgrade asciinema (need v2.4+) |
| asciinema not installed | Missing CLI | brew install asciinema |
| Empty output file | Corrupted .cast input | Verify .cast file has valid NDJSON structure |
| Conversion failed | Invalid cast format | Check header line is valid JSON with jq |
| numfmt not found | macOS missing coreutils | Use raw byte count or brew install coreutils |
| stat syntax error | Linux vs macOS difference | Script handles both; check stat version |
| Batch skipping all files | All .txt already exist | Use --skip-existing=false to reconvert |
| Permission denied on output | Directory not writable | Check output directory permissions |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.