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

• asciinema convert command

• asciinema-cast-format skill

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