agentleFS
tandryukhatandryukha/aidemo/AGENTS.md

aidemo

AGENTS.md32 starsChanged 7 days agoMITView on GitHub

You are working on the demo engine, not just using it. The README explains what aidemo is and why it's built this way; CONTRIBUTING.md covers process (DCO sign-off, PR expectations, CI policy). If this file contradicts them, they win. Mental model: storyboard.json (script + per-scene voice/music plan + browser action-spec) → voice (OpenAI TTS) → record (deterministic replay in real Chrome, injected cursor, timeline) → captions (Whisper word timing) → compose (ffmpeg: trim idle, sync to narration, zoom, cards, mux)…

  • Reads credentials
  • Installs packages
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository8 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never use unbounded apad: it never EOFs and -t does not stop it (runaway encode until killed).

    line 132
  2. Very specific:

    Commit style: short imperative subject (fix: compose hangs on unbounded apad).

    line 156
  3. Very specific:

    If you add code that reads a new file relative to ENGINE_ROOT/REPO_ROOT (e.g.

    line 173

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Working on aidemo — guide for coding agents

You are working on the demo engine, not just using it. The README explains what aidemo is and why it's built this way; CONTRIBUTING.md covers process (DCO sign-off, PR expectations, CI policy). If this file contradicts them, they win.

Mental model: storyboard.json (script + per-scene voice/music plan + browser action-spec) → voice (OpenAI TTS) → record (deterministic replay in real Chrome, injected cursor, timeline) → captions (Whisper word timing) → compose (ffmpeg: trim idle, sync to narration, zoom, cards, mux) → output/final-demo.mp4.

Commands

TaskCommand
Installnpm install — Node 22.12+, system Chrome, ffmpeg+ffprobe on PATH (no Playwright browser download; Playwright's ~2 MB take-recording ffmpeg helper installs itself on the first take — AIDEMO_NO_AUTO_INSTALL=1 opts out; doctor reports it)
Type checknpm run typecheck
Unit tests (no Chrome/ffmpeg; also CI)npm test — npm run test:blank-open needs Chrome + ffmpeg
Lead-in vs real frames (needs Chrome + ffmpeg)npm run test:lead-in
Fixture servernode examples/local-demo/serve.mjs (port 8787)
E2E smoke testnode bin/aidemo.mjs render examples/local-demo --headless
Dry-run actions onlynode bin/aidemo.mjs probe examples/local-demo --headless
Resume a takenode bin/aidemo.mjs record <dir> --from-scene <id> (also render, MCP fromScene) — reuses the previous take's earlier scenes (hash-guarded), replays their actions fast, records from <id>
Draft from a Playwright trace/testnode bin/aidemo.mjs import-trace <trace.zip|spec.ts> --name <demo> — actions + selectors → scenes, no LLM (MCP import_trace)
Draft from a URLnode bin/aidemo.mjs init <name> --from-url <url> — inspect first, headings → scenes, unique selectors → beats (MCP init_demo {fromUrl})
Selector discoverynode bin/aidemo.mjs inspect <url> --dir <demo> — unique selectors per visible element (MCP inspect job); the same scan writes logs/drift-*.json suggestions when a take's selector matches nothing
Validate a storyboard (no browser)node bin/aidemo.mjs validate <dir> (--file <path>, --json; non-zero exit on issues)
Lint / pacing forecast (no browser)node bin/aidemo.mjs lint <dir> (--lang, --json, --strict) — also auto-runs in probe/record/render; measured counterpart is output/report.json from compose
Frames for reviewnode bin/aidemo.mjs frames <dir> --every 3 (--source raw for the take)
Walkthrough bundlenode bin/aidemo.mjs walkthrough <dir> — output/walkthrough/ (index.html, guide.md, frames, captions) from the final video (also auto in render with output.walkthrough)
One pipeline stagenode bin/aidemo.mjs voice|record|captions|compose <dir>
Screenshot stillsnode bin/aidemo.mjs stills <dir> — extract named PNGs from an existing take (also auto-runs in render when the storyboard has still markers)
Golden regression checknode bin/aidemo.mjs probe <dir> --update-golden (write baseline) / --golden (CI guard, non-zero exit on drift)
Multi-language matrixnode bin/aidemo.mjs render <dir> --langs de,fr — one take → N locales (also --lang on voice/captions/compose)
Personalized variantsnode bin/aidemo.mjs render <dir> --variants variants.json (or --param k=v)
Always-fresh embed snippetsnode bin/aidemo.mjs embed <dir> — stable raw-GitHub URLs for READMEs/PRs
CI render (consumers)uses: tandryukha/aidemo@stable (composite action, action.yml) — see docs/CI.md
MCP server (agent interface)node bin/aidemo.mjs mcp — stdio; smoke test: npm run mcp-smoke (needs Chrome)
Print authoring guidenode bin/aidemo.mjs guide (--topic core|schema|attention|polish|…, --list)
Environment checknode bin/aidemo.mjs doctor

render, voice, and captions need OPENAI_API_KEY in .env (or OPENAI_BASE_URL pointing at a local OpenAI-compatible server, or AIDEMO_TTS_PROVIDER=local + npm install kokoro-js for in-process TTS with offline captions — no key at all); probe, record, and compose re-runs don't. Every engine change should keep the fixture rendering end-to-end (that's the smoke test CI can't run for you — it needs Chrome, ffmpeg, and a TTS/STT endpoint or the local provider).

Layout

bin/aidemo.mjs        CLI entry (launches tsx → src/cli.ts)
src/types.ts          storyboard schema (zod) — the contract everything shares
src/                  pipeline stages: voice, recorder/player/cursor (record),
                      captions/caption-render, compose/zoom/cards/music/ffmpeg
                      (compose writes output/report.json), attention (highlight/
                      spotlight/callout/keystroke/click-ring PNGs + redact blur
                      filter), inspect (page scan → unique selectors; drift
                      ranking for failed selectors), anchors ({{@word}} markers → piecewise
                      retime), frame (produced-look canvas PNG), guide
                      (topic slices of AUTHORING.md), import-trace (Playwright
                      trace.zip / spec → draft storyboard), lint (browser-free
                      pacing forecast + pitfalls), recorder (take lifecycle,
                      resume via per-scene hashes + raw.keep-* footage),
                      stills (screenshot mode), frames (review PNGs),
                      walkthrough (HTML/Markdown bundle from the final video), setup
                      (cookie/storageState seeding + preflight hook),
                      i18n (multi-language),
                      params/variants (personalized renders), golden (probe
                      regression), embed (always-fresh URLs), capture
                      (native/OBS), starter (init templates), distribute
                      (skill install/update/feedback, doctor, repo-init)
src/mcp/              the MCP server (server = tools/resources, jobs = job model)
docs/AUTHORING.md     canonical authoring guide — served by the engine
                      (MCP get_authoring_guide / `aidemo guide`)
action.yml            composite GitHub Action (uses: tandryukha/aidemo@stable)
docs/CI.md            CI render recipe; docs/EMBEDS.md always-fresh embeds
docs/plans/           deferred designs (public-mcp.md) + roadmap-leftovers-2026-09.md
                      (open items after v0.14.0); docs/recipes/ how-tos
examples/workflows/   copy-paste consumer CI workflow templates
.claude/skills/       record-demo (thin adapter → AUTHORING.md) + dev skills
.claude-plugin/       marketplace.json — Claude Code plugin marketplace catalog
plugins/record-demo/  published plugin (bundles record-demo skill + aidemo MCP)
blog/                 SEO blog source: article JSON + blog.config.json →
                      blog-engine-baked, committed docs/blog/ (served at
                      aidemo.top/blog); writer contract via `blog-engine guide
                      AUTHORING`, map in data/topics.json
examples/local-demo/  self-contained fixture + storyboard — the smoke test
.github/local-voice/ kokoro-js for demo-render, pinned by its lockfile (sharp
                      overridden); .github/node-floor/ the Node 22.12 floor's
                      @types/node for CI's second typecheck
test/mcp-smoke.mjs    MCP-surface smoke test (local, needs Chrome)
demos/                untracked local working area
docs/                 public docs + README media (docs/internal/ is gitignored, private)

Invariants — don't break these

  • No LLM in the capture loop. The recording is a deterministic replay of a fixed action-spec. Agents author storyboards; they never steer a live take.
  • Schema ↔ authoring-doc sync. src/types.ts is the storyboard schema; docs/AUTHORING.md is the canonical authoring guide that documents it (served to agents via the MCP get_authoring_guide tool and aidemo guide; .claude/skills/record-demo/SKILL.md is a thin adapter with no schema content). Change the schema → update docs/AUTHORING.md in the same commit.
  • Published plugin skill stays in sync. The Claude Code plugin ships a copy of the record-demo skill at plugins/record-demo/skills/record-demo/SKILL.md. It must be byte-identical to .claude/skills/record-demo/SKILL.md. Edit the canonical one, then npm run sync:plugin-skill; npm run check:plugin-skill fails on drift. On a version bump, also bump version in plugins/record-demo/.claude-plugin/plugin.json.
  • ffmpeg portability. Many ffmpeg builds lack subtitles/drawtext. Captions and cards are headless-Chrome-rasterized PNGs overlaid with time-gated enable. Don't add filters beyond that baseline.
  • Storyboards are backward compatible. Cinematic and content features (zoom, scroll easing, ducking, cards, scene transition crossfades, output sizing/letterbox, still markers, params/placeholders, per-scene narrations) are opt-in; existing storyboards must render unchanged, and a run with no new flag must be byte-for-byte the old behavior.
  • Polish is compose-time, not record-time. A bad zoom must stay a recompose, never a re-record.

ffmpeg gotchas (learned the hard way)

  • Stream-copy concat of -loop 1 PNG→x264 card segments carries leading negative pts and silently kills overlay captions — the final card assembly must re-encode (concatSegments(..., reencode: true)); scene-only concat can stay stream-copy.
  • Never use unbounded apad: it never EOFs and -t does not stop it (runaway encode until killed). Always apad=whole_dur=<sec>. Same class: -stream_loop -1 through atrim never EOFs — loop a computed finite count.
  • zoompan: use on/FPS as the time base (input must be CFR), single-quote every expression (they contain commas), and pre-upscale 2× below ~1600 px width or integer-pixel crops shimmer.
  • The final mux writes -movflags +faststart (moov first, web-playable), so compare renders by stream, not by file hash: ffmpeg -i out.mp4 -map 0:v -c copy -f md5 - (and -map 0:a) must match the pre-change render for an unchanged storyboard; the container bytes legitimately differ.
  • A built-in take's length says nothing about its lead-in: the file runs well past the last scene. Playwright stamps a closing copy of the last frame at "now" (at least 1 s after it) and ffmpeg holds it for as long as the gap before it, so a page idle for 4.5 s at the end stays on screen ~9 s in the file, while context.close() takes only ~0.2 s. builtinLeadInMs uses the recorder's creation_time stamp; npm run test:lead-in measures scenes against their first frames (#94).
  • Debugging compose: AIDEMO_KEEP_TMP=1 preserves .compose-tmp/ intermediates. Logs land in <demo>/logs/<command>.log; a failed take also leaves logs/fail-*.png/json.

Repo conventions

  • demos/ is untracked scratch and docs/internal/ is gitignored — never link to either from tracked files.
  • Commit style: short imperative subject (fix: compose hangs on unbounded apad); every commit signed off (git commit -s — DCO, required to merge).
  • CI is typecheck (latest @types/node, then the Node 22.12 floor's types) + gitleaks + unit tests (npm test, Node 22, 24 and 26) + an MCP handshake in the Docker image (built from the checkout) + dependency review. The workflows' own npm installs and the Dockerfile are npm ci from a lockfile (OpenSSF Scorecard Pinned-Dependencies); only the Action's consumer mode installs by ref, by design. PRs must not add install scripts, new network endpoints, or unpinned GitHub Actions.
  • Canonical repo: github.com/tandryukha/aidemo. Consumers run the engine via npx -y github:tandryukha/aidemo#stable (git ref, the primary channel) or npx -y @tandryukha/aidemo (npm, additive — published from release.yml when repo var NPM_PUBLISH=true, via OIDC trusted publishing + provenance); server.json is the MCP-registry manifest. See RELEASING.md for how the stable tag moves and the one-time npm setup.
  • npm files allowlist tracks runtime reads. package.json files ships only bin/, src/, docs/AUTHORING.md, .claude/skills/record-demo/SKILL.md. If you add code that reads a new file relative to ENGINE_ROOT/REPO_ROOT (e.g. another served doc or template), add it to files too — else it works from the git checkout but the npm package silently breaks. Verify with npm pack --dry-run (and an install-from-tarball aidemo guide smoke).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.