Skill

asciinema-converter

Convert .cast recordings to .txt for analysis. TRIGGERS - convert cast, cast to txt, strip ANSI, batch convert.

Install

Run in your terminal

npx claudepluginhub terrylica/cc-skills --plugin asciinema-tools

Tool Access

This skill is limited to using the following tools:

ReadBashGlobWriteAskUserQuestion

Supporting Assets

View in Repository

references/anti-patterns.md

references/batch-processing.md

references/batch-workflow.md

references/evolution-log.md

references/integration-guide.md

references/post-change-checklist.md

references/task-templates.md

references/workflow-phases.md

tests/converter-integration.bats

tests/converter.test.ts

tests/fixtures/simple.cast

tests/fixtures/with spaces.cast

Skill Content

Similar Skills

executing-plans

Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.

superpowers

134.2k

finishing-a-development-branch

Verifies tests pass on completed feature branch, presents options to merge locally, create GitHub PR, keep as-is or discard; executes choice and cleans up worktree.

superpowers

134.2k

dispatching-parallel-agents

Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.

superpowers

134.2k

Stats

Parent Repo Stars28

Parent Repo Forks4

Last CommitApr 1, 2026

Actions

View Source View Plugin View on GitHub View README

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.