recording-rig

recording-rig

A reusable, language-agnostic framework for recording deterministic Claude Code sessions — tutorials, demos, screencasts, regression fixtures, anything you want repeatable. Hook-driven coordination, no TUI scraping. See docs/design.md for the rationale.

Getting started — single-pane

Agent runs doctor.sh, lists examples/, cats a spec. Spec: test-runs/tutorial-intro.json.

Gated path — auto-answer AskUserQuestion

Agent calls AskUserQuestion with ['production', 'staging', 'dev']; rig sends Down + Enter to pick option 2 (staging); agent confirms DEPLOY_TARGET-K7Q=staging. must_not_contain blocks the other two answers, so the gate-navigation mechanism is provable end-to-end. Spec: test-runs/tutorial-gated.json.

Two-pane path — companion observer subscribed to a hook sentinel

Agent uses Bash to emit JOB_ID=…; PostToolUse[^Bash$] hook extracts it to a sentinel; companion node observer.mjs (right pane) waits on the sentinel, reads JOB_ID from env, prints lifecycle ticks. Spec: test-runs/tutorial-twopane.json; observer: test-runs/observer.mjs.

Multi-command path — agent.commands[] across turns

Three sequential prompts; rig deletes turn-end before each paste so per-command idle detection works. must_contain_in_order enforces strict reply ordering. Spec: test-runs/tutorial-multicmd.json.

Quick start — as a Claude Code plugin

This repo is also a Claude Code plugin. Install it once and the rig becomes available as skills and slash commands in any project:

/recording-rig:doctor                 verify prereqs
/recording-rig:author [out.json]      interactively author a spec
/recording-rig:record path/spec.json  run a recording
/recording-rig:diagnose <session>     forensics on a failed run

The skills (record, author-spec, doctor, diagnose) also trigger on natural prose like "make a gif of this skill" or "diagnose my failed rig run".

Quick start — as standalone scripts

# 1. Verify prereqs
bin/doctor.sh

# 2. Write a spec
cp examples/single-pane.json my-recording.json
$EDITOR my-recording.json

# 3. Record
bin/record.sh my-recording.json

# Outputs:
#   /tmp/<session>.cast   (lossless asciinema cast)
#   /tmp/<session>.gif    (agg-rendered GIF; only if validation passes)

What the rig gives you

• Hook-driven coordination. A generated --settings file installs lifecycle hooks (UserPromptSubmit, Stop, PreToolUse[AskUserQuestion], PostToolUse, SessionStart) that drop sentinel files. The driver watches sentinels, not pane text.
• Multi-turn idle detection. The Stop hook touches a turn-end sentinel every turn. Idle = mtime hasn't moved for N seconds. Works uniformly for single-turn and multi-turn flows.
• Multi-command tutorials. agent.commands[] runs commands in sequence; gates can target specific commands via gates[].for_command.
• Reliable gate handling. AskUserQuestion gates are handled by ordered gate decisions in the spec. The driver navigates to option N via (N−1) Down keypresses then Enter, holding for pre/post-Enter seconds for readability.
• Consent sweep. Before recording, an auxiliary tmux session (not captured) dismisses Claude's two interactive consent dialogs (--dangerously-skip-permissions legal accept; per-workspace trust). Skip with SKIP_CONSENT_SWEEP=1. This is the only place the rig does TUI screen-scrape, and it's outside the recorded window.
• Autonomous termination. Driver sends /exit (falling back to C-c + C-d) when work is done so the tmux pane dies, asciinema returns, and the recording completes without manual intervention. A backstop in record.sh also kills the session once the agent-done sentinel has been present long enough.
• Two-pane lockstep (optional). A companion pane can subscribe to backend state via sentinels emitted by the agent's PostToolUse hook. One drives, the other observes.
• Validation gate. Before rendering the GIF, parse the cast (ANSI/CSI escapes stripped) for required positive signals, optional in-order signals, and forbidden failure markers. Refuse to render on mismatch (override with SKIP_VALIDATE=1).

Spec format

A tutorial is one JSON file. Fields:

{
  "session": "my-tutorial",            // [A-Za-z0-9._-]+; auto-generated if absent