motion-explainer

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	open
What is Microsoft Access?	a product tour, narrated (English)	open
¿Qué es Microsoft Access?	the same tour, narrated in Spanish with three voices	abrir

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 4@1.5 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.