CodeTour

Animated, LLM-driven "explain like I'm five" tours of GitHub pull requests.

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 pull request — file tree, diffs, pulsing line highlights — while the narration is shown as captions and spoken aloud via the browser's built-in text-to-speech. Every stop links back to GitHub so viewers can dig into the detail themselves.

How it works

Claude ──(MCP stdio)──▶ codetour ──(WebSocket)──▶ your browser
                          │
                          └──(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.

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 to the PR on GitHub.

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: auto-detecting the current branch's PR via gh, planning 3–7 stops before opening the viewer, ELI5 narration style rules, 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

Development

uv run pytest                 # unit tests
uv run ruff check .           # lint
uv run codetour --demo        # web viewer only, replays a canned tour on a loop

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