CodeTour

Animierte, LLM-gesteuerte "Erklär's-wie-einem-Fünfjährigen"-Touren durch GitHub-Pull-Requests.

CodeTour ist ein MCP-Server, gepaart mit einem lokalen Browser-Viewer. Claude (oder ein beliebiges MCP-gesteuertes LLM) ruft die Tools von CodeTour Schritt für Schritt auf; der Viewer animiert durch den Pull-Request — Dateibaum, Diffs, pulsierende Zeilenhervorhebungen — während die Erzählung als Untertitel angezeigt und über die integrierte Text-to-Speech-Funktion des Browsers laut vorgelesen wird. Jeder Stopp verlinkt zurück zu GitHub, damit die Zuschauer selbst ins Detail gehen können.

So funktioniert's

Claude ──(MCP stdio)──▶ codetour ──(WebSocket)──▶ your browser
                          │
                          └──(REST)──▶ GitHub API

1. Das LLM ruft get_pr_info / get_file_diff auf, um den PR über CodeTour zu lesen, sodass seine Erzählung genau dem entspricht, was angezeigt wird.

2. start_tour öffnet den Viewer in deinem Browser und wartet darauf, dass du auf Start klickst (der Klick aktiviert auch den Ton).

3. show_overview und eine Reihe von show_step-Aufrufen animieren durch die Änderungen. Jeder Aufruf blockiert, bis die Erzählung zu Ende gesprochen ist, sodass sich die Tour natürlich selbst taktet.

4. end_tour zeigt eine abschließende Zusammenfassung mit einem Link zum PR auf GitHub.

Installation

Benötigt Python 3.11+ und uv.

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

Registriere CodeTour bei Claude Code im user scope, damit die Tools in jedem Repository verfügbar sind:

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

Dann frag einfach:

Gib mir eine Überblickstour durch https://github.com/owner/repo/pull/123

Der codetour-Skill

Das Repository enthält einen Claude Code Skill (skills/codetour/SKILL.md), der Claude die Kunst einer guten Tour beibringt: automatisches Erkennen des PR des aktuellen Branches über gh, Planung von 3–7 Stopps vor dem Öffnen des Viewers, ELI5-Erzählstilregeln und wie man weitermacht, wenn der Viewer geschlossen wird. Installiere ihn, indem du ihn in dein persönliches Skill-Verzeichnis verlinkst (oder kopierst):

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

Mit installiertem Skill genügt ein einfaches "tour diesen PR" in jedem Repository, und es passiert das Richtige. Starte deine Claude Code-Sitzung neu, nachdem du den MCP-Server oder den Skill installiert hast.

GitHub-Authentifizierung

Öffentliche PRs funktionieren ohne Authentifizierung (niedriges Rate-Limit). Für private Repositories oder ein höheres Limit verwendet CodeTour die erste der folgenden Optionen: GITHUB_TOKEN, GH_TOKEN oder das gespeicherte Token der gh-CLI (gh auth login).

Konfiguration

Entwicklung

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

Der Demo-Modus ist der schnellste Weg, um am Frontend zu iterieren: Er benötigt keinen MCP-Client und keinen GitHub-Zugriff — öffne die ausgegebene URL, klicke auf Start und sieh dir die vorgefertigte Tour an.

MCP-Tools