Repo Tour

Repo Tour

A guided walkthrough of an unfamiliar GitHub repo. Output a 5-section markdown report so the reader can decide what it does, how it's built, where to start reading, what's active right now, and what to watch out for.

Steps

1. Identify the repo. Parse owner/name from the user query. If the user gave only a name, ask once for the owner. If they gave a URL, strip to owner/name.

2. Read the README. Call the GitHub MCP tool to fetch README.md from the default branch. This is the single highest-value read — do it first.

3. Map the top-level structure. List the contents of the root directory. Note presence of: src/, lib/, app/, pkg/, cmd/, internal/, tests/, docs/, examples/, scripts/. Their absence is also a signal.

4. Read the build/config manifest. Whichever exists, pick the most authoritative:

   • pyproject.toml / setup.py / requirements.txt (Python)
   • package.json (JS/TS)
   • Cargo.toml (Rust)
   • go.mod (Go)
   • Gemfile (Ruby)
   • pom.xml / build.gradle (JVM)

   Extract: name, version, declared dependencies (top 5–10 only), entry points / scripts.

5. Find entry points. Look for main.*, index.*, cli.*, __main__.py, files referenced under [project.scripts] / "bin" / "main" in the manifest. Read one entry-point file end-to-end.

6. Sample recent activity. Fetch:

   • The 5 most recent merged pull requests.
   • The 5 most recent open issues.

   Skim titles and short bodies. Look for themes (refactor in progress, breaking change brewing, frequently reported bug, large unmerged PR).

7. Synthesize the report. Output exactly five sections in markdown:

   ## What it does
   2–3 sentences. Plain language. No marketing copy.
   
   ## How it's built
   Language, frameworks, top dependencies, notable architecture choices.
   
   ## Where to start reading
   1–3 file paths a new contributor should open first, with one sentence each.
   
   ## What's active
   Themes from recent PRs and open issues. Surface anything unusual.
   
   ## What to watch
   Risks, gotchas, deprecated paths, pinned issues, unfinished refactors.
   

Stopping rules

• If the README alone answers the user's question, stop after step 2 and report.
• Don't recursively read every file. Sample, don't crawl.
• Hard ceiling: at most ~10 GitHub MCP tool calls per tour. Quality over coverage.

Tips

• If a directory listing is huge (>50 entries), only read the first page.
• If a file is huge (>1k lines), read just the first ~100 lines.
• Prefer search_code over deep traversal when looking for a specific symbol.