fraude

Terminal session playback tool that takes a YAML script and plays it back as a realistic Claude Code session, or records it to an asciicast file. Designed for making educational screencasts on techniques for using agentic coding tools.

Quick Start

bun install
bun run build

# Play in terminal
bin/fraude play scripts/example.yaml

# Render to GIF or MP4
brew install agg ffmpeg gifsicle
scripts/render.sh scripts/example.yaml demo.mp4
scripts/render.sh scripts/example.yaml demo.gif

# Validate a script
bin/fraude validate scripts/example.yaml

Press Space to pause/resume during playback. Press Ctrl+C to exit.

What It Does

fraude reads a YAML script file describing a multi-turn Claude Code session and renders it in the terminal with visual effects:

• Typewriter effect for human prompts
• Streaming appearance for agent responses
• Spinner animations for thinking and annotation scenes
• Tool call output with Claude Code's indentation styling
• Question selection UI with animated choice
• Highlight flash effects
• Section transitions with centered titles
• Scrolling credits
• Persistent "Simulation" disclaimer banner

Record mode produces an asciicast v2 file instantly (no real-time waiting) using a virtual clock. Convert to GIF with agg or play with asciinema.

Script Format

Scripts are YAML document streams. The first document is a meta block; subsequent documents are scenes. See docs/guide.md for the full format reference.

---
meta:
  disclaimer: Based on an actual session
---
type: human
text: show me the bug
---
type: agent
text: |
  Found it. The issue is in the error handler —
  it swallows the exception silently.
---
type: tool_call
command: Bash(bun test)
output: |
  3 pass, 0 fail

Commands

Command	Description
fraude play <script.yaml> [--line N]	Play script in terminal (optionally from line N)
fraude record <script.yaml> -o <file.cast>	Record to asciicast file
fraude validate <script.yaml>	Validate script without playing

Development

bun test          # Run tests
bun run lint      # Lint with Biome
bun run typecheck # TypeScript check
bun run build     # Compile binary

Transcript-to-Script Skill

A Claude Code skill is included at skills/transcript-to-script/ that can generate script drafts from real Claude Code conversation logs (JSONL files). It maps user messages, agent responses, tool calls, and thinking blocks to the appropriate scene types. The output is a draft meant for editing — editorial scenes like transitions, questions, and credits are added manually.

License

MIT