Skip to main content
skill CX Codex

asciinema-converter — Claude Code skill: convert .cast files

asciinema-converter turns asciinema .cast recordings into clean .txt files for reading and search. It handles one file or a directory batch.

MIT 126 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill asciinema-converter -a claude-code
Open on GitHub

What asciinema-converter does

This skill discovers a .cast recording, asks for conversion and output choices, then runs asciinema convert -f txt. It can add a [HH:MM:SS] timestamp index. The generated text removes ANSI escape codes and the surrounding JSON structure, so Claude Code can inspect it with Read and Grep.

Batch mode uses --batch to convert every .cast file in a directory and organize the output. You can provide --source and --output-dir to avoid the related questions, while --skip-existing=false allows existing .txt files to be converted again.

The asciinema CLI must be version 2.4 or newer, or the convert command will fail. The workflow also checks malformed cast data, output permissions, and the different stat syntax used on macOS and Linux.

What it helps with

  • turn a .cast recording into .txt
  • remove ANSI escape codes from terminal output
  • make a recording searchable with Read and Grep
  • convert every .cast file in a directory

Example prompts for the agent

  • Convert recording.cast to recording.txt and check that asciinema convert is available.
  • Run a batch conversion with --batch for the .cast files in the directory I specify.
  • Convert this .cast recording and include a [HH:MM:SS] timestamp index.

How to install asciinema-converter

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill asciinema-converter -a claude-code

2Manually: put the files in place

~/.claude/skills/asciinema-converter/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/asciinema-converter/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about asciinema-converter

How do I install asciinema-converter in Claude Code?

Run npx skills add terrylica/cc-skills --skill asciinema-converter -a claude-code, then check ~/.claude/skills/asciinema-converter/SKILL.md.

What does asciinema-converter do?

It changes asciinema .cast recordings into clean .txt files, removes ANSI codes and JSON framing, and prepares the text for reading and search.

What does asciinema-converter require?

It requires the asciinema CLI at version 2.4 or newer. The skill targets macOS and Linux.

Source text

SKILL.md · MIT
---
name: asciinema-converter
description: Convert .cast recordings to .txt for analysis. TRIGGERS - convert cast, cast to txt, strip ANSI, batch convert.
allowed-tools: Read, Bash, Glob, Write, AskUserQuestion
---

# 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](./references/workflow-phases.md)

### 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](./references/batch-workflow.md)

---

## 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

```bash
# 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](./references/workflow-phases.md) - Single file mode phases 0-6 with full scripts
- [Batch Workflow](./references/batch-workflow.md) - Batch mode phases 7-10 with full scripts
- [Task Templates](./references/task-templates.md) - TodoWrite templates for single and batch modes
- [Post-Change Checklist](./references/post-change-checklist.md) - Verification after modifications
- [Anti-Patterns](./references/anti-patterns.md) - Common mistakes to avoid
- [Batch Processing](./references/batch-processing.md) - Patterns for bulk conversion
- [Integration Guide](./references/integration-guide.md) - Chaining with analyze/summarize

### External References

- [asciinema convert command](https://docs.asciinema.org/manual/cli/)
- [asciinema-cast-format skill](../asciinema-cast-format/SKILL.md)

---

## 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:

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.

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set79

The whole set →
iterm2-layout iterm2-layout configures iTerm2 workspace layouts, panes, and tabs using a TOML file. Helps an AI agent register project directories and auto-discover git worktrees. CX Codex +1 126installs asciinema-player asciinema-player — a skill for Claude Code and five other platforms that plays .cast terminal recordings inside a dedicated iTerm2 window. Files over 100 MB crash browser players; this skill streams them from disk. CX Codex +1 126installs impl-standards impl-standards — a set of coding rules: error propagation, constant extraction, progress logging for long operations, and dependency injection patterns. CX Codex +1 126installs bootstrap-monorepo bootstrap-monorepo scaffolds a polyglot monorepo using moon, proto, and Bun with a TypeScript control plane and strict boundary rules. CX Codex +1 126installs multi-agent-performance-profiling multi-agent-performance-profiling spawns five parallel profiling agents to investigate system layers: instrumentation, database config, client library, batch sizing, and synthesis. CX Codex +1 126installs clickhouse-cloud-management clickhouse-cloud-management manages ClickHouse Cloud database users and access permissions using SQL statements over HTTPS. CX Codex +1 126installs booking-notify booking-notify sends notifications for new bookings, cancellations and reschedules via Telegram and Pushover. 6-hour polling sync, real-time webhook for urgent events. CX Codex +1 125installs implement-plan-preflight implement-plan-preflight runs the ITP workflow preflight phase to generate MADR 4.0 architecture records, design specs, and linked diagrams. CX Codex +1 125installs

Project sponsors

Companies that keep this analytics open