Verified, polished demo videos of the features you ship — from one JSON scenario.
Getting started · Wiki · CLI reference · MCP server · Roadmap
DemoFlow drives your web app in Chromium through a short scenario — navigate, click, fill, assert — and records it. If an assertion fails, the run fails and the video says so; a demo that shows a broken feature never looks like a working one.
The recording is then rendered into an MP4 with a smooth drawn cursor, click rings, camera zoom on the steps that ask for it, captions, idle time compressed, and the page in a rounded window on a background. Passwords come from environment variables, never touch disk or logs, and are blurred in the video.
Everything runs on your machine. Run it from the command line, from CI, or let an AI agent such as Claude Code ask for a demo over MCP.
| Feature | What it does |
|---|---|
| Scenarios | A JSON file with up to 200 steps and accessible-role locators, validated by a JSON Schema. Data lists and a repeat step run the same steps once per item. |
| Running demos | demoflow run checks readiness, starts your app if configured, runs the steps and renders the video. |
| Recording scenarios | demoflow record writes the scenario while you click through the app in a browser. |
| Rendering and effects | An FFmpeg compositor adds cursor, rings, zoom, captions, key badges, a window frame and a background. |
| Secrets and masking | valueFrom.env keeps secrets out of files and logs; their fields are blurred in the video. |
| Run artifacts | Every run leaves the video, a timeline and a result.json with per-stage status and exit codes for CI. |
| MCP server | demoflow mcp lets Claude Code generate a demo, poll the task and get the video path back. |
Note
demoflow@0.1.0 on npm has run, validate, setup and mcp. record,
the press step, starting the app from devCommand, key badges and the
window frame are on develop and ship in the next release, with cards,
transitions, GIF/WebM export and the vertical 9:16 MP4 (mp4-vertical), as
do login, logout and the background runner with online status. Jobs
over the Runner connection are not built yet — see Status and Roadmap.
flowchart LR
S["scenario.demo.json"] --> RD["readiness<br/>origins · env secrets"]
RD --> EX["execution<br/>Chromium runs the steps"]
EX --> VE["verification<br/>assertions"]
VE --> RC["recording<br/>source.webm + timeline"]
RC --> RN["rendering<br/>FFmpeg compositor"]
RN --> MP4["render/ffmpeg.mp4<br/>result.json"]
flowchart TB
CC["Claude Code"] -->|"MCP · stdio"| CLI
YOU["You / CI"] --> CLI["demoflow CLI"]
CLI --> ENG["engine<br/>Playwright"] --> REN["renderer<br/>FFmpeg"]
CORE["core<br/>zod contracts"] -.-> CLI
CORE -.-> ENG
CORE -.-> REN
- Recording is separate from rendering — the source stays a faithful capture; every effect is applied afterwards from the timeline (ADR-0004, ADR-0005).
- Scenarios and config are data, never code — JSON an agent can write and a person can review (ADR-0003).
- Local first — the browser, your app and your secrets stay on your machine (ADR-0001, ADR-0008).
More in Architecture.
Needs Node.js 22+. Create demoflow.config.json in your project:
{ "baseUrl": "http://localhost:3000" }Write demoflow/first.demo.json:
{
"schemaVersion": 1,
"name": "Open the settings",
"steps": [
{ "action": "navigate", "path": "/" },
{ "action": "click", "target": { "role": "link", "name": "Settings" }, "caption": "Open the settings" },
{ "action": "assertVisible", "target": { "role": "heading", "name": "Settings" } }
]
}With your app running:
npx demoflow run demoflow/first.demo.jsonChromium is downloaded on first use. The summary prints the path of the video.
To connect Claude Code instead: claude mcp add demoflow -- npx demoflow mcp.
A scenario can declare data lists and run a group of steps once per item.
{{post.text}} is the item's text field and {{index}} its 1-based
position; they work in every string of a step inside the repeat:
{
"schemaVersion": 1,
"name": "Post three updates",
"data": {
"posts": [{ "text": "Hello" }, { "text": "Shipping today" }, { "text": "Thanks!" }]
},
"steps": [
{ "action": "navigate", "path": "/feed" },
{
"action": "repeat",
"each": "posts",
"as": "post",
"caption": "Three posts",
"steps": [
{ "action": "click", "target": { "role": "button", "name": "Compose" } },
{ "action": "fill", "target": { "label": "Post" }, "value": "{{post.text}}" },
{ "action": "click", "target": { "role": "button", "name": "Publish" } }
]
}
]
}- A list holds 1–100 items of strings, numbers and booleans;
asdefaults toitem; arepeatholds 1–50 steps and norepeatof its own. - Its
captionis shown once, before the first iteration. - Every field a step uses must be in every item, and a URL, path or key must
be valid once filled in.
demoflow validatereports any problem by step path (steps[1].steps[1].value) before anything runs. {{…}}is an error outside arepeatand invalueFrom; write\\{{in JSON for a literal{{.- The timeline and
result.jsoncount the expanded steps, and tag each withorigin: { repeatIndex, iteration }(0-based). A failure readsstep 4 (repeat steps[1], iteration 3).
demoflow login prints a code, opens the website, and stores a revocable
device token once you approve the code there. demoflow logout revokes it.
Every other command works without an account. See
apps/cli/README.md.
demoflow runner start keeps the paired machine connected in the background,
so /app/machines shows it online. See
apps/cli/README.md.
| Where | What |
|---|---|
| Wiki | How to use and operate DemoFlow: one page per feature, configuration, CLI and MCP reference, FAQ |
docs/adr/ |
Architecture decisions, one per record, superseded never rewritten |
docs/specs/ |
One specification per issue |
docs/product/ |
Product vision and roadmap |
apps/cli/README.md |
The README shipped in the npm package |
deploy/README.md |
Staging deploy and npm release, for maintainers |
Bun workspaces and Turborepo; bun install, then bun run check and
bun run test. Pull requests target develop. Local setup (Docker, env files) is in
Contributing and CLAUDE.md.
MIT. The bundled Inter fonts are under the SIL Open Font License 1.1.