name: vhs description: Techniques for creating deterministic terminal demo screencasts with VHS

VHS Demo Recording

VHS records terminal sessions by scripting keystrokes in .tape files and rendering them as GIFs. Use Wait+Screen /regex/ to synchronize with interactive TUI elements instead of fragile fixed Sleep durations. VHS can only detect text appearing on screen, not disappearing — keep this constraint in mind when designing wait conditions.

Non-Deterministic TUI Responses

When recording an LLM-powered TUI, detecting when a response is complete requires special care. Naive approaches all fail:

The concatenation trick

Ask the LLM to concatenate two words and print the result. The prompt contains both words separately but never the combined string:

Type "briefly explain this repo. Then print ALFA concatenated with BRAVO."
Enter
Wait+Screen /ALFABRAVO/

Why it works:

1. Typed prompt shows ...ALFA concatenated with BRAVO — no ALFABRAVO
2. Thinking trace says "I need to concatenate ALFA and BRAVO" — no ALFABRAVO
3. Response outputs ALFABRAVO — the only match

Use uncommon words (ALFA, BRAVO, ZULU) so the combined form can't appear accidentally.

Tips

• Run VHS from the correct CWD — it inherits the working directory. If the prompt references "this repo", the CWD must be the repo root, not a subdirectory.
• Inspect GIF frames when debugging timing issues:

  ffmpeg -i demo.gif -vf "select='eq(n\,100)'" -vsync vfr /tmp/frame.png
  

Nix Integration

• If the project uses Nix, create a dedicated flake.nix for the demo (e.g., doc/demo/flake.nix) so anyone can reproduce the recording with nix run.
• Reference tape by Nix store path in flake apps (vhs "${./.}/demo.tape") — don't cd into the store, as it may contain a flake.nix that confuses nix run inside the recording.