An explanation compiler for Claude Code. Ask how something works, and get the explanation that costs you the least effort to understand. Usually that is a short answer in precise, plain prose, built from first principles. When the structure needs it, the answer becomes a diagram, an interactive page, or a narrated 3Blue1Brown-style video. Behind each artifact sits a small model of the subject, and every rendering is checked against it, both for what it leaves out and for what it says that you did not need.
 |
 |
| Self-attention (interactive): remove one part at a time (the content weights, a separate query, √d, the mask) and see what breaks. | Softmax temperature (video, 93 s): one value, T, drives every object. The voice is local, and no API keys are needed. |
Live site: interactive pages, and videos that stop for your prediction · Inspired by Andrej Karpathy's post on understanding LLM output through richer formats.
In Claude Code:
/plugin marketplace add ifrit98/Explainer
/plugin install explainer@explainer
Then ask:
/explainer:explain how does a bloom filter work
/explainer:video why the derivative of sin is cos
/explainer:verify bloom-filter
The plugin adds an explainer command that runs the toolkit through uv. Stages 1–3 need nothing else. Video also needs Cairo, Pango, and FFmpeg (brew install cairo pango pkgconf ffmpeg) and a one-time explainer setup for the local voice. Details: getting started.
The principles also shape plain chat answers: answer first, give the mechanism and why it has its form, add one case with numbers, then stop. explainer eval chat measures that. It asks six questions about phenomena (why ice floats, why TCP starts slowly, how a wing makes lift, …), answers each one under three system prompts, and has a fresh model grade them blind:
| System prompt | Score /10 | Words | Passages the reader did not need | Ranked best |
|---|---|---|---|---|
| none | 6.3 | 399 | 4.7 per answer | 0 of 6 |
| v0.5.0 principles | 7.2 | 544 | 5.0 | 1 of 6 |
| current principles | 7.8 | 292 | 1.5 | 5 of 6 |
The first run showed that the principles made answers 50% longer. The answers carried Scope sections, status tags on textbook facts, and extra cases. One rule fixed it: a chat answer is not a small artifact. Evals.
Most explanations fail by omission, not by error: a formula with no reason for its form, a guarantee never shown to break, a symbol used before anyone said what it means. Explainer separates the work into three passes, and checks each one.
flowchart LR
Q[Question] --> M["1 · Model<br/>what is true:<br/>entities, causes, numbers,<br/>claims with their evidence"]
M --> N["3 · Narrative<br/>the reader's path:<br/>question, motive, beats,<br/>every symbol introduced"]
M -.-> S("2 · Stage<br/>the simplest medium<br/>that keeps the structure")
S -.-> N
N --> P[Prose]
N --> D[Diagram]
N --> H[Interactive page]
N --> V[Video]
M -. "probe" .- PR(("fresh<br/>agent"))
N -. "cold read" .- CR(("fresh<br/>agent"))
-
Model (
model.md,model.yaml): the entities, the causal chain, every number a rendering shows, and the claims a reader must take away. A why claim needs the simplest alternative failing; a guarantee needs a case where it holds and one where it breaks. -
Stage: the lowest rung that keeps the structure. If five sentences explain it, the answer is five sentences.
Stage Use when the subject is mainly… Escalate when… 1 · Prose a procedure, a definition, an argument — 2 · Diagram topology, flow, architecture the reader must hold 3+ relationships at once 3 · Interactive a parameter, scenarios, drill-down the reader must explore states or alternatives 4 · Video a transformation over time understanding depends on seeing A become B -
Narrative (
narrative.md): the question and the result in words, a reason to care, a reason for the approach, an introduction ledger for every term, symbol, and color, and the beats in order. This is where an explainer gets its power, more than from the animation.
Every rendering is compiled from the same model and narrative, so prose, diagram, page, and video use the same terms and numbers.
The checks push in both directions. A fresh agent probes the model for omissions. A cold read follows each rendering in order, as the audience the model names, and reports both what that reader was not given and what they did not need. explainer check holds every number and term to the model, and holds each rendering to a length budget. The process scales with the stakes: an answer in chat, a quick artifact with one check, or a published explainer with the full pipeline.
 |
Softmax temperature: one model rendered as prose, diagrams, an interactive page, and a narrated video. Why exp (divide by the sum instead and owl gets −0.4), why divide by T, and entropy as average surprise. |
 |
Odd numbers make squares (proof): each odd number is an L that grows the square by one, and each L is two bigger than the last. The reference for the narrative pass: narrative, cold-read record. |
 |
Dijkstra's shortest paths (algorithm): the run in model.yaml, replayed. Why the smallest estimate settles first, why a settled estimate is final, one step at a time, and a negative edge that breaks it. Blind-test results. |
| Why a CDN makes a request faster (interactive) | Three round trips, priced by distance: predict the no-CDN time from the model, then compare no CDN, a miss, and a hit while you move the edge. Cold read. |
 |
STE-80 rewrite (video, 97 s): one manual sentence through three Simplified Technical English rules, 16 → 15 → 13 → 9 words, and what each rule changes for the reader. Cold read. |
| Self-attention (interactive) | One token, four levels. Remove one part at a time (content weights, a separate query, √d, the causal mask) and see what breaks, with every number from the model. |
| How a higher interest rate lowers inflation (interactive) | The mainstream chain and its lag, then a toggle for each assumption that changes the answer: anchored expectations, a supply shock, and two disputed views (the cost channel, the neo-Fisherian long run). Every claim is tagged established, estimate, disputed, or constructed. |
| Why the sky is blue (prose + diagram) | A phenomenon from first principles in 650 words: scattered power goes with the electron's acceleration squared, so blue scatters 5.86 times more than red; losses multiply along a sunset's 38 air masses. |
| git bisect (prose) · git objects (diagram) | The router at work: a procedure gets numbered steps; pure topology gets one diagram. Their cold reads found a remedy that could not work and a missing "because" (bisect, objects). |
All examples, with the reason for each stage: explainers/.
Every check below has caught a real problem in this repo. Each finding then became a rule for every new explanation, not only a fix to one example.
| Check | When | Catches | It found |
|---|---|---|---|
explainer probe |
before rendering | what the model omits: a formula with no why, a guarantee with no failure case, an undefined term | the first softmax model never said why it uses exp |
explainer coldread |
on the narrative before rendering, on each rendering after | read as the audience: every word, symbol, or picture met before it is introduced; things shown but never said; leaps; and excess, what this reader did not need. Findings that block the main line come first. | odd-squares used "the n-th L" without saying what n is; Dijkstra's finality argument claimed "reaching D costs at least ten", then D became eight |
explainer check |
always; CI | a number the model does not contain, a stale page, an incomplete or uncovered claim, a second name for one concept, a symbol the narrative never introduces, a rendering over its length budget, a Mermaid block that does not render (--diagrams) |
Dijkstra's narration called a value that can still drop a "distance"; the sky-blue prose went over its 650 words twice after review fixes |
explainer render · review |
every video render | text that overlaps, touches, or leaves the frame; a key claim with no pause; narration over one picture for too long; a repeated line | Dijkstra said "D is ten" while the screen showed 8; two softmax labels touched |
explainer quiz |
before publishing | what a fresh reader understood, scored against the model's quiz and claims | passed the softmax prose and failed a deliberately broken copy |
--run · explainer findings --stats |
every review | the probe, cold read, and blind test run by a fresh claude -p agent and saved; the author records what they adopted |
authors adopt 100% of blocking cold-read findings but 3% of edge findings and 9% of audit gaps, so those prompts were cut back (evals) |
explainer eval chat |
when the principles change | whether the principles make chat answers better for a technical reader, graded blind against no system prompt and the last release | the principles made answers 50% longer; with a chat rule they now score 7.8/10 at 292 words, against 6.3 at 399 with no system prompt (evals) |
Effort has two sources, and the checks push against both: what is missing and what is extra. Without the second, every review adds words. (Concepts: omission and excess.)
The blind test and the cold read measure different things. The old odd-squares video passed the blind test (a capable reviewer fills gaps from context) and failed the cold read. The authoring guide tells the whole story, including how the narrative's cold read changed the proof itself.
class Softmax(ExplainerScene):
def construct(self):
T = ValueTracker(1.0) # drives the dots, bars, and numbers
...
self.predict("When T rises to 2, does cat stay the most likely token?")
with self.voiceover(text="Now raise the temperature. <bookmark mark='hot'/> At T equal to two, "
"the logits move together."):
self.wait_until_bookmark("hot")
self.play(T.animate.set_value(2.0), run_time=3)The animation starts exactly when the voice reaches the bookmark. Local TTS engines give no word timings, so the usual fix is a second pass with Whisper. Here the Kokoro service synthesizes each sentence and each bookmark segment separately and records where each one starts, so bookmark and caption times are exact. self.predict dims the frame and asks a question; web players stop there until the viewer commits a prediction. How it works.
This project started from a post by Andrej Karpathy (October 2026). The post proposes a ladder of output formats for understanding what language models produce, each rung "even better" than the last: writing in ASD-STE100 softened to "80% of the way" (here: STE-80), diagrams, web pages ("in HTML"), and explainer videos ("a 3b1b style video explainer on X", narrated with a free local voice). Its closing point is the project's premise: as code gets cheap, it makes sense to ask for "large, custom, discardable software artifacts". Explainer turns the ladder into a workflow, and adds the checks.
Prose and narration use STE-80, a house style based on ASD-STE100. It applies about 80% of the rules and skips the dictionary check.
It is imperative that the operator ensures the hydraulic reservoir is replenished prior to commencing operation.Fill the hydraulic reservoir before you start the machine.
One idea per sentence, active voice, one term per concept, and direct causal statements ("A causes B because C"). The other 20% keeps explanatory power: a precise term of art stays (and is defined once), a cause stays in the sentence with its effect, and nothing the reader already knows is defined. Rules.
Plugin · plugin/ |
Skills explain, video, verify; the principles; playbooks for writing, diagrams, HTML, and video. |
Toolkit · explainer_kit/ |
The explainer CLI, the model check, the probe and cold-read prompts, ExplainerScene (voice sync, timeline, layout and pace checks, predict pauses), reusable components, word morphs, the Stage 3 web toolkit, and templates. |
Docs · docs/ |
Getting started, concepts, authoring guide, model reference, video pipeline, web toolkit, CLI, troubleshooting. |
- Claude Code for the agent workflow (Stages 1–4).
- For video: Python 3.11–3.13 via
uv, Cairo, Pango, pkg-config, FFmpeg. Optional: SoX; LaTeX forMathTex(a user-level TinyTeX works; see troubleshooting). explainer check --diagramsneeds Node (it runs the pinned Mermaid CLI withnpx).- Tested on macOS (Apple silicon). CI runs the tests, the checks, and a draft render on Ubuntu.
- showtime: a broader local video studio plugin for coding agents (HTML motion graphics, footage editing, music). It works alongside this repo; see video playbook §7.
- Manim Community · manim-voiceover · Kokoro-82M
What is done, what is next, and what the reviews found: ROADMAP.md. Release notes: CHANGELOG.md and releases. Contributing: CONTRIBUTING.md.
MIT. Third-party components keep their own licenses: Manim and manim-voiceover (MIT), Kokoro-82M weights (Apache-2.0), kokoro-onnx (MIT), FFmpeg (LGPL/GPL). The Kokoro model files are downloaded by explainer setup and are not part of this repository.