Your app demos itself.
Walkabout is a pattern (not a library) for giving any web app three connected capabilities:
- A guided voice tour — a floating guide card walks the real app page by page with AI voice narration. The spotlight scrolls to each section as the voice reaches it, auto-advance makes it hands-free, and the user can wander off mid-step (the guide politely pauses and waits). ~250 owned lines of React; no tour library.
- An ask-the-app AI guide — the same corner button hosts a question box answered by an LLM grounded in a hand-written app guide. Every question is logged: what users ask is your roadmap.
- One-command demo videos — headless recorders turn the tour (or any scripted click-path) into narrated MP4s. Change the app, re-run the script, get a fresh video. Stale demos become a choice.
Born on FieldProof (Jezweb, 2026) because the founder didn't want to give demos anymore. Now the app gives them.
Tour libraries fight your router and your styles, and none of them do the
thing that matters: voice synced to a moving spotlight. The trick that
makes Walkabout work is that nothing is hand-timed — narration is generated
through ElevenLabs' with-timestamps endpoint, so the exact second each
sentence starts is known. The spotlight moves on the audio's own clock
(ontimeupdate), demo-video actions fire at narration offsets, and
re-recording the voice regenerates every timing. Sync is correct by
construction, not by validation.
| Path | What |
|---|---|
templates/Tour.tsx |
The tour component: navigate → narrate → moving spotlight → auto-advance, pause-on-wander, keyboard, ?tour=N deep links |
templates/steps.ts |
Steps config + localStorage helpers |
templates/halo.css |
The spotlight halo (3 rules, incl. reduced-motion) |
templates/gen-tour-audio.py |
Segmented scripts → ElevenLabs with-timestamps → MP3s + generated cue timings |
templates/record-tour.mjs |
Tour → narrated MP4, fully headless (lossless CDP screencast + ffmpeg muxes the source MP3s at measured offsets) |
templates/record-demo.mjs |
Scripted feature demos: {say, do} segments — the harness types/clicks on narration cue |
templates/Assist.tsx + assist-routes.ts + assist-knowledge.ts + questions.sql |
The ask-the-app guide: widget, endpoint, app-guide content, question log schema |
skills/walkabout/SKILL.md |
A Claude Code skill that walks an AI agent through adopting the whole pattern |
docs/pattern.md |
The deep reference: design rationale and every gotcha earned in production |
.claude-plugin/ |
Plugin + marketplace manifests so this repo installs via /plugin |
The templates are real production files, not scaffolds — copy them into
your app and adapt names, styling, and the auth bootstrap. The gotchas in
docs/pattern.md are the hard-won part: the React effect-dependency trap
that replays audio on every click, the z-index war with Leaflet, why
getDisplayMedia tab-capture is the wrong way to record, and a dozen more.
- An ElevenLabs API key (
ELEVENLABS_API_KEY) - For videos: Node, Playwright,
ffmpeg/ffprobe - Seeded demo data that looks good on camera
One engine, three script lengths:
| Tier | Length | Audience |
|---|---|---|
| Quick highlights | 30–45s | socials, home page |
| Promo tour | 2–3 min | first-time users, prospects |
| Training demos | 30–60s each | users learning a feature |
Install it as a plugin (recommended) — this repo is its own marketplace:
/plugin marketplace add jezweb/walkabout
/plugin install walkabout@walkabout
Then ask Claude Code to "add a walkabout to this app" (or run
/walkabout:walkabout). The skill carries the build order, the verification
gates ("test by wandering, not by watching"), and the traps; templates/ and
docs/pattern.md ride along in the plugin.
Prefer a manual skill install? Copy the skill folder instead:
cp -R skills/walkabout ~/.claude/skills/walkabout # then restart Claude Code
MIT © Jezweb