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 Phases (ALL MANDATORY)

IMPORTANT: All phases are MANDATORY. Do NOT skip any phase. AskUserQuestion MUST be used at each decision point.

Phase 0: Preflight Check

Purpose: Verify asciinema is installed and supports convert command.

bash

/usr/bin/env bash << 'PREFLIGHT_EOF'
if command -v asciinema &>/dev/null; then
  VERSION=$(asciinema --version | head -1)
  echo "asciinema: $VERSION"

  # Check if convert command exists (v2.4+)
  if asciinema convert --help &>/dev/null 2>&1; then
    echo "convert: available"
  else
    echo "convert: MISSING (update asciinema to v2.4+)"
  fi
else
  echo "asciinema: MISSING"
fi
PREFLIGHT_EOF

If asciinema is NOT installed or convert is missing, use AskUserQuestion:

Question: "asciinema CLI issue detected. How would you like to proceed?"
Header: "Setup"
Options:
  - Label: "Install/upgrade asciinema (Recommended)"
    Description: "Run: brew install asciinema (or upgrade if outdated)"
  - Label: "Show manual instructions"
    Description: "Display installation commands for all platforms"
  - Label: "Cancel"
    Description: "Exit without converting"

Phase 1: File Discovery & Selection (MANDATORY)

Purpose: Discover .cast files and let user select which to convert.

Step 1.1: Discover .cast Files

bash

/usr/bin/env bash << 'DISCOVER_EOF'
# Search for .cast files with metadata
for file in $(fd -e cast . --max-depth 5 2>/dev/null | head -10); do
  SIZE=$(ls -lh "$file" 2>/dev/null | awk '{print $5}')
  LINES=$(wc -l < "$file" 2>/dev/null | tr -d ' ')
  DURATION=$(head -1 "$file" 2>/dev/null | jq -r '.duration // "unknown"' 2>/dev/null)
  BASENAME=$(basename "$file")
  echo "FILE:$file|SIZE:$SIZE|LINES:$LINES|DURATION:$DURATION|NAME:$BASENAME"
done
DISCOVER_EOF

Step 1.2: Present File Selection (MANDATORY AskUserQuestion)

Use discovery results to populate options:

Question: "Which recording would you like to convert?"
Header: "Recording"
Options:
  - Label: "{filename} ({size})"
    Description: "{line_count} events, {duration}s duration"
  - Label: "{filename2} ({size2})"
    Description: "{line_count2} events, {duration2}s duration"
  - Label: "Browse for file"
    Description: "Search in a different directory"
  - Label: "Enter path"
    Description: "Provide a custom path to a .cast file"

Phase 2: Output Options (MANDATORY)

Purpose: Let user configure conversion behavior.

Question: "Select conversion options:"
Header: "Options"
multiSelect: true
Options:
  - Label: "Plain text output (Recommended)"
    Description: "Convert to .txt with all ANSI codes stripped"
  - Label: "Create timestamp index"
    Description: "Generate [HH:MM:SS] indexed version for navigation"
  - Label: "Split by idle time"
    Description: "Create separate chunks at 30s+ pauses"
  - Label: "Preserve terminal dimensions"
    Description: "Add header with original terminal size"

Phase 3: Output Location (MANDATORY)

Purpose: Let user choose where to save the output.

Question: "Where should the output be saved?"
Header: "Output"
Options:
  - Label: "Same directory as source (Recommended)"
    Description: "Save {filename}.txt next to {filename}.cast"
  - Label: "Workspace tmp/"
    Description: "Save to ${PWD}/tmp/"
  - Label: "Custom path"
    Description: "Specify a custom output location"

Phase 4: Execute Conversion

Purpose: Run the conversion and report results.

Step 4.1: Run asciinema convert

bash

/usr/bin/env bash << 'CONVERT_EOF'
INPUT_FILE="${1:?Input file required}"
OUTPUT_FILE="${2:?Output file required}"

echo "Converting: $INPUT_FILE"
echo "Output:     $OUTPUT_FILE"
echo ""

# Run conversion
asciinema convert -f txt "$INPUT_FILE" "$OUTPUT_FILE"

if [[ $? -eq 0 && -f "$OUTPUT_FILE" ]]; then
  echo "Conversion successful"
else
  echo "ERROR: Conversion failed"
  exit 1
fi
CONVERT_EOF

Step 4.2: Report Compression

bash

/usr/bin/env bash << 'REPORT_EOF'
INPUT_FILE="${1:?}"
OUTPUT_FILE="${2:?}"

# Get file sizes (macOS compatible)
INPUT_SIZE=$(stat -f%z "$INPUT_FILE" 2>/dev/null || stat -c%s "$INPUT_FILE" 2>/dev/null)
OUTPUT_SIZE=$(stat -f%z "$OUTPUT_FILE" 2>/dev/null || stat -c%s "$OUTPUT_FILE" 2>/dev/null)

# Calculate ratio
if [[ $OUTPUT_SIZE -gt 0 ]]; then
  RATIO=$((INPUT_SIZE / OUTPUT_SIZE))
else
  RATIO=0
fi

# Human-readable sizes
INPUT_HR=$(numfmt --to=iec "$INPUT_SIZE" 2>/dev/null || echo "$INPUT_SIZE bytes")
OUTPUT_HR=$(numfmt --to=iec "$OUTPUT_SIZE" 2>/dev/null || echo "$OUTPUT_SIZE bytes")

echo ""
echo "=== Conversion Complete ==="
echo "Input:       $INPUT_HR"
echo "Output:      $OUTPUT_HR"
echo "Compression: ${RATIO}:1"
echo "Output path: $OUTPUT_FILE"
REPORT_EOF

Phase 5: Create Timestamp Index (if selected)

Purpose: Generate indexed version for navigation.

bash

/usr/bin/env bash << 'INDEX_EOF'
INPUT_CAST="${1:?}"
OUTPUT_INDEX="${2:?}"

echo "Creating timestamp index..."

# Process .cast file to indexed format
(
  echo "# Recording Index"
  echo "# Format: [HH:MM:SS] content"
  echo "#"

  cumtime=0
  tail -n +2 "$INPUT_CAST" | while IFS= read -r line; do
    # Extract timestamp and content
    ts=$(echo "$line" | jq -r '.[0]' 2>/dev/null)
    type=$(echo "$line" | jq -r '.[1]' 2>/dev/null)
    content=$(echo "$line" | jq -r '.[2]' 2>/dev/null)

    if [[ "$type" == "o" && -n "$content" ]]; then
      # Format timestamp as HH:MM:SS
      hours=$((${ts%.*} / 3600))
      mins=$(((${ts%.*} % 3600) / 60))
      secs=$((${ts%.*} % 60))
      timestamp=$(printf "%02d:%02d:%02d" "$hours" "$mins" "$secs")

      # Clean and output (strip ANSI, limit length)
      clean=$(echo "$content" | sed 's/\x1b\[[0-9;]*[a-zA-Z]//g' | tr -d '\r' | head -c 200)
      [[ -n "$clean" ]] && echo "[$timestamp] $clean"
    fi
  done
) > "$OUTPUT_INDEX"

echo "Index created: $OUTPUT_INDEX"
wc -l "$OUTPUT_INDEX"
INDEX_EOF

Phase 6: Next Steps (MANDATORY)

Purpose: Guide user to next action.

Question: "Conversion complete. What's next?"
Header: "Next"
Options:
  - Label: "Analyze with /asciinema-tools:analyze"
    Description: "Run keyword extraction on the converted file"
  - Label: "Open in editor"
    Description: "View the converted text file"
  - Label: "Done"
    Description: "Exit - no further action needed"

Batch Mode (Phases 7-9)

Batch mode converts all .cast files in a directory with organized output. Activated via

--batch

flag.

Use case: Convert 1000+ iTerm2 auto-logged recordings efficiently.

Phase 7: Batch Source Selection

Purpose: Select source directory for batch conversion.

Trigger:

--batch

flag without

--source

argument.

Question: "Select source directory for batch conversion:"
Header: "Source"
Options:
  - Label: "~/asciinemalogs (iTerm2 default)" (Recommended)
    Description: "Auto-logged iTerm2 recordings"
  - Label: "~/Downloads"
    Description: "Recent downloads containing .cast files"
  - Label: "Current directory"
    Description: "Convert .cast files in current working directory"
  - Label: "Custom path"
    Description: "Specify a custom source directory"

Skip condition: If

--source

argument provided, skip this phase.

Phase 8: Batch Output Organization

Purpose: Configure output directory structure.

Trigger:

--batch

flag without

--output-dir

argument.

Question: "Where should converted files be saved?"
Header: "Output"
Options:
  - Label: "~/Downloads/cast-txt/ (Recommended)"
    Description: "Organized output directory, easy to find"
  - Label: "Same as source"
    Description: "Save .txt files next to .cast files"
  - Label: "Custom directory"
    Description: "Specify a custom output location"

Skip condition: If

--output-dir

argument provided, skip this phase.

Phase 9: Execute Batch Conversion

Purpose: Convert all files with progress reporting.

bash

/usr/bin/env bash << 'BATCH_EOF'
SOURCE_DIR="${1:?Source directory required}"
OUTPUT_DIR="${2:?Output directory required}"
SKIP_EXISTING="${3:-true}"

mkdir -p "$OUTPUT_DIR"

echo "=== Batch Conversion ==="
echo "Source:        $SOURCE_DIR"
echo "Output:        $OUTPUT_DIR"
echo "Skip existing: $SKIP_EXISTING"
echo ""

total=0
converted=0
skipped=0
failed=0
total_input_size=0
total_output_size=0

# Count files first
total=$(find "$SOURCE_DIR" -maxdepth 1 -name "*.cast" -type f 2>/dev/null | wc -l | tr -d ' ')
echo "Found $total .cast files"
echo ""

for cast_file in "$SOURCE_DIR"/*.cast; do
  [[ -f "$cast_file" ]] || continue

  basename=$(basename "$cast_file" .cast)
  txt_file="$OUTPUT_DIR/${basename}.txt"

  # Skip if already converted (and skip mode enabled)
  if [[ "$SKIP_EXISTING" == "true" && -f "$txt_file" ]]; then
    echo "SKIP: $basename (already exists)"
    ((skipped++))
    continue
  fi

  # Get input size
  input_size=$(stat -f%z "$cast_file" 2>/dev/null || stat -c%s "$cast_file" 2>/dev/null)

  # Convert
  if asciinema convert -f txt "$cast_file" "$txt_file" 2>/dev/null; then
    output_size=$(stat -f%z "$txt_file" 2>/dev/null || stat -c%s "$txt_file" 2>/dev/null)
    if [[ $output_size -gt 0 ]]; then
      ratio=$((input_size / output_size))
    else
      ratio=0
    fi
    echo "OK:   $basename (${ratio}:1 compression)"
    ((converted++))
    total_input_size=$((total_input_size + input_size))
    total_output_size=$((total_output_size + output_size))
  else
    echo "FAIL: $basename"
    ((failed++))
  fi
done

echo ""
echo "=== Batch Complete ==="
echo "Converted: $converted"
echo "Skipped:   $skipped"
echo "Failed:    $failed"

if [[ $total_output_size -gt 0 ]]; then
  overall_ratio=$((total_input_size / total_output_size))
  echo "Overall compression: ${overall_ratio}:1"
fi
echo "Output directory: $OUTPUT_DIR"
BATCH_EOF

Phase 10: Batch Next Steps

Purpose: Guide user after batch conversion.

Question: "Batch conversion complete. What's next?"
Header: "Next"
Options:
  - Label: "Batch analyze with /asciinema-tools:analyze --batch"
    Description: "Run keyword extraction on all converted files"
  - Label: "Open output directory"
    Description: "View converted files in Finder"
  - Label: "Done"
    Description: "Exit - no further action needed"

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

TodoWrite Task Template

Single File Mode

1. [Preflight] Check asciinema CLI and convert command
2. [Preflight] Offer installation if missing
3. [Discovery] Find .cast files with metadata
4. [Selection] AskUserQuestion: file to convert
5. [Options] AskUserQuestion: conversion options (multi-select)
6. [Location] AskUserQuestion: output location
7. [Convert] Run asciinema convert -f txt
8. [Report] Display compression ratio and output path
9. [Index] Create timestamp index if requested
10. [Next] AskUserQuestion: next steps

Batch Mode (--batch flag)

1. [Preflight] Check asciinema CLI and convert command
2. [Preflight] Offer installation if missing
3. [Source] AskUserQuestion: source directory (skip if --source)
4. [Output] AskUserQuestion: output directory (skip if --output-dir)
5. [Batch] Execute batch conversion with progress
6. [Report] Display aggregate compression stats
7. [Next] AskUserQuestion: batch next steps

Post-Change Checklist

After modifying this skill:

Single File Mode

Preflight check detects asciinema version correctly
Discovery uses heredoc wrapper for bash compatibility
Compression calculation handles macOS stat syntax
All AskUserQuestion phases are present
TodoWrite template matches actual workflow

Batch Mode

```
--batch
```
flag triggers batch workflow (phases 7-10)
```
--source
```
skips Phase 7 (source selection)
```
--output-dir
```
skips Phase 8 (output organization)
```
--skip-existing
```
prevents re-conversion of existing files
Aggregate compression ratio calculated correctly
iTerm2 filename format documented

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

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

asciinema-converter

NPX Install

Tags

SKILL.md Content

asciinema-converter

When to Use This Skill

Why Convert?

Requirements

Workflow Phases (ALL MANDATORY)

Phase 0: Preflight Check

Phase 1: File Discovery & Selection (MANDATORY)

Step 1.1: Discover .cast Files

Step 1.2: Present File Selection (MANDATORY AskUserQuestion)

Phase 2: Output Options (MANDATORY)

Phase 3: Output Location (MANDATORY)

Phase 4: Execute Conversion

Step 4.1: Run asciinema convert

Step 4.2: Report Compression

Phase 5: Create Timestamp Index (if selected)

Phase 6: Next Steps (MANDATORY)

Batch Mode (Phases 7-9)

Phase 7: Batch Source Selection

Phase 8: Batch Output Organization

Phase 9: Execute Batch Conversion

Phase 10: Batch Next Steps

iTerm2 Filename Format

TodoWrite Task Template

Single File Mode

Batch Mode (--batch flag)

Post-Change Checklist

Single File Mode

Batch Mode

CLI Quick Reference

Reference Documentation

Internal References

External References

Troubleshooting