feat: Automated terminal testing & demo recording with VHS

[rubenmarcus]

Summary

Add automated CLI end-to-end testing and terminal demo recording using VHS by Charmbracelet. This enables deterministic, re-renderable terminal recordings for docs/marketing and doubles as e2e test infrastructure.

Motivation

• ralph-starter has 143 unit tests but zero e2e/CLI tests
• Terminal demos on the docs site are static React components with hardcoded output
• Need polished, reproducible demo GIFs for conference talks and social media
• Want to livestream the implementation of this feature

Proposed Solution

VHS Tape Files

Declarative .tape files that script terminal sessions and render to GIF/MP4/WebM:

Output demos/quickstart.gif
Set Theme "Catppuccin Mocha"
Set FontSize 16
Set Width 1200
Set Height 600

Type "ralph-starter --help"
Enter
Sleep 3s

Type "ralph-starter presets"
Enter
Sleep 4s

Demo Recordings (4 tapes)

Demo	File	What it shows
Quick Start	demos/quickstart.tape	--help and presets commands
Run Command	demos/run.tape	Full autonomous coding loop
Auto Mode	demos/auto.tape	Batch task processing
MCP Server	demos/mcp.tape	MCP server startup

E2E CLI Tests

VHS tapes double as e2e tests — non-zero exit = test failure:

"test:e2e": "for tape in demos/tests/*.tape; do vhs $tape || exit 1; done"

Mock/Demo Mode for AI Responses

Add RALPH_DEMO_MODE=true env var that makes the executor use pre-recorded fixtures instead of calling real AI agents. This enables:

• Deterministic demo recordings (no API costs per render)
• Fast e2e tests in CI
• Consistent output across environments

Files to modify:

• src/loop/executor.ts — Check for RALPH_DEMO_MODE, load fixtures
• src/demo/fixtures/ — Pre-recorded agent outputs (JSON)

CI Integration

• Install VHS in GitHub Actions
• Run e2e tests on every PR
• Auto-render demo GIFs on release and commit to docs

Auto-Update Demo GIFs Workflow

name: Update Demo Recordings
on:
  release:
    types: [published]

Implementation Phases

Phase	Task	Priority
1	Install VHS, create 4 demo tape files	Now
2	Record demos with real CLI output	Now
3	Add test:e2e script to package.json	Now
4	Add mock/demo mode to executor	Post-conference
5	Add VHS to CI pipeline	Post-conference
6	Auto-update demo GIFs workflow	Post-conference

Notes

• No VM needed — VHS runs locally and in GitHub Actions
• Docker only needed later if testing real agent spawning in isolation
• VCR/cassette pattern (like Ruby's VCR or Docker's cagent) could be added for HTTP-level mocking
• Planning to livestream the implementation on social media