motion-explainer
Ask Claude to explain something. Get a motion-graphics animation you can pause, step through and zoom into.
A Claude Code skill. One prompt in, one self-contained HTML player out,narrated in English or Spanish if you want.
▶ Live demos · Install · Prompts to try · Narration · Scene format
Made from one prompt. Click to play it yourself: pause, step, zoom.
One prompt in, one explainer out
Input
/motion-explainer Explain a login flow. Icon on every box, a terminal mockup for the curl call,
a latency chart, zoom into the auth service, hud theme.
Output · ▶ Watch it (9 steps, 1:16, one 120 KB HTML file) · scene source
| Step | What happens |
|---|
| 2 | A terminal types the curl call |
| 3 | The request packet passes through the API gateway (its outline fills like a progress ring) on its way to the auth service |
| 4 | The camera zooms inside the auth service: rate limit → bcrypt → sign JWT |
| 5 | The packet goes into the users database and comes back with the password hash |
| 6 | A latency chart: bcrypt takes ~250 ms of the request, on purpose |
| 7–8 | A signed token travels back; later requests only check its signature |
What Claude did in between
1. storyboarded 9 steps and checked the facts
2. wrote the scene, built it, linted it in headless Chrome (overlaps, text that doesn't fit, hidden arrows)
3. screenshotted every step and fixed what looked wrong
4. opened the player
Another one, from a plain prompt with no graphics named and no edits: how DNS resolution works, built from a real dig +trace.
Why it's different
| What it means for you |
|---|
| A player, not a video | Play, pause, step with ← →, scrub, change speed. Viewers go at their own pace. |
| Zoom into anything | Scroll or pinch to zoom, drag to pan, double-click a box to fly into it. Boxes can hold detail that only appears up close. |
| One HTML file | Engine, scene and narration inlined. No network, no CDN, strict CSP. Email it, attach it to a PR, open it offline. |
| Checks its own work | Every build is linted for overlaps, text that doesn't fit, arrows through boxes and off-canvas elements. Claude reviews a screenshot of every step before you see it. |
| Narrated, offline | Local Kokoro voices in English and Spanish, with a voice picker in the player. Nothing leaves your machine. |
Install
Needs: macOS or Linux, Google Chrome or Chromium, bash, openssl. Nothing from npm or pip.
Plugin (Claude Code keeps it updated). In Claude Code:
/plugin marketplace add 4lxn/motion-explainer
/plugin install motion-explainer@motion-explainer
Or git clone (update with git pull):
git clone https://github.com/4lxn/motion-explainer ~/.claude/skills/motion-explainer
Use one or the other; if both are installed, the plugin wins. Then ask:
/motion-explainer how TCP's three-way handshake works
Or just say "animate this architecture" or "explícamelo con una animación".
Run motion doctor (plugin installs put motion on Claude's PATH) or ~/.claude/skills/motion-explainer/bin/motion doctor (git clone). It checks Chrome, openssl and an end-to-end build, and prints the fix for anything missing.
- Chrome somewhere unusual:
export MOTION_CHROME="/path/to/chrome-or-chromium"
- Windows: run it inside WSL with Chromium installed. The built HTML plays in any browser on any OS.
- Ubuntu 24.04 CI or containers: headless Chrome needs its sandbox allowed:
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 (this repo's CI does the same).
Prompts to try
| You want | Ask |
|---|
| How a system works | "/motion-explainer how a request reaches our API: load balancer, auth, cache, database" |
| An algorithm, step by step | "animate quicksort on [7, 2, 9, 4, 1, 8]" |
| An idea that changes over time | "show why retries without jitter overload a server after an outage" |
| What went wrong | "walk through yesterday's outage as an animation, failure path first" |
| Lots of graphics | "explain a login flow: icon on every box, a terminal mockup for the curl call, a latency chart, zoom into the auth service, hud theme" (result) |
| A product or tool | "explain what Microsoft Access is and its main features, narrated in Spanish" |
| Onboarding | "explain our deploy pipeline to a new engineer, with a step for every stage" |
Graphics are used only where they carry meaning, unless you name them: icons, charts, terminal / browser / phone mockups, kinetic titles, zooms, particles, the hud theme or a glow backdrop.
Claude reads your code or docs first when the topic is your own system, and says "likely" in the narration for anything it inferred rather than checked.
Narration: English and Spanish
Each step's narration can be spoken by a local text-to-speech model and embedded in the HTML. Every step waits for its voice to finish.
| Narration language | Voices (picker in the player) | Pronunciation |
|---|
| English | Heart (af_heart) | American English |
| Spanish | Dora, Alex, Santa (ef_dora, em_alex, em_santa) | Latin American (set lang: 'es-es' for Castilian) |
Only native voices read each language: an English voice reading Spanish keeps its accent, so motion voice picks the right voices from the scene's lang (or detects the language) and refuses a mismatch.
Hear the same explainer in both languages: What is Microsoft Access? · ¿Qué es Microsoft Access?
Needs node, ffmpeg and Python 3.
APP=~/.claude/skills/motion-explainer # plugin installs: APP=$(dirname "$(dirname "$(command -v motion)")")
V=~/.cache/motion-voice; mkdir -p "$V"; python3 -m venv "$V/venv"
"$V/venv/bin/pip" install -r "$APP/tools/voice-requirements.txt"
for f in kokoro-v1.0.int8.onnx voices-v1.0.bin; do
curl -L -o "$V/$f" "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/$f"
done
Every dependency is pinned, and the model files are checked against pinned SHA-256 hashes. Then ask Claude to "add narration", or run motion voice my-topic.scene.js and build again. More in REFERENCE.md › Voice.
Examples
| Explainer | Shows | Live |
|---|
| GitHub Actions runners | architecture, packets along arrows, zooming inside a box | open |
| Binary search | an algorithm; the steps come from a real run of the code | open |
| Retries with jitter | an idea over time, live charts | open |
| From git push to production | icons, terminal and browser mockups, kinetic type, hud theme | open |
| DNS resolution | made by the skill from one prompt, unedited, with real dig +trace data | open |
| How a login works | rich visuals from one prompt: hud theme, terminal that types, icons, zoom inside a service, latency chart, packets passing through components |
Player keys
| Key | Does | Key | Does |
|---|
Space | play / pause | S | step mode: pause after each step |
← → | previous / next step | [ ] | slower / faster |
| scroll, pinch | zoom | T | light / dark |
| drag | pan | V | narration on / off |
| double-click a box | zoom into it | ? | all keys |
Add #4 to the URL to open at step 4.
Write scenes yourself
The skill drives bin/motion, and you can too:
motion new my-topic architecture # start from a template: architecture | algorithm | idea | story
motion build my-topic.scene.js # inline everything into my-topic.html, then lint it
motion shot my-topic.html # one PNG with every step (add 4 or [email protected] for one step, mid-motion)
motion open my-topic.html # chromeless 1440x900 window
motion voice my-topic.scene.js # narrate, then build again
motion doctor # check the setup
(motion is on PATH with the plugin; with git clone it's ~/.claude/skills/motion-explainer/bin/motion.)
A scene is a small JS file: declare every element, then the steps that reveal and move them.
Motion.scene({
title: 'Cache hit vs miss',
lang: 'en',
elements: [
{ id: 'app', type: 'box', x: 300, y: 450, label: 'App' },
{ id: 'cache', type: 'box', x: 800, y: 450, label: 'Cache', tone: 'accent' },
{ id: 'db', type: 'box', x: 1300, y: 450, label: 'Database', shape: 'db' },
{ id: 'a1', type: 'arrow', from: 'app', to: 'cache' },
{ id: 'a2', type: 'arrow', from: 'cache', to: 'db' },
],
steps: [
{ title: 'Ask the cache first', say: 'The app checks the cache before the database.',
do: [{ show: ['app', 'cache', 'a1'] }, { flow: 'a1', label: 'GET' }] },
{ title: 'Miss: go to the database', say: 'On a **miss**, the cache asks the database and keeps the answer.',
do: [{ show: ['db', 'a2'] }, { flow: 'a2' }, { flow: 'a2', reverse: true, label: 'row' }, { pulse: 'cache', tone: 'ok' }] },
],
});
Errors name the scene line and suggest the closest valid name:
error 'cache': unknown type 'bxo'. Did you mean 'box'?
error step 2: unknown id 'dbb'. Did you mean 'db'?
error js: Uncaught ReferenceError: lable is not defined (my-topic.scene.js:14)
Elements: boxes, circles, text, arrows, zones, notes, code panels, icons, charts, terminal, browser and window mockups, kinetic titles, particles. Actions: show, hide, set, move, flow, focus, camera, pulse, line and more. The full format is in REFERENCE.md.
FAQ
How it works
scene.js ──► motion build ──► one .html (engine + scene + voice inlined, hash-pinned CSP)
│
├─► headless Chrome lint (overlaps, fit, unknown ids, JS errors)
└─► motion shot (a PNG per step that Claude reviews)
engine/player.js compiles the scene into tweens and paints SVG. bin/motion is plain bash 3.2. tools/voice.py runs Kokoro locally.
Updating and contributing
- Update:
claude plugin update motion-explainer@motion-explainer, or git -C ~/.claude/skills/motion-explainer pull. See CHANGELOG.md.
- Test:
test/run.sh lints every example and runs the player, voice, CLI and lint tests. CI runs it on Ubuntu and macOS.
- Contribute: issues and PRs welcome; see CONTRIBUTING.md.
License
MIT. The optional voice feature downloads Kokoro weights (Apache-2.0) and uses phonemizer / espeak-ng (GPL-3.0); they are not bundled here.
