proving-it-works

A Claude Code plugin for making a movie that proves software actually works — and for catching the defects that make such movies worthless before you hand one to anybody.

See it work

the movie the plugin made, playing inside the demo

▶ Watch the full two minutes, with sound · subtitles · how it was made

A clean container installs this plugin from the public marketplace, an agent inside it uses the skill to make a narrated movie of a small web app, and the skill's own checker verifies that movie. The loop above is that inner movie playing: real screenshots, a cursor you can watch, a local voice (there is no API key in that container), and subtitles burned into the picture.

Why

A movie is evidence, and every way it fails is silent. No crash, no red text: just an artifact that looks fine to whoever made it and is obviously broken to the first person who watches it.

This plugin exists because of a measured failure. Two agents were asked to record a narrated movie proving a small web app worked. One of them extracted frames and looked at them, ran ffprobe, checked the audio wasn't silent, asserted real DOM state at every step, and confirmed via the server log that a page reload had genuinely round-tripped. Every check passed. It shipped a movie whose picture froze three seconds in while the narration kept talking for another twenty.

Per-frame verification cannot see a defect that lives between frames. So the timeline check here is a script, not advice.

What's in it

A skill, proving-it-works-with-a-movie, that covers five routes:

Route	For
Browser	A web app in use: typing, clicking, live updates (`movie browse`)
Desktop app	Linux/X11: driven and filmed with `movie desk`; macOS and Windows: the window captured with ffmpeg
Terminal	A CLI, a TUI, an install, a test run, an agent working
Stills	A sequence of real states, motion optional
Log-rendered reel	OS capture is blocked, or the thing to prove is a run, not a UI

...plus the parts that go wrong regardless of route: narration verbatim gates, measured (never guessed) pacing, cursor visibility, ffmpeg traps, and recording against a copy of your data rather than the real thing.

The tool

One binary, run through bin/movie, which on first use downloads the build for your machine (macOS, Linux, or Windows, on x86-64 or ARM64) from this repo's GitHub release and checks it against bin/checksums.txt. It needs ffmpeg; movie term also needs tmux, movie browse needs Chrome, Chromium, or Edge, movie desk needs xdotool and ffmpeg where the display is, and the keyless local voice needs Piper (see Requirements):

Command	Does
`movie build scenes.yaml movie.mp4`	narrates (a cloud voice with a key, a local one without), assembles each scene to max(narration, visuals), writes and burns subtitles, and runs the gate
`movie check movie.mp4`	the gate, alone
`movie term ...`	films a terminal session, one narrated beat per `--say`, and writes the scene file
`movie browse ...`	films a web app driven in headless Chrome, with a drawn cursor, one narrated beat per `--say`, and writes the scene file
`movie desk ...`	films a desktop app on X11 (Linux, or Xvfb in a container) driven with real pointer and keys, one narrated beat per `say` (allowed only after a `shot`), and writes the scene file

`movie check`

The mechanical gate. It samples picture and sound on one timeline and fails a movie when the action is crammed into the opening seconds while narration continues over a frozen picture, when the picture never changes at all, or when the audio is silent. It writes a contact sheet you are then expected to actually look at.

$ skills/proving-it-works-with-a-movie/bin/movie check demo.mp4
container  h264 1280x800, 26.8s, audio=yes
picture    reaches a new state in 2 of 26 seconds; last at 3s
sound      audible in 24 of 24 seconds; last at 23s
sheet      demo-check/contact-sheet.png
FAIL       every visible change happens in the first 3s (12% of runtime),
           then the picture is frozen for 23s while narration keeps talking
           for 20s of it. The demo is over before the explanation starts:
           pace the action to the narration.

NOT SHIPPABLE. Fix, regenerate, re-run.

It cannot tell you a movie is right — only that it isn't obviously broken. That is what the contact sheet and your own eyes are for.

Install

/plugin marketplace add prime-radiant-inc/proving-it-works
/plugin install proving-it-works

The skill then activates on its own when you ask for a demo, screencast, tutorial, or proof video.

It runs on every harness below; each one reads the same skill from skills/.

Harness	Install
Claude Code	see docs/install/claude-code.md
Cursor	see docs/install/cursor.md
Codex	see docs/install/codex.md
Devin CLI	see docs/install/devin.md
Kimi Code	see docs/install/kimi.md
Gemini CLI	see docs/install/gemini.md
OpenCode	see docs/install/opencode.md
Pi	see docs/install/pi.md
Hermes Agent	see docs/install/hermes.md
Agent Plugins 1.0 clients	see docs/install/agent-plugins-1.0.md
Factory Droid / Grok / Copilot (marketplace descriptor)	see docs/install/agents-marketplace.md

Requirements

ffmpeg and ffprobe
For the keyless voice: Piper (uv tool install piper-tts), see the skill's narrating.md
For filming web apps: Chrome, Chromium, or Edge (Playwright only for what movie browse cannot drive)
tmux, for filming terminals

Tests

go test ./...

Synthesizes movies with known defects via ffmpeg's lavfi sources and asserts each verdict, builds real movies at awkward paths, and drives real tmux sessions.

Credits

The stills and log-rendered-reel routes are adapted from rendering-a-demo-movie.md and recording-a-proof-movie.md in obra/superpowers PR #1931 (MIT). The rest comes from producing a real narrated product tutorial and from the baseline experiments described above.

License

MIT — see LICENSE.