Asciinema Converter

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?

Key benefit: Claude Code's Read and Grep tools work directly on .txt output.

---

Requirements

---

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)

Full implementation details: Workflow Phases

Batch Mode (Phases 7-10)

Activated via --batch flag. Converts all .cast files in a directory with organized output.

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

---

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

• asciinema convert command
• asciinema-cast-format skill

---

Troubleshooting

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. 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.