Aidemo

aidemo — your coding agent makes the demo video

[aidemo.top](https://aidemo.top) · watch a real 51s output ▶ · authoring guide · render in CI

Tell your coding agent *"record a 45s demo of the checkout flow"* — get back a polished MP4 with voiceover, synced captions, and auto-zoom. Any MCP-capable agent (Claude Code, Codex CLI, Gemini CLI) writes one storyboard.json; the headless engine drives a real Chrome, records a deterministic replay, voices it, captions it, and trims the dead time. Because the replay is deterministic, the demo re-renders itself in CI when the product changes — no re-recording, no API key, about $0 a render. An open-source (MIT) alternative to Screen Studio, Clueso, or Demosmith for when you'd rather your coding agent make the demo.

Install: Claude Code /plugin marketplace add tandryukha/aidemo · any agent npx skills add tandryukha/aidemo (skill only; add the MCP server with repo-init) · CI uses: tandryukha/aidemo@stable · CLI npx -y @tandryukha/aidemo · Homebrew brew install tandryukha/aidemo/aidemo

Published on the GitHub Marketplace, npm, a Homebrew tap, and the MCP Registry.

Real output — a ~51 s self-narrated tour of Wikipedia (portal search → Ada Lovelace → focus-zoom → click through to the Analytical Engine → glide scroll), authored by Claude from one storyboard.json and recorded as a deterministic replay. The preview GIF is silent; [watch the full version with narration ▶](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/wikipedia-showcase-demo.mp4).

Three ways to use it

1. From your coding agent — the fastest path. In Claude Code: /plugin marketplace add tandryukha/aidemo then /plugin install record-demo@aidemo (bundles the skill and the MCP server). In Codex / Gemini / any MCP agent: npx -y github:tandryukha/aidemo#stable repo-init. Then just say *"record a 45s demo of <flow>"* and the agent authors + renders it.
2. Locally, free & offline — AIDEMO_TTS_PROVIDER=local aidemo render --headless. An in-process voice model + script-timed captions mean no API key, ~$0, fully offline. See docs/LOCAL_MODELS.md.
3. In CI, self-maintaining — drop uses: tandryukha/aidemo@stable into a workflow. When the product changes, it replays the committed storyboard and commits fresh media — no key, no LLM tokens, ~$0 on free runner minutes. See docs/CI.md.

Free & open source. MIT-licensed. Runs on GitHub's free Actions tier, or fully local at $0 with the in-process voice — no API key, no cloud upload, no telemetry. Works against localhost and auth-walled apps (your own Chrome).

From one sentence to a narrated MP4

You type a sentence, the agent writes an artifact you can read and edit, the engine records and cuts it:

1 · What you type — one line to any MCP-capable agent (Claude Code here):

claude "record a 45s demo touring Wikipedia: search for Ada Lovelace,

open the Analytical Engine, then glide down the article"

2 · What the agent authors — a plain, editable storyboard.json (excerpt: narration + a fixed browser action-spec, side by side — no generated code):

{

"title": "A quick tour of Wikipedia", "zoom": {}, // Screen-Studio-style auto-zoom "scenes": [ { "id": "search", "narration": "Start at the Wikipedia portal and search for Ada Lovelace.", "actions": [ { "op": "goto", "url": "https://www.wikipedia.org/" }, { "op": "type", "target": { "selector": "#searchInput" }, "text": "Ada Lovelace" }, { "op": "click", "target": { "selector": "button[type=submit]" } } ] }, { "id": "engine", "narration": "Her notes on Babbage's Analytical Engine hold the first computer program.", "actions": [ { "op": "focus", "target": { "selector": "#firstHeading" } }, { "op": "click", "target": { "selector": "a[href*='Analytical_Engine']" } }, { "op": "scrollBy", "dy": 900, "easing": "glide" } ] } ] }

3 · How it's recorded + cut — aidemo render drives a real Chrome (smooth animated cursor, human-cadence typing, auto-zoom), then trims the dead time and syncs to the narration:

storyboard.json

→ voice OpenAI / ElevenLabs / local TTS → audio/narration.mp3 + voice.json → record drives Chrome, animated cursor → recordings/raw.{webm,mp4} + timeline.json → captions Whisper word timestamps → generated/captions.{srt,vtt,cues.json} → compose trim idle · sync · auto-zoom · cards · caption · mux → output/final-demo.mp4

4 · What you get — output/final-demo.mp4 with final-demo.srt/.vtt captions beside it (timed to the video; captions.track also embeds them as a subtitle track viewers can toggle), plus a README-ready GIF (aidemo gif) and named stills (aidemo stills) from the same take. UI changed? Re-run against the same storyboard — no re-recording by hand.

The design goal: demos that look human-made and snappy, not like an AI clicking around and waiting between screenshots — by separating authoring (slow, one-time — figure out the flow) from recording (a fast deterministic replay with a smooth animated cursor).

What teams render with it

• GitHub README demos — aidemo gif demos/onboarding, drop the autoplaying GIF into the readme (the GIFs on this page are exactly that).
• Landing-page hero videos — the muted-autoplay MP4 on aidemo.top is a rendered demo, poster frame and all.
• Release / what-shipped demos — narrate the new feature, then gh release upload v1.4.0 demos/whats-new/output/final-demo.mp4.
• Customer & prospect demos — personalized flows against your real app: localhost, auth walls, your own logged-in Chrome; nothing leaves the machine.

Render in CI (self-maintaining demos)

Commit a storyboard and the [aidemo GitHub Action](docs/CI.md) keeps its demo media in sync — a fresh narrated, captioned MP4 (and GIF) on every relevant change. Deterministic replay + a local voice mean no API key, no LLM tokens, about $0 (just free runner minutes). It's the loop a screen recorder can't run: your demo maintains itself.

# .github/workflows/demo.yml

• uses: actions/checkout@v4
• run: sudo apt-get update && sudo apt-get install -y ffmpeg # ubuntu ships Chrome, not ffmpeg
• uses: tandryukha/aidemo@stable with: demos: demos/* tts: local # in-process voice → no keys, no tokens gif: "true"

Full recipe, templates (auto-commit / PR-comment / cron-refresh), and the always-fresh-embeds trick: [docs/CI.md](docs/CI.md), [docs/EMBEDS.md](docs/EMBEDS.md), [docs/recipes/](docs/recipes/).

Quick start (self-contained smoke test)

A bundled fixture store (search → results → cart → checkout) that renders a finished demo with zero external dependencies:

npm install                                # Node 22.12+, system Chrome, ffmpeg on PATH

node examples/local-demo/serve.mjs # terminal 1: fixture on :8787 node bin/aidemo.mjs render examples/local-demo --headless # terminal 2 open examples/local-demo/output/final-demo.mp4 # xdg-open on Linux, start on Windows

Voice/captions need OPENAI_API_KEY in .env — or AIDEMO_TTS_PROVIDER=local (no key, offline), or OPENAI_BASE_URL at a local server. See docs/LOCAL_MODELS.md. No Playwright browser download is needed — the engine uses your system Chrome (channel: "chrome"; see Setup to use a different browser). The one Playwright download is its ~2 MB ffmpeg helper, which encodes the take: the first take installs it automatically (AIDEMO_NO_AUTO_INSTALL=1 to manage it yourself with npx playwright install ffmpeg).

The bundled fixture rendered end-to-end — narrated, captioned, auto-trimmed. Silent preview; [full version ▶](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/quickstart-demo.mp4).

CLI

Each step is independently runnable and re-runnable — regenerate voice without re-recording, recompose without re-transcribing, etc.

aidemo init <name>            # scaffold demos/<name>/ with a starter storyboard

aidemo init --from-url # …drafted from the live page's headings + real selectors aidemo import-trace trace.zip --name # …or from a Playwright trace / *.spec.ts (actions + selectors → scenes) aidemo voice # per-scene TTS → narration.mp3 + voice.json aidemo record # drive Chrome → raw video + timeline.json aidemo probe # record-only dry run (verify selectors), no key needed aidemo validate # schema-check the storyboard, no browser (non-zero exit on issues) aidemo lint # predict freezes/cuts + selector pitfalls before spending a take aidemo captions # Whisper → captions.{srt,vtt,cues.json} (--offline for no network) aidemo compose # trim + sync + zoom + cards + caption + mux → final-demo.mp4 aidemo gif # final-demo.mp4 → README-ready GIF (autoplays on GitHub) aidemo frames # evenly spaced PNGs from the video for review (--source raw) aidemo render # voice → record → captions → compose aidemo guide # print the canonical authoring guide aidemo doctor # check Node, ffmpeg, Chrome, voice endpoint

Add --headless for CI/fixtures; omit it for real sites that need your logged-in session. --profile picks the Chrome user-data dir; --fresh records on a wiped one; --storage-state / --cookie "name=value;domain=host" seed a cookie-gated site before the first action (or declare setup in the storyboard, which can also run a preflight script before every take); --capture native|obs switches to high-fide