Generates narrated and captioned MP4 product demos from a JSON storyboard using a deterministic Chrome replay engine.
Also known as tandryukha/aidemo, @tandryukha/aidemo
- Stars
- 33
- Tools
- 24
- Downloads, 30 days
- —
- Latest version
- 0.20.6
- Last commit
- Nov 11, 2026
- License
- MIT
What is aidemo MCP?
aidemo generates narrated and captioned MP4 product demos from a JSON storyboard using a deterministic Chrome replay engine. It exposes 24 tools, such as get_authoring_guide, get_storyboard_schema, validate_storyboard.
Summary generated from the project's README
About aidemo MCP server
Developers and product teams can generate narrated, captioned MP4 product demos by simply describing a workflow to an AI agent. By providing a single sentence to an MCP-capable client like Claude Code, Codex CLI, or Gemini CLI, the agent authors a storyboard.json file that drives a deterministic Chrome replay engine. This engine records a smooth, human-like browser session featuring animated cursors, auto-zoom, and synchronized voiceovers.
The system is designed to be highly cost-effective and private. It can run fully offline using a local TTS provider, which eliminates the need for API keys and keeps costs at nearly zero. Because the replay is deterministic, teams can integrate it into CI workflows using the aidemo GitHub Action to automatically re-render fresh demos whenever the product code changes. It also supports recording native mobile apps via iOS Simulators or Android emulators using Maestro flows to create store-ready media for the App Store and Google Play.
What you can do with it
- 1Automated product walkthroughsAsk your coding agent to record a specific user flow to get a polished video with voiceover and captions.
- 2Self-maintaining documentationKeep your GitHub README demos up to date by re-rendering them automatically in your CI pipeline when the UI changes.
Written from the project's README. Every use case is checked against a quote from it.
How to install aidemo MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall aidemo MCP in Claude Code
$ claude mcp add aidemo -- npx -y @tandryukha/aidemo mcpInstall aidemo MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"aidemo": {
"command": "npx",
"args": [
"-y",
"@tandryukha/aidemo",
"mcp"
]
}
}
}Install aidemo MCP in VS Code
.vscode/mcp.json
{
"servers": {
"aidemo": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@tandryukha/aidemo",
"mcp"
]
}
}
}Install aidemo MCP in VS Code CLI
$ code --add-mcp '{"name":"aidemo","type":"stdio","command":"npx","args":["-y","@tandryukha/aidemo","mcp"]}'Install aidemo MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"aidemo": {
"command": "npx",
"args": [
"-y",
"@tandryukha/aidemo",
"mcp"
]
}
}
}Install aidemo MCP in Codex
$ codex mcp add aidemo -- npx -y @tandryukha/aidemo mcpInstall aidemo MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.aidemo] command = "npx" args = ["-y", "@tandryukha/aidemo", "mcp"]
Install aidemo MCP in Gemini CLI
$ gemini mcp add -s user aidemo npx -- -y @tandryukha/aidemo mcpInstall aidemo MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"aidemo": {
"command": "npx",
"args": [
"-y",
"@tandryukha/aidemo",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @tandryukha/aidemo 0.20.6 in an isolated container with no network and no keys. It answered and listed 24 tools.
aidemo MCP tools 24
Read from the server with tools/listget_authoring_guideRead-onlyThe canonical guide to authoring demos: storyboard schema, action vocabulary, demo-director principles, ChatGPT-app recording facts. Call this FIRST before authoring or editing a storyboard. Pass `topic` (core | schema | polish | attention | chatgpt-apps | stills | variants | captions | debug | troubleshooting | ci, or any H2 heading prefix) for one slice instead of the whole ~1000-line guide; start with `core`, then fetch `attention`/`polish`/`chatgpt-apps` as needed.
get_storyboard_schemaRead-onlyJSON Schema for storyboard.json, generated from the engine's own zod schema — the exact contract the engine validates against.
validate_storyboardRead-onlyValidate a storyboard against the engine schema without running anything. Pass exactly one of: dir (uses generated/storyboard.json), path (a storyboard file), or json (storyboard JSON as a string). relaxed makes narration optional (probe semantics).
lint_storyboardRead-onlyBrowser-free preflight over a storyboard: a per-scene pacing forecast (which scenes compose will mostly freeze-hold or cut because the narration and the recorded action don't match), selector/wait pitfalls (type+Enter with no wait, :text-is on nested labels, focus without a zoom block, anchored waitForChange regexes), and no-op keys. Run it after every storyboard edit, before probe/render. Pass exactly one of dir / path / json. lang lints a narrations[lang] translation at that language's speaking rate.
init_demoCreate demos/<name>/ with a starter brief + storyboard. dir is the repo to scaffold into (absolute path recommended; default: server cwd). With fromUrl the page is inspected first (no LLM): its headings become scenes and its unique selectors become the beats + a `_candidates` list — you then write the narration and turn the candidate hover into the real click.
doctorRead-onlyCheck prereqs: node, ffmpeg, Chrome (or the AIDEMO_CHROME_CHANNEL / AIDEMO_CHROME_EXECUTABLE browser in use), TTS/STT endpoint (flags LLM-only servers like Ollama), API key, playwright + its ffmpeg helper (records the take; installed on the first take unless AIDEMO_NO_AUTO_INSTALL=1), installed skill.
embedRead-onlyReady-to-paste embed snippets (markdown GIF, markdown still, HTML <video>) for a demo, using stable raw.githubusercontent URLs on the 'demo-media' branch. Pure string generation — no network, no render. Owner/repo come from the repo's origin remote; the demo name from the directory basename. Pair with the demo-publish workflow so CI keeps the URLs fresh. See docs/EMBEDS.md.
feedbackFile a bug, surprise, or workaround you hit this session as a GitHub issue on the aidemo engine repo (github.com/tandryukha/aidemo) — the in-band equivalent of `aidemo feedback` on the CLI. Environment (engine version, OS, node, ffmpeg) and a recent-log tail from `dir` are auto-attached, same as the CLI. Uses `gh issue create` when available; falls back to a local docs/feedback-*.md plus a prefilled github.com New Issue URL when gh is missing or offline — no other network call. Call this whenever something felt broken, surprising, or needed a workaround; skip it if the session was clean. Set dryRun to preview the assembled title/body without filing anything.
job_statusRead-onlyStatus, stage, per-scene progress (scenesTotal/scenesDone/currentScene — populated for probe/record/render/voice/captions/compose), log tail, and final result or error (with failure-artifact paths and, on a genuine failure, a feedbackHint pointing at the feedback tool) of a pipeline job.
job_listRead-onlyAll jobs this server session, newest last.
job_cancelBest-effort cancel (checked between actions/scenes/stages). A mid-record cancel salvages the partial timeline + footage. The job settles asynchronously — poll job_status for the final state.
probeRecord-only dry run to verify selectors/timing (narration optional). With updateGolden, writes golden/probe.json (the regression baseline); with golden, deep-compares against it and returns match + field-level diffs. Returns a jobId immediately — poll job_status. Rejects if another job is running.
Show all 24 toolsShow fewer tools
import_traceTurn a Playwright trace.zip (context.tracing / `--trace on`) or a *.spec.ts test file into demos/<name>/ with a draft storyboard: the run's own actions and selectors become scenes (cut at navigations and async payoffs), narration is left as placeholders, and `_notes` lists what was approximated. No LLM, no browser. Then write the narration and probe.
recordDrive the storyboard in Chrome and record raw video + timeline.json. Returns a jobId immediately — poll job_status. Rejects if another job is running.
renderFull pipeline: voice → record → captions → compose (the CLI `render`). Returns a jobId immediately — poll job_status. Rejects if another job is running.
voiceGenerate per-scene TTS narration (skips unchanged scenes). Returns a jobId immediately — poll job_status. Rejects if another job is running.
captionsTranscribe narration.mp3 to captions with word timing. Returns a jobId immediately — poll job_status. Rejects if another job is running.
composeTrim, sync, mux and caption into output/final-demo.mp4 (+ final-demo.srt/.vtt timed to it). Returns a jobId immediately — poll job_status. Rejects if another job is running.
qaPost-render checks on the FINISHED MP4 — blank opening, blank poster, master loudness, music-bed level, per-scene hold shares + compose warnings, caption readability, frame/chapter hygiene. Run it after compose/render: it sees what a viewer sees, which neither lint (pre-take) nor report.json (structural) can. Returns a jobId immediately — poll job_status. Rejects if another job is running.
gifConvert output/final-demo.mp4 to a README-ready GIF. Returns a jobId immediately — poll job_status. Rejects if another job is running.
stillsExtract named stills (screenshot mode) from the recorded take into output/stills/ — one PNG per `still` marker, pulled from the CLEAN take (no captions/zoom). Needs only a recorded timeline (no key). Returns a jobId immediately — poll job_status. Rejects if another job is running.
framesDump evenly spaced PNG frames from the final video (or the raw take) into output/frames/ for review — look at them instead of hand-running `ffmpeg -ss`. Needs only the video (no key). Returns a jobId immediately — poll job_status. Rejects if another job is running.
walkthroughExport output/walkthrough/ from the final video: index.html (one card per scene — payoff frame, title, narration, jump-to-time; ← → keyboard nav), guide.md (README/SOP-ready), per-scene PNGs, SRT/VTT and a JSON manifest. Needs only the rendered video + report.json (no key, no browser). Returns a jobId immediately — poll job_status. Rejects if another job is running.
inspectOpen a URL in the recording profile (logged-in state included) and list every visible interactive element with UNIQUE selectors ranked data-testid → id → aria-label → role/text → name/placeholder → class → path, plus headings and iframes. Use it BEFORE writing targets — no selector guessing, no wasted probe. Writes logs/inspect-<n>.json and a screenshot in the demo dir. Returns a jobId immediately — poll job_status. Rejects if another job is running.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubaidemo — your coding agent makes the demo video
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 ▶.
Three ways to use it
- From your coding agent — the fastest path. In Claude Code:
/plugin marketplace add tandryukha/aidemothen/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. - Locally, free & offline —
AIDEMO_TTS_PROVIDER=local aidemo render <dir> --headless. An in-process voice model + script-timed captions mean no API key, ~$0, fully offline. See docs/LOCAL_MODELS.md. - In CI, self-maintaining — drop
uses: tandryukha/aidemo@stableinto 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.
- App Store & Google Play media — see Native apps & store media.
Native apps & store media
For a native iOS or Android app, aidemo records the iOS Simulator
(simctl recordVideo) or the Android emulator (adb screenrecord) while your
own Maestro flows drive it, then edits the clips into store-ready media:
- App Store App Preview (886×1920, 15–30 s, 30 fps H.264 + stereo AAC, poster frame + its ASC timecode) and Google Play promo (1080×1920 or 1920×1080, YouTube-ready) — validated against the store spec; a file that would be rejected fails the run.
- Made for muted autoplay: burned-in captions rendered from text (a new
language is a text swap:
--lang ru), speed ramps on labelled dead time (typing, waiting), no still frame over ~0.7 s unless you mark it a hold, an end card with icon, name and one line. No voiceover needed. - Screenshot sets: iOS 6.9" (1320×2868), Play phone (1080×1920), Play feature graphic (1024×500) — headline + zoomed device frame that bleeds off the edge so UI text is readable at search-thumbnail size; brand fonts and colours.
aidemo store-check demos/store # generated/store.json: scenes → Maestro flows, captions, shots
aidemo native-record demos/store # one clip per scene on the booted simulator/emulator (--boot to start one)
aidemo store-video demos/store # → output/store/app-store-preview.mp4 (+ poster, report)
aidemo store-screenshots demos/store # → output/store/screenshots/ios-6.9/01-….png
aidemo store-validate some.mp4 --preset app-store-preview # check any file
Recipe: docs/recipes/app-store-preview.md ·
reference: aidemo guide --topic store.
Render in CI (self-maintaining demos)
Commit a storyboard and the aidemo GitHub Action 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/EMBEDS.md, 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 ▶.
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 <name> --from-url <url> # …drafted from the live page's headings + real selectors
aidemo import-trace trace.zip --name <name> # …or from a Playwright trace / *.spec.ts (actions + selectors → scenes)
aidemo voice <dir> # per-scene TTS → narration.mp3 + voice.json
aidemo record <dir> # drive Chrome → raw video + timeline.json
aidemo probe <dir> # record-only dry run (verify selectors), no key needed
aidemo validate <dir> # schema-check the storyboard, no browser (non-zero exit on issues)
aidemo lint <dir> # predict freezes/cuts + selector pitfalls before spending a take
aidemo captions <dir> # Whisper → captions.{srt,vtt,cues.json} (--offline for no network)
aidemo compose <dir> # trim + sync + zoom + cards + caption + mux → final-demo.mp4
aidemo gif <dir> # final-demo.mp4 → README-ready GIF (autoplays on GitHub)
aidemo frames <dir> # evenly spaced PNGs from the video for review (--source raw)
aidemo render <dir> # voice → record → captions → compose
aidemo native-record <dir> # iOS Simulator / Android emulator take, one clip per scene (Maestro)
aidemo store-video <dir> # → App Store App Preview / Play promo, spec-validated
aidemo store-screenshots <dir> # → store screenshot sets + Play feature graphic
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 <dir> picks the Chrome user-data dir; --fresh
records on a wiped one; --storage-state <file> / --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-fidelity screen capture. voice/render
skip TTS for unchanged scenes, and record salvages a failed take (keeps
the footage + drops a screenshot/frame-dump in logs/).
Agent interface (MCP)
aidemo mcp runs a stdio MCP server (no network listener) exposing the engine
to any MCP client. The Claude Code plugin bundles it; aidemo repo-init registers
it agent-neutrally (.mcp.json for Claude Code, .gemini/settings.json for
Gemini; codex mcp add aidemo -- npx -y github:tandryukha/aidemo#stable mcp for
Codex).
- Authoring tools —
get_authoring_guideserves docs/AUTHORING.md version-matched from the engine (can't go stale);get_storyboard_schema,validate_storyboard,init_demo,doctor. - Pipeline tools run as jobs —
probe/record/render/voice/captions/compose/gif(andnative_record/store_video/store_screenshots) return ajobIdimmediately;job_statusreports stage, per-scene progress, and (on failure) the screenshot/frame-dump paths. .envworks like the CLI — the server loads its cwd's and the engine's.envat startup, and since MCP clients often start it outside your repo, each tool given a demo dir also applies that repo's.env(nearest one walking up from the demo dir to the repo root).doctor {dir}shows the result.
Why it's built this way
- Deterministic replay, not an LLM in the loop. The recording runs a fixed action-spec at full speed, so the video is smooth. The agent only authors the storyboard (and confirms selectors once), never during capture.
- Declarative action-spec + fixed player (not generated
spec.ts). Safer, editable, and it emits a timeline for free — compose fits each scene's video to its narration by trimming/speeding only the idle parts, freeze-holding a static page for any remainder instead of ugly slow-motion. - Captions via overlaid PNGs, not libass. Many ffmpeg builds lack
subtitles/drawtext; aidemo rasterizes each caption with headless Chrome and overlays it with time-gatedenable— works on any ffmpeg withoverlay. - Cinematic polish is compose-time, not record-time — a bad zoom is a recompose, never a re-record. See docs/POLISH.md.
Deeper docs
- docs/AUTHORING.md — the canonical storyboard schema, action vocabulary, and demo-director principles (served by the engine).
- docs/LOCAL_MODELS.md — no-key rendering: in-process Kokoro voice, local speech servers (speaches), ElevenLabs, offline captions.
- docs/POLISH.md — auto-zoom, scroll easing, music ducking, intro/outro cards, motion blur, cursor control, native/OBS high-fidelity capture.
- docs/CHATGPT_APPS.md — recording ChatGPT Apps SDK
widgets (dedicated profile, nested iframes,
waitForWidget). - docs/CI.md · docs/EMBEDS.md · docs/recipes/ — CI rendering, always-fresh embeds, agent-in-CI recipes.
Setup
Prereqs: Node 22.12+, Google Chrome, ffmpeg + ffprobe on PATH. The
first take also fetches Playwright's ~2 MB ffmpeg helper, which encodes the
recording (once per Playwright version; AIDEMO_NO_AUTO_INSTALL=1 opts out).
Developed and tested on macOS; Linux works for the default (Playwright) capture
and --capture obs. Run aidemo doctor to check your setup.
npm install
cp .env.example .env # add OPENAI_API_KEY, or use AIDEMO_TTS_PROVIDER=local (no key)
Choosing the browser. Every launch (recording, inspect, caption/card
rasterizing) uses system Google Chrome by default. Two env vars (shell or
.env) override that, highest precedence first:
AIDEMO_CHROME_EXECUTABLE=/path/to/chrome— an explicit Chromium-based binary.AIDEMO_CHROME_CHANNEL=<channel>— a Playwright channel:chrome(default),chrome-beta,chrome-dev,chrome-canary,msedge,msedge-beta,msedge-dev,msedge-canary, orchromium.chromium(Chrome for Testing) is the fix when an enterprise-managed Chrome closes automated sessions after a few seconds ("Target page, context or browser has been closed"); it needs a one-timenpx playwright install chromium.
aidemo doctor reports which browser will be used and whether it was found.
aidemo login opens the same browser, so the profile you log into matches the
one you record with.
Project layout (per demo)
demos/<name>/ ← your working area (untracked; scaffold with `aidemo init`)
input/ brief.md
generated/ storyboard.json timeline.json captions.{srt,vtt,cues.json}
recordings/ raw.webm (or raw.mp4 for native/OBS capture)
audio/ scene-*.mp3 narration.mp3 voice.json
output/ final-demo.mp4 final-demo.{srt,vtt} (captions timed to the video)
logs/ <command>.log fail-<scene>-<n>.{png,json} (on a failed action)
Security & trust
- No telemetry, no analytics, no install-time scripts (
package.jsonhas nopostinstall/preinstall). - Network is user-initiated only:
api.openai.com(onlyvoice/captions, your key — or a local server viaOPENAI_BASE_URL),api.elevenlabs.io(opt-in),huggingface.co(download-only, once, forAIDEMO_TTS_PROVIDER=local),cdn.playwright.dev(download-only, once per Playwright version: the ~2 MB ffmpeg helper that encodes the take; off withAIDEMO_NO_AUTO_INSTALL=1), andgithub.com(your owngh, foraidemo feedback). Recording/composing are otherwise fully local. The MCP server is stdio-only — no listener. - Small, auditable surface: ~50 source files, 7 runtime deps (11 packages
installed in all), MIT. Pin an immutable ref if you're wary of the moving
#stabletag:npx -y github:tandryukha/aidemo#v0.20.1(any released tag). - Full detail: docs/LOCAL_MODELS.md · report vulnerabilities privately per SECURITY.md.
Roadmap
- Comments on the video (pause & comment) and in-place transcript editing:
captions map to scenes, so editing a line marks that scene dirty and
aidemo voice --scene <id>+composeregenerates only the delta. - Web UI, project history, brand kits, changelog integrations.
- Hosted public MCP (see docs/plans/public-mcp.md).
Shipped: the GitHub Action (CI re-render), cinematic polish (auto-zoom, scroll easing, music ducking, intro/outro cards, motion blur, post-hoc cursor control), native/OBS capture, iOS Simulator / Android emulator capture with App Store / Google Play exports, the agent-neutral MCP server + authoring guide, ElevenLabs and in-process local voice providers, and the Claude Code plugin.
Contributing
Issues and PRs welcome — see CONTRIBUTING.md for dev setup, the
smoke test, and the DCO sign-off requirement. Recording-session feedback has a fast
path: aidemo feedback demos/<name> pre-fills a structured issue. Blocked in the
meantime? aidemo guide --topic troubleshooting covers the local workarounds
(per-stage re-runs, pinning a release, running a patched checkout).
License
MIT © Andrii Taran
aidemo MCP questions
How do I add aidemo MCP to Claude Code?
Run claude mcp add aidemo -- npx -y @tandryukha/aidemo mcp in your terminal. Add --scope user to make it available in every project.
How do I add aidemo MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does aidemo MCP provide?
It exposes 24 tools, including get_authoring_guide, get_storyboard_schema, validate_storyboard, lint_storyboard, init_demo.
Does it require an API key for voiceover?
No, you can use a local TTS provider for fully offline, zero-cost narration.
Can it be used in CI/CD pipelines?
Yes, it can be integrated into GitHub Actions to automatically re-render demos when your product changes.
Does it work with local or authenticated applications?
Yes, it can record against localhost and applications behind authentication walls using your own Chrome instance.

