CodeTour

Animated, LLM-driven guided tours of code, pitched at a developer new to the codebase.

CodeTour is an MCP server paired with a local browser viewer. Claude (or any MCP-driving LLM) calls CodeTour's tools step by step; the viewer animates through the code — file tree, diffs or source excerpts, pulsing line highlights — while the narration is shown as captions and spoken aloud via the browser's built-in text-to-speech. The subject can be a pull request, an area of existing code, or local git work; where there is a GitHub page behind it, every stop links back to it.

How it works

Claude ──(MCP stdio)──▶ codetour ──(WebSocket)──▶ your browser
                          │                        (or a headless one, recorded to .mp4)
                          └──(REST)──▶ GitHub API

1. The LLM calls get_pr_info / get_file_diff to read the PR through CodeTour, so its narration matches exactly what is displayed. (For a codebase tour it uses its own Read/Grep tools to decide what to show, and CodeTour reads the files from disk.)

2. start_tour opens the viewer in your browser and waits for you to click Start (the click also enables audio).

3. show_overview and a series of show_step calls animate through the changes. Each call blocks until the narration finishes speaking, so the tour paces itself naturally.

4. end_tour shows a closing summary, with a link back to GitHub where the tour has one.

Related MCP server: Code Review MCP Server

Four ways to start a tour

A tour does not have to be about a change. Whatever the subject, the viewer, narration and controls are the same.

Stops come in two flavours and can be mixed in one tour: show_step for a diff hunk and show_code for an excerpt of existing source (real file line numbers, no diff markers). That means a PR tour started with root= can also show the unchanged caller of new code.

Source files are only ever read from inside the tour's root — paths that resolve outside it are refused.

Video mode

Any tour can be recorded to an .mp4 instead of played live — handy for attaching to a pull request. Pass video="/absolute/path.mp4" to any start_* tool (the skill does this for "record a video of this PR" or /codetour --video). Nothing opens on screen: a headless Chromium renders the viewer, each stop's narration is synthesised with macOS say, and end_tour muxes the two with ffmpeg and returns the file's path and size.

uv sync --extra video               # Playwright
uv run playwright install chromium  # the headless browser (~150 MB, once)
brew install ffmpeg

Try it without an MCP client: uv run codetour --demo code --video ~/Desktop/demo.mp4.

A three-minute tour at the default 1280×720 and CRF 26 comes out at a few megabytes, well under GitHub's 10 MB attachment cap for free plans (100 MB on paid plans). GitHub has no upload API for PR attachments, so the last step is a drag into the PR description or a comment. Recording is macOS-only for now (say); the narration engine is a small interface in tts.py if you want to add another.

Installation

Requires Python 3.11+ and uv.

git clone <this repo> && cd CodeTour
uv sync

Register with Claude Code at user scope, so the tools are available in every repo:

claude mcp add --scope user codetour -- uv --directory /path/to/CodeTour run codetour

Then just ask:

Give me an executive tour of https://github.com/owner/repo/pull/123

The codetour skill

The repo ships a Claude Code skill (skills/codetour/SKILL.md) that teaches Claude the craft of a good tour: choosing the right entry point, auto-detecting the current branch's PR via gh, planning 3–7 stops before opening the viewer, junior-developer-level narration style (references/narration.md), how to route a codebase tour (references/code-tours.md), and how to recover when the viewer is closed. Install it by linking (or copying) it into your personal skills directory:

ln -s /path/to/CodeTour/skills/codetour ~/.claude/skills/codetour

With the skill installed, a plain "tour this PR" in any repo does the right thing. Restart your Claude Code session after installing the MCP server or the skill.

GitHub authentication

Public PRs work unauthenticated (low rate limit). For private repos or a higher limit, CodeTour uses the first of: GITHUB_TOKEN, GH_TOKEN, or the gh CLI's stored token (gh auth login).

Configuration

Viewer controls

The tour plays itself as the LLM narrates, but the viewer can take over at any point:

Navigating is local to the browser: it re-narrates the stop you land on and never disturbs the LLM. If you browse backwards or pause while the LLM is still adding stops, the view stays where you are and new stops simply extend the dots — the viewer keeps acknowledging them so the LLM is never left waiting. Step forward to the newest stop and the viewer follows along live again.

Development

uv run pytest                 # unit tests, including the frontend harness
uv run ruff check .           # lint
uv run codetour --demo       # web viewer only, plays a canned pull request tour once
uv run codetour --demo code  # a tour of CodeTour's own source, via the real read path
uv run codetour --demo code --video /tmp/demo.mp4  # record it instead (video extras needed)

tests/frontend/dom_harness.mjs runs app.js under Node against a stub DOM to test the viewer's navigation state machine without a browser (needs node; no npm packages). Run it directly for a readable pass/fail list:

node tests/frontend/dom_harness.mjs

Demo mode is the quickest way to iterate on the frontend: it needs no MCP client and no GitHub access — open the printed URL, click Start, and watch the canned tour.

MCP tools