main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-demo-recording description: >- Recipe for recording a Hydrogen demo video on Linux: human-typed prompt into a Claude tab, the user's desktop screen recorder (Hydrogen has no native recorder on Linux), getting the file into the workspace, then 10-30x speedup and an adom-tts voiceover. Use when asked to record a demo, make a demo video of an app, or show what the app feels like.

hydrogen-demo-recording: a Hydrogen demo video on Linux

The canonical Adom demo: the viewer watches an AI prompt get TYPED into Hydrogen Desktop, watches the AI do the work, and hears a narrator explain it, all in a tight sped-up clip. This skill is the full pipeline. It exists because every piece is easy to get slightly wrong and the pieces live in four different tools.

On Linux Hydrogen cannot record the screen itself (/recording/native/* answers ok:false, native recording is not on this platform; see hydrogen-recording). The user records with their desktop's own recorder while you drive Hydrogen. Everything else in the pipeline is the same.

The shape of every demo:

  1. The user starts their screen recorder (GNOME: Ctrl+Shift+Alt+R, or the screenshot tool's video toggle; OBS anywhere).
  2. Type the prompt into a Claude tab with VISIBLE typing (the sexy part) and submit.
  3. Let the AI's output stream on camera.
  4. The user stops the recorder; you fetch the file.
  5. Post-production: speed up 10x to 30x (adom-video-post), overlay adom-tts narration.

Step 0: pick your calling transport

Everything below is Hydrogen control-API calls. Inside the workspace the live base URL is in a file, never an env var:

CTRL=$(cat ~/.adom/hydrogen-control-url)
curl -s -X POST "$CTRL/claude/inject" -H 'Content-Type: application/json' -d '{...}'

Step 1: preflight (30 seconds, saves the take)

  • GET /health answers with service hydrogen-desktop-control (not the SPA).
  • GET /claude/auth-check: Claude is signed in (a demo of a sign-in wall is not a demo).
  • Tell the user exactly when to start recording, and wait for their go.

Step 2: type the prompt(s) on camera

One call per prompt opens a NEW Claude tab, waits for its compose box, types with human jitter, and submits:

POST /claude/new-chat-and-send
{"text":"<the demo prompt>","typed":true,"submit":true,"delay_ms":35}
  • typed:true is the visible typing (about delay_ms per char with 50 percent jitter). typed:false pastes instantly: fine for seeding, boring on camera.
  • The call BLOCKS until typing completes: perfect for sequencing. If your call times out on a long prompt, the typing still finishes on Hydrogen's side. Do NOT re-fire. Confirm with GET /claude/conversation-state (turns went up), then continue. Keep prompts short enough to type in under about 20 seconds.
  • Single-prompt demo into the CURRENT tab instead: POST /claude/inject with the same body shape.

Multi-prompt demos (the 5-tabs pattern): repeat the call once per prompt (each opens its own tab), then flip through the finished answers on camera with the BACKGROUND tab switch:

POST /claude/tabs/activate  {"index":0}   // 0-based; or {"label":"substring"}

Verify each switch took with GET /claude/tabs (active:true moved). Pause a few seconds per tab so the sped-up video gives each answer screen time. GET /claude/conversations gives per-tab context_ids if you want to seed specific tabs deterministically (/claude/inject with context_index).

On Linux this automation runs over Hydrogen's frame bus (WebKitGTK has no DevTools protocol). Do one dry run before the user records, and look at the result with POST /screenshot (a snapshot of the whole Hydrogen window).

Step 3: collect the video

GNOME saves to the host user's ~/Videos/Screencasts/, which the workspace sees at /mnt/host/home/<host user>/Videos/Screencasts/. If that is "Permission denied", ask the user to copy the file to /tmp on their desktop and read it from /mnt/host/tmp/. Copy it into ~/project/recordings/. GNOME writes WebM; convert to h264 mp4 for the wiki:

sudo apt-get install -y ffmpeg   # once; not preinstalled
ffmpeg -i in.webm -c:v libx264 -pix_fmt yuv420p -c:a aac out.mp4

Step 4: post-production

  • Speedup: the adom-video-post skill owns this. The house style is 10x for demos where the output matters, 30x for long AI work sessions. Keep the typing segment readable (video-post can ramp: normal speed on the typing, fast on the waiting).
  • Narration: synthesize with adom-tts say (it pronounces Adom terms correctly and caches repeats), then video-post mixes it as the audio track. Write narration that explains what the viewer is SEEING at each sped-up moment.
  • Recording choreography (captions, panel staging, what makes a take clean) lives in the demo-recording skill; read it for anything fancier than a single-window take.

Known hazards

  • A Hydrogen restart mid-take resets the demo tabs. Do not run a demo while anyone (another AI thread too) is relaunching Hydrogen on the same machine.
  • Tab state reads (GET /claude/tabs) are DOM reads: labels can be briefly empty while the editor reloads. Prefer GET /claude/conversations for stable context_ids + titles.

Safety and cleanup (non-negotiable)

  • These endpoints are disruptive tier and their responses carry a _safety block: you are typing into the user's REAL Claude panel (each submitted prompt SPENDS a real turn; a 5-prompt demo spends 5). Only do it for a demo the user asked for.
  • NEVER call /claude/tabs/close-all to clean up: it closes the user's own tabs too. There is no per-tab close; leave demo tabs open and tell the user they exist.
  • Delete junk takes you pulled; do not litter recordings/ with failed attempts.

hydrogen-recording (what records on Linux), hydrogen-self-screenshot, demo-recording, adom-video-post, adom-tts.