rahimnathwani/showntell

Narrated slide walkthroughs for coding agents, voiced on your machine.
Ask your agent to walk you through a pull request, a module or a concept. It writes slides and narration in Markdown; showntell voices them locally with Kokoro and hands back a link that starts playing in about a second, while the rest is still being written. A pointer follows the narration through code, diagrams and lists, word by word.
Watch the gallery: ten walkthroughs written by Claude (Opus and Sonnet) and voiced on a laptop, unedited: a tour of this repository, one call's path through it, a refactor step by step, a code review, contributor setup, a speed-up told with a chart, the messages of an MCP tool call, the TLS 1.3 handshake, scaled dot-product attention, and git rebase versus merge on a phone-shaped frame.
Local: speech runs on your Mac or PC. No API keys, no hosted service, no telemetry. Code never leaves your machine except to the model you already use.
Fast: the link is playable about 0.3 s after the agent sends its opening, so you start watching while the agent keeps writing.
Grounded: code slides are read straight from your files and git history, with real line numbers. The agent never retypes code, and the pointer lands on the right line.
Checked: every call returns coded findings to the agent: a cue pointing at a missing line, code too big for the frame, narration that reads the screen aloud, a slide that holds still too long, and, from the player, diagrams that failed to render or text shrunk too small to read; with Playwright installed, finishwalkthrough draws every slide to find them. The agent can also look at pictures of its slides with previewslides.
Shareable: export a walkthrough as one HTML file that plays offline (send it in Slack or by email), a static folder with captions, or an MP4; embed it with , link to a range of slides, or present it yourself with speaker notes. An agent in a sandbox or behind WhatsApp sends you the MP4 itself.
How it compares with a screen recording, a written PR description and a rendered MP4 explainer, including where those win: docs/comparison.md.
## Install
You need uv. It installs Python 3.12 or newer for you if needed.
Every agent runs the same command, which starts showntell as a stdio MCP server:
zsh
uvx --from git+https://github.com/rahimnathwani/showntell@v0.1.8 showntell mcp
The tag after @ installs that release; leave it off for the latest commit. Once showntell is on PyPI this shortens to uvx showntell mcp. Pick your agent below, then ask it something like "walk me through how a request gets retried in this codebase". The agent replies with a link; open it and press play.
The first run downloads the voice model (about 330 MB on Apple silicon, 92 MB elsewhere) and a 12 MB English language model. The first walkthrough takes a few seconds longer while they load. After that, everything works offline.
The base install leaves out the browser that draws slides. With it, finishwalkthrough checks every slide's layout and shows the agent pictures of slides that look alike, each walkthrough gets a poster in the gallery, and MP4 export works. To add it, use the video extra in place of the command above and fetch Chromium (about 100 MB) once: