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+)

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