CodeTour

애니메이션 방식의 LLM 기반 '다섯 살에게 설명하듯이' GitHub 풀 리퀘스트 투어.

CodeTour는 MCP 서버와 로컬 브라우저 뷰어로 구성됩니다. Claude(또는 MCP를 구동하는 모든 LLM)는 CodeTour의 도구를 단계별로 호출하며, 뷰어는 파일 트리, diff, 펄스 라인 강조 표시를 애니메이션으로 보여줍니다. 이때 내레이션은 캡션으로 표시되고 브라우저의 기본 텍스트 음성 변환을 통해 소리로 읽힙니다. 각 정류장은 GitHub로 연결되어 보는 사람이 직접 세부 내용을 확인할 수 있습니다.

작동 방식

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

1. LLM은 get_pr_info / get_file_diff를 호출하여 CodeTour를 통해 PR을 읽으므로 내레이션이 표시되는 내용과 정확히 일치합니다.

2. start_tour는 브라우저에서 뷰어를 열고 시작을 클릭할 때까지 기다립니다(클릭하면 오디오도 활성화됩니다).

3. show_overview와 일련의 show_step 호출은 변경 사항을 애니메이션으로 보여줍니다. 각 호출은 내레이션 말하기가 끝날 때까지 대기하므로 투어가 자연스럽게 진행됩니다.

4. end_tour는 GitHub의 PR 링크와 함께 마무리 요약을 표시합니다.

설치

Python 3.11+ 및 uv가 필요합니다.

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

Claude Code에 사용자 범위로 등록하면 모든 저장소에서 도구를 사용할 수 있습니다:

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

그런 다음 그냥 요청하세요:

https://github.com/owner/repo/pull/123의 경영진용 투어를 보여줘.

codetour 스킬

이 저장소에는 좋은 투어를 만드는 요령을 Claude에게 가르쳐 주는 Claude Code 스킬(skills/codetour/SKILL.md)이 포함되어 있습니다: gh를 통해 현재 브랜치의 PR을 자동 감지하고, 뷰어를 열기 전에 3~7개의 정류장을 계획하며, ELI5 내레이션 스타일 규칙과 뷰어가 닫혔을 때 복구하는 방법을 다룹니다. 개인 스킬 디렉터리에 링크(또는 복사)하여 설치하세요:

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

스킬을 설치하면 어떤 저장소에서든 그냥 "이 PR 투어"라고 말하면 올바르게 동작합니다. MCP 서버나 스킬을 설치한 후에는 Claude Code 세션을 다시 시작하세요.

GitHub 인증

공개 PR은 인증 없이도 동작합니다(속도 제한 낮음). 비공개 저장소 또는 더 높은 제한이 필요하면 CodeTour는 다음 중 첫 번째를 사용합니다: GITHUB_TOKEN, GH_TOKEN, 또는 gh CLI에 저장된 토큰(gh auth login).

구성

개발

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

데모 모드는 프런트엔드를 반복 개발하는 가장 빠른 방법입니다: MCP 클라이언트도 GitHub 접근도 필요 없습니다 — 출력된 URL을 열고 시작을 클릭하면 준비된 투어를 볼 수 있습니다.

MCP 도구