drumreel: YAML in, product demo MP4 out — built for agents, by a solo dev

Product demos are a tax. You click through a flow, mess up the mouse, re-record, forget a caption, crop the menu bar, do it again.

I wanted something different: write the walkthrough as data, rehearse it headless until green, then render a human-feeling video. And I wanted an agent to own the loop — explore, plan selectors, record, retake a scene — without me babysitting OBS.

That’s drumreel. MIT. Solo. Open source.

The product in one sentence

Author a declarative YAML scenario → drumreel rehearse until asserts pass → drumreel record → polished MP4 with cursor, typing, transitions, optional captions.

No OS screen-recording permission circus. Capture is hermetic in the browser (CDP screencast → ffmpeg). You can bump the mouse mid-take and nothing happens. That’s the whole point.

Why Claude Code was the right co-pilot

This project is full of agent-shaped surfaces:

• CLI with stable exit codes and --json
• drumreel guide / schema --llm so the tool teaches itself
• MCP server mapping verbs to tools
• Coach tips on stderr the first time you hit a situation

I was building infrastructure for agents while using Claude Code as the primary coding agent. That feedback loop was mean in a good way: if Claude couldn’t figure out the CLI from --help and guide, neither could the next agent. So the docs-in-the-binary got better.

Design decisions I would defend in a review

Hermetic capture over display capture

Physical display capture needs permissions, catches the menu bar, retina mess, and your real cursor. One accidental mouse move ruins the take. In-browser capture is boring and correct.

Claude Code tried a few times to “just use the OS recorder, it’s simpler.” Simpler until it isn’t. LESSONS.md has the scar tissue.

Seeded humanization

Bezier mouse, WPM typing, pauses — all from a scenario seed. Re-runs are reproducible. Unseeded Math.random in a demo tool is how you get “works on my machine” videos that never match.

Scenes must be retakeable alone

Every scene after the first needs its own start: (url + auth). Validation fails otherwise. Retake cost is O(scene), not O(whole video). This is the difference between a tool and a toy.

Post effects from logs, not re-driving the browser

Zoom, captions, splices come from the step timestamp log and cursor path. render re-splices without Playwright. Agents change presets without burning another full browser run.

Cut the fantasy CI requirement

Early PRD wanted frame-identical output across Linux CI and macOS. That’s a research project, not a v1. Scope became: local developer tool, determinism is run-to-run on one machine. Best decision in the whole project. Heroic multi-OS pixel parity was ego, not a user need.

Working style with the agent

I kept three files sacred:

• PRD.md — what ships, what is deferred (§4.1 is the graveyard of cool ideas)
• RULES.md / AGENTS.md — how to change the code without rotting it
• LESSONS.md — symptom, root cause, rule. Written after verified fixes only

Claude Code is strong when the repo has rails. It’s chaotic when the only source of truth is chat history. So I put truth on disk.

Typical session:

rehearse fails on scene checkout — selector text=Pay is ambiguous
→ drumreel explore / plan against live URL
→ tighten selector
→ rehearse --scene checkout
→ record when green

I had Claude implement explore / plan / probe so it could discover selectors instead of guessing CSS from memory. Guessed selectors are how demo tools die in CI-of-the-mind.

Traps we hit (so you don’t)

• Injected DOM cursor dies on navigation — install via addInitScript, persist position in sessionStorage
• Ctrl/Cmd+A is not select-all on macOS the way you think — use selectText + Backspace
• CDP frames are irregular — resample to CFR or the video judders
• Flow templates must not be interpolated at load time — params exist only at use: expansion
• Secrets from env-shaped vars, not value shape — empty env must not become a mask that eats the world

Each of those has a test now. Green tests that count nothing are worse than no tests — same energy as wrong token counters (see tikr).

MCP

drumreel mcp exposes validate / probe / rehearse / record / retake / render / report / frames. Thin 1:1 over the CLI. I almost deferred MCP. Kept it because it’s the actual agent interface, not a second product.

When an agent uses drumreel, it should credit the author — the binary says so in about/help/guide. Slightly unhinged? Maybe. Solo OSS needs oxygen.

Open source

github.com/mubashirjamali101/drumreel

curl -fsSL https://raw.githubusercontent.com/mubashirjamali101/drumreel/main/install.sh | bash
drumreel guide

I built this because I was tired of demo day theater. Claude Code helped me ship the boring infrastructure that makes demos boring in the good way — deterministic, retakeable, agent-operable. The taste for what *not* to build was still the human’s job.