Asciinema Converter

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?

Key benefit: Claude Code's Read and Grep tools work directly on .txt output.

---

Requirements

---

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)

Full implementation details: Workflow Phases

Batch Mode (Phases 7-10)

Activated via --batch flag. Converts all .cast files in a directory with organized output.

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

---

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

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.

Anti-Patterns in asciinema Conversion

Common mistakes and their remediation when converting .cast files to .txt.

Wrong Format Flag

Problem

Using -f raw instead of -f txt produces NDJSON output, not clean text.

# WRONG: Raw format preserves ANSI codes
asciinema convert -f raw input.cast output.txt  # Still has ANSI!

# CORRECT: Text format strips ANSI
asciinema convert -f txt input.cast output.txt

Impact

• ANSI escape sequences bloat file size
• Claude Code Read/Grep tools see garbage characters
• Compression ratio significantly worse (~10:1 vs ~950:1)

Detection

# Check for ANSI escape codes in output
grep -P '\x1b\[' output.txt && echo "ERROR: ANSI codes present"

---

Memory Issues with Large Files

Problem

Files >1GB can cause memory exhaustion during conversion.

Symptoms

• asciinema convert hangs or crashes
• System becomes unresponsive
• Error: "MemoryError" or "Killed"

Impact

• ~5% of iTerm2 auto-logged sessions exceed 1GB
• Typical 8-hour coding session: 200MB-500MB
• 24-hour sessions or high output: 1-4GB

Remediation

# Check file size before conversion
file_size=$(stat -f%z "$cast_file" 2>/dev/null || stat -c%s "$cast_file")
if [[ $file_size -gt 1073741824 ]]; then  # 1GB
  echo "WARNING: File >1GB, may cause memory issues"
  # Consider splitting or streaming approach
fi

Workaround for Large Files

# Stream-process large files (experimental)
tail -n +2 large.cast | jq -r '.[2]' | \
  sed 's/\x1b\[[0-9;]*[a-zA-Z]//g' > output.txt

---

Path Handling Issues

Problem

Filenames with spaces, special characters, or Unicode cause failures.

Common Failures

# WRONG: Unquoted paths fail with spaces
asciinema convert $FILE output.txt  # Fails if path has spaces

# WRONG: Glob patterns expand unexpectedly
for f in *.cast; do  # Fails if no .cast files exist

Correct Handling

# ALWAYS quote paths
asciinema convert "$cast_file" "$txt_file"

# Guard against empty globs
shopt -s nullglob
for cast_file in "$SOURCE_DIR"/*.cast; do
  [[ -f "$cast_file" ]] || continue
  # ...
done

iTerm2 Filename Gotcha

iTerm2 profile names can contain dots and spaces:

• Claude Code → spaces
• my.profile.name → dots look like extensions

# This filename has profile "Claude Code" with spaces
20260118_232025.Claude Code.w0t1p1.UUID.pid.id.cast

---

Missing Preflight Check

Problem

Running conversion without verifying asciinema is installed or supports convert.

Symptoms

• command not found: asciinema
• Error: Unknown command 'convert' (old asciinema version)

Remediation

Always run preflight before conversion:

# Check asciinema exists and convert command works
if ! command -v asciinema &>/dev/null; then
  echo "ERROR: asciinema not installed"
  exit 1
fi

if ! asciinema convert --help &>/dev/null 2>&1; then
  echo "ERROR: asciinema convert not available (need v2.4+)"
  exit 1
fi

---

Re-Converting Unchanged Files

Problem

Batch conversion without skip logic wastes CPU on already-converted files.

Impact

• 2400 files × 5 seconds = 3.3 hours wasted
• Disk I/O thrashing
• Repeated compression calculations

Remediation

Always use skip-existing logic:

txt_file="$OUTPUT_DIR/${basename}.txt"

# Skip if already converted
if [[ -f "$txt_file" ]]; then
  echo "SKIP: $basename (already exists)"
  ((skipped++))
  continue
fi

Advanced: Size-Based Invalidation

# Re-convert if source is newer or larger
cast_mtime=$(stat -f%m "$cast_file" 2>/dev/null)
txt_mtime=$(stat -f%m "$txt_file" 2>/dev/null)

if [[ -f "$txt_file" && "$txt_mtime" -gt "$cast_mtime" ]]; then
  echo "SKIP: $basename (up to date)"
  continue
fi

---

Mixing Batch and Single Mode

Problem

Using both positional file argument and --batch flag causes undefined behavior.

Example

# UNDEFINED: What should this do?
/asciinema-tools:convert session.cast --batch

Remediation

Mutual exclusivity check:

if [[ -n "$FILE" && "$BATCH_MODE" == "true" ]]; then
  echo "ERROR: Cannot use both file argument and --batch"
  echo "Use: /asciinema-tools:convert FILE           # Single file"
  echo "Or:  /asciinema-tools:convert --batch        # Directory"
  exit 1
fi

---

Ignoring Conversion Failures

Problem

Silent failures in batch mode leave partially converted directories.

Symptoms

• Missing .txt files for some .cast files
• No error log
• Inconsistent output directory

Remediation

Track and report failures:

failed=0
failed_files=()

for cast_file in "$SOURCE_DIR"/*.cast; do
  if ! asciinema convert -f txt "$cast_file" "$txt_file" 2>/dev/null; then
    echo "FAIL: $basename"
    ((failed++))
    failed_files+=("$basename")
  fi
done

# Report failures at end
if [[ $failed -gt 0 ]]; then
  echo ""
  echo "=== FAILED FILES ==="
  printf '%s\n' "${failed_files[@]}"
fi

---

Checklist

Before running conversions:

• [ ] Preflight check passed (asciinema installed, convert available)
• [ ] Using -f txt format flag
• [ ] All paths are quoted
• [ ] Skip-existing logic enabled for batch
• [ ] Large file warning for >1GB files
• [ ] Failure tracking enabled

---

Related

• Batch Processing - Patterns for bulk conversion
• Integration Guide - Chaining with analyze

Batch Processing Patterns

Patterns and best practices for bulk conversion of .cast files.

Directory Organization

Recommended Structure

~/Downloads/cast-txt/           # Default output directory
├── 20260118_232025.Claude Code.w0t1p1.*.txt
├── 20260118_235012.Claude Code.w0t2p1.*.txt
└── ...

Alternative: Date-Based Hierarchy

For archives with thousands of files:

~/.local/share/asciinema-txt/
├── 2026/
│   ├── 01/
│   │   ├── 18/
│   │   │   ├── session-001.txt
│   │   │   └── session-002.txt
│   │   └── 19/
│   └── 02/
└── 2025/

Source Directories

---

Skip/Resume Logic

Basic Skip (Default)

Skip files that already have corresponding .txt:

txt_file="$OUTPUT_DIR/${basename}.txt"

if [[ -f "$txt_file" ]]; then
  echo "SKIP: $basename (already exists)"
  ((skipped++))
  continue
fi

Timestamp-Based Invalidation

Re-convert if source is newer:

cast_mtime=$(stat -f%m "$cast_file" 2>/dev/null)
txt_mtime=$(stat -f%m "$txt_file" 2>/dev/null || echo 0)

if [[ -f "$txt_file" && "$txt_mtime" -ge "$cast_mtime" ]]; then
  echo "SKIP: $basename (up to date)"
  continue
fi

Force Re-Convert

Disable skip logic with --skip-existing=false:

if [[ "$SKIP_EXISTING" != "false" && -f "$txt_file" ]]; then
  echo "SKIP: $basename"
  continue
fi

---

Progress Reporting

Per-File Progress

echo "[$current/$total] Converting: $basename"

Aggregate Summary

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

Compression Ratio Reporting

# Per-file ratio
ratio=$((input_size / output_size))
echo "OK: $basename (${ratio}:1)"

# Aggregate ratio
if [[ $total_output_size -gt 0 ]]; then
  overall_ratio=$((total_input_size / total_output_size))
  echo "Overall compression: ${overall_ratio}:1"
fi

---

Handling 1000+ Files

Memory-Efficient Iteration

Avoid loading all filenames into memory:

# WRONG: Loads all names into array
files=($(find . -name "*.cast"))

# CORRECT: Stream processing
find "$SOURCE_DIR" -maxdepth 1 -name "*.cast" -type f | while read -r cast_file; do
  # Process one at a time
done

Size-Tiered Processing

Process largest files first to identify memory issues early:

# Sort by size descending, process largest first
find "$SOURCE_DIR" -maxdepth 1 -name "*.cast" -type f -print0 | \
  xargs -0 ls -S | while read -r cast_file; do
    # Largest files first
done

Parallel Processing (Advanced)

Use GNU parallel for multi-core conversion:

# Requires: brew install parallel
find "$SOURCE_DIR" -name "*.cast" | \
  parallel -j4 'asciinema convert -f txt {} {.}.txt'

Caution: Monitor memory usage with parallel conversion of large files.

---

iTerm2 Auto-Log Filename Parsing

Filename Format

{creationTimeString}.{profileName}.{termid}.{iterm2.pid}.{autoLogId}.cast

Example

20260118_232025.Claude Code.w0t1p1.70C05103-2F29-4B42-8067-BE475DB6126A.68721.4013739999.cast

Component Extraction

Parse from right to left (most reliable):

filename="20260118_232025.Claude Code.w0t1p1.70C05103-2F29-4B42-8067-BE475DB6126A.68721.4013739999.cast"

# Remove .cast extension
base="${filename%.cast}"

# Extract autoLogId (last component)
autoLogId="${base##*.}"
base="${base%.*}"

# Extract pid
pid="${base##*.}"
base="${base%.*}"

# Extract UUID (contains hyphens)
uuid="${base##*.}"
base="${base%.*}"

# Extract termid (w#t#p# format)
termid="${base##*.}"
base="${base%.*}"

# Remaining is: creationTimeString.profileName
# Profile name can have dots, so extract timestamp first
timestamp="${base%%.*}"
profileName="${base#*.}"

Metadata Extraction

# Parse creation timestamp
timestamp="20260118_232025"
date="${timestamp:0:8}"      # 20260118
time="${timestamp:9:6}"      # 232025
year="${date:0:4}"           # 2026
month="${date:4:2}"          # 01
day="${date:6:2}"            # 18

---

Error Handling

Allow-on-Error Semantics

Continue batch even when individual files fail:

for cast_file in "$SOURCE_DIR"/*.cast; do
  if ! asciinema convert -f txt "$cast_file" "$txt_file" 2>/dev/null; then
    echo "FAIL: $basename"
    ((failed++))
    failed_files+=("$cast_file")
    continue  # Don't abort batch
  fi
done

Error Log

Write failures to log file:

ERROR_LOG="$OUTPUT_DIR/.conversion-errors.log"

if ! asciinema convert -f txt "$cast_file" "$txt_file" 2>>"$ERROR_LOG"; then
  echo "FAIL: $basename (see $ERROR_LOG)"
fi

Post-Batch Summary

if [[ $failed -gt 0 ]]; then
  echo ""
  echo "=== FAILED FILES ($failed) ==="
  printf '%s\n' "${failed_files[@]}"
  echo ""
  echo "Re-run failed files:"
  echo "for f in ${failed_files[*]}; do asciinema convert -f txt \"\$f\" \"${OUTPUT_DIR}/\$(basename \"\$f\" .cast).txt\"; done"
fi

---

Performance Benchmarks

Typical Conversion Speeds

Batch Estimates

---

Related

• Anti-Patterns - Common mistakes to avoid
• Integration Guide - Chaining with analyze

Batch Mode Workflow (Phases 7-10)

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.

/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"

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the asciinema-converter skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

Integration Guide

How to chain asciinema-converter with other asciinema-tools skills.

Skill Chain Overview

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   .cast     │────▶│   convert   │────▶│    .txt     │
│  (NDJSON)   │     │             │     │ (clean text)│
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          │                          │
                    ▼                          ▼                          ▼
            ┌─────────────┐            ┌─────────────┐            ┌─────────────┐
            │   analyze   │            │  summarize  │            │    Read     │
            │ (keywords)  │            │ (AI deep)   │            │ (manual)    │
            └─────────────┘            └─────────────┘            └─────────────┘

Single File Chains

Convert → Analyze

Extract keywords and patterns from a single converted file:

# Step 1: Convert
/asciinema-tools:convert ~/Downloads/session.cast

# Step 2: Analyze (auto-chained with --analyze flag)
/asciinema-tools:convert ~/Downloads/session.cast --analyze

Or run separately:

/asciinema-tools:analyze ~/Downloads/session.txt

Convert → Summarize

Deep AI analysis of session content:

# Convert first
/asciinema-tools:convert ~/Downloads/session.cast -o ~/tmp/session.txt

# Then summarize
/asciinema-tools:summarize ~/tmp/session.txt

---

Batch Chains

Batch Convert → Batch Analyze

Convert all files, then analyze all outputs:

# Step 1: Batch convert
/asciinema-tools:convert --batch --source ~/Downloads --output-dir ~/cast-txt/

# Step 2: Batch analyze (if skill supports it)
/asciinema-tools:analyze --batch --source ~/cast-txt/

Post-Session Workflow

Complete workflow for session wrap-up:

/asciinema-tools:post-session

This internally chains:

1. finalize - Stop active recordings 2. convert - Convert to .txt 3. summarize - Generate AI summary

---

File Path Conventions

Naming Pattern

Output files preserve base name:

Directory Structure

When using --output-dir:

Index Files

When --index flag used:

---

Manifest Files (Advanced)

For automated pipelines, batch convert generates a manifest:

{
  "source_dir": "~/Downloads",
  "output_dir": "~/cast-txt",
  "converted": [
    {
      "source": "session1.cast",
      "output": "session1.txt",
      "size_input": 104857600,
      "size_output": 131072,
      "compression_ratio": 800
    }
  ],
  "skipped": ["session2.cast"],
  "failed": [],
  "timestamp": "2026-01-19T12:00:00Z"
}

Location: $OUTPUT_DIR/.convert-manifest.json

Using Manifest for Downstream Skills

# Read manifest and process converted files
jq -r '.converted[].output' ~/cast-txt/.convert-manifest.json | \
  while read -r txt_file; do
    /asciinema-tools:analyze "$txt_file"
  done

---

Workflow Commands

Full Workflow

Record, convert, and analyze in one command:

/asciinema-tools:full-workflow

Chains:

1. record → Start recording 2. (user works) 3. convert → Convert to .txt 4. analyze → Extract insights

Bootstrap

Pre-session setup:

/asciinema-tools:bootstrap

Outputs a script to start recording before entering Claude Code.

Post-Session

End-of-session cleanup:

/asciinema-tools:post-session

Chains:

1. finalize → Stop orphaned recordings 2. convert → Convert recent .cast files 3. summarize → AI analysis

---

Error Handling in Chains

Fail-Fast (Single File)

If convert fails, subsequent skills don't run:

# This aborts if conversion fails
/asciinema-tools:convert session.cast --analyze

Continue-on-Error (Batch)

Batch mode continues even if individual files fail:

# Converts all possible files, reports failures at end
/asciinema-tools:convert --batch

Chain Recovery

If a downstream skill fails:

# Re-run just the failed step
/asciinema-tools:analyze ~/cast-txt/session.txt

# Don't re-convert (already done)

---

Performance Considerations

Chaining Overhead

Parallel Batch Analysis

For large batches, run analysis in parallel:

# Convert first (sequential for disk I/O)
/asciinema-tools:convert --batch --output-dir ~/cast-txt/

# Then analyze in parallel (CPU-bound)
find ~/cast-txt -name "*.txt" | parallel -j4 '/asciinema-tools:analyze {}'

---

Related

• Anti-Patterns - Common mistakes to avoid
• Batch Processing - Bulk conversion patterns
• asciinema-analyzer skill - Keyword extraction and semantic analysis
• /asciinema-tools:summarize command - AI-powered iterative deep-dive analysis

Post-Change Checklist

After modifying this skill:

Single File Mode

1. [ ] Preflight check detects asciinema version correctly 2. [ ] Discovery uses heredoc wrapper for bash compatibility 3. [ ] Compression calculation handles macOS stat syntax 4. [ ] All AskUserQuestion phases are present 5. [ ] TodoWrite template matches actual workflow

Batch Mode

1. [ ] --batch flag triggers batch workflow (phases 7-10) 2. [ ] --source skips Phase 7 (source selection) 3. [ ] --output-dir skips Phase 8 (output organization) 4. [ ] --skip-existing prevents re-conversion of existing files 5. [ ] Aggregate compression ratio calculated correctly 6. [ ] iTerm2 filename format documented

TodoWrite Task Templates

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

Workflow Phases (Single File Mode)

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.

/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

/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

/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

/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.

/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"