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
-
Identify the repo. Parse
owner/namefrom the user query. If the user gave only a name, ask once for the owner. If they gave a URL, strip toowner/name. -
Read the README. Call the GitHub MCP tool to fetch
README.mdfrom the default branch. This is the single highest-value read — do it first. -
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.
-
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.
-
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. -
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).
-
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_codeover deep traversal when looking for a specific symbol.