showntell: ask your coding agent to explain, start watching in a second

Why I built it

When I ask a coding agent to explain something (a diff, an architecture, a concept), I get a wall of text. A short narrated walkthrough that points at the code while it talks is often faster to take in. Agents can already produce that kind of material. What was missing was a way to get it without waiting and without a cloud service.

Hosted tools that turn an agent's output into a narrated explainer do exist. They need an account, send the narration to a cloud text-to-speech API, and keep the result on their servers. I wanted:

• Speed. A link I can open and start watching within a second or two, while the agent is still writing the rest. This is the point of the whole thing.
• Local voice. Narration generated on my own machine. No API keys, no paid or unreliable APIs.
• Real code. Code slides read from disk and git, with real line numbers, not code the model retyped from memory.

How it works

1. Start. The agent calls start_walkthrough with a title slide and one or two spoken sentences. As soon as that audio exists, showntell returns a link, and the agent passes it to you.
2. Add slides. The agent sends one to three slides per call. Each is voiced in the background while you watch, and the open page picks up new slides over server-sent events.
3. Check. finish_walkthrough draws every slide and reports render and layout problems, which the agent fixes with revise_slide.
4. Export (optional). export_walkthrough saves a single offline HTML file, a static folder with captions, or a 1080p MP4.

Walkthroughs are written in Markdown: headings start slides, blocks are what you see, paragraphs are what you hear. Kokoro reports word timings, so the pointer and highlights move with the narration.

Details

Area	What you get
Voice	Kokoro-82M on your machine: MLX on Apple silicon, ONNX elsewhere. Offline after a one-time download. No telemetry.
Visuals	About 15 kinds: code, diffs, Mermaid, SVG, draw.io, maths, charts, terminal sessions
Time to first playable link	Typically under a second after the opening; 0.7–2 s in tests with Sonnet
MP4 export	A 4.4-minute walkthrough renders in 16–20 s on an M-series Mac
Model cost	About $0.09–0.24 per walkthrough on Sonnet
Agents	Claude Code, Codex CLI, Gemini CLI, Antigravity, Copilot CLI, Cursor, VS Code, Pi, Claude Desktop, or anything that speaks MCP over HTTP

It also works for agents that live in a sandbox or a chat app: --deliver file sends the MP4 itself, kept under WhatsApp's 16 MB limit.

Limitations

• English voices only.
• macOS on Apple silicon is the main platform. Linux and Intel Macs are supported; Windows is untested.
• No generated images, by design: image APIs cost money and local image generation is slow.
• Extras for export. Layout checks and MP4 export need Playwright's Chromium and FFmpeg.

Code and setup instructions for each agent: github.com/rahimnathwani/showntell.