What this tutorial solves
Hooking up Claude to GitHub is easy — click “connect”, grant scope, done. Using it well without burning tokens, leaking access, or getting plausible-sounding nonsense is the actual skill. This guide shows how to treat the GitHub connector as a read-only research tool over your own code, with prompts that force grounded answers and habits that keep the scope tight. Audience: developers maintaining a codebase who want to answer “where is X” and “how does Y work” without copy-pasting files into chat.
Who this is for
Developers maintaining an existing codebase who want Claude to answer questions about it without you pasting files. Particularly valuable for new joiners on a large repo, or maintainers asked to explain modules to someone else.
When to reach for it
Understanding an unfamiliar codebase, reviewing a PR before opening it locally, finding “where is X implemented”, comparing two branches, or drafting a tour of a module before writing documentation.
When this is NOT the right tool
Live IDE editing (use Cursor or Claude Code); private repos you cannot grant access to; or trivial questions answerable by reading the README. Also avoid for security-sensitive code paths your plan does not commit to keeping out of training.
Before you start
- Authorize the connector for only the specific repos you need. Refuse the default “all repos” scope; it widens blast radius and slows retrieval.
- Make sure the repo’s main branch is the one you actually want analyzed. The connector defaults to main; if you live on
develop, mention it in every prompt. - Have a known question ready to baseline trust. “Where is rate limiting implemented?” with a known answer lets you spot hallucinations on the first response.
- Decide whether you want answers with file:line references (recommended) and state that in your first message.
Step by step
- Authorize the GitHub connector for only the specific repos you need. Wider scope = more confusion. Use a fine-grained personal access token if available.
- Start each chat with a specific question: “Where is rate limiting implemented?” not “explain the codebase”. The first question sets the grounding for everything after.
- Ask Claude to first list the relevant files, then drill in.
List the 3-5 files most relevant to authentication, then I will pick one to walk through.This forces it to inventory before interpreting. - For “how does X work”, ask for one specific entry point plus the call chain. Avoid letting Claude wander the whole repo; it will produce confidently wrong threads.
- When reviewing a PR, paste the PR URL and ask:
Summarize the change in 3 sentences with file:line references. Then list any risk you see, with the exact line.Follow up:What is the smallest change that achieves the same goal? - For long answers, ask for direct file:line references for every claim. Open 2-3 in GitHub and verify before trusting the rest.
First-run exercise
- Pick a module you wrote yourself recently. Familiarity is your hallucination detector.
- Ask Claude:
Walk me through how this module is invoked, starting from any HTTP route or job that triggers it. Give file:line refs for every step. - Open the references in GitHub. Mark which were correct, which were misrouted, which were invented.
- Refine your prompt with whatever made step 3’s answer wobble. Save the refined prompt.
Quality check
- Every claim has a file:line reference. No exceptions; vague summaries hide errors.
- The references actually exist and contain what Claude said they contain. Spot-check at least 3.
- The answer scope matches the question. If you asked about auth and the answer wanders into logging, push back.
- The connector is reading the branch you expected. Ask
Which branch are you using for these answers?once per session.
How to reuse this workflow
- Save your favorite “explain this module” and “review this PR” prompts as canned templates.
- For onboarding to a new codebase, run the same set of prompts week 1 and week 4 — note what you now know that Claude got wrong before.
- For PR review, build a single template: summary, risk, smallest-change suggestion, test gaps. Use the same template every PR.
- Audit which repos the connector still has access to monthly. Revoke retired projects.
Recommended workflow
New job, unfamiliar codebase: day 1 chat — What are the 5 most important files in this repo and what does each do? Include file:line refs. Day 2 — Walk me through the auth flow with file:line refs for every step. Day 3 — How is testing organized? Which files have the worst coverage? Cite paths.
FAQ
- Does Claude clone the whole repo?: It indexes / retrieves on-demand. Smaller scopes = faster + more accurate retrieval.
- Will Claude edit my code?: The GitHub connector is read-only. Use Claude Code or Cursor for actual edits.
- What about private repos?: Supported with proper OAuth scopes; consider a separate token for the connector if your org is strict.
- Can it see all branches?: Mostly main by default; you may need to mention other branches explicitly. PRs are accessible via URL.
- Why does it sometimes invent function names?: Long answers across many files drift; tighten scope and re-ask if you see invented identifiers.
- Does the connector cost extra?: It uses your existing Claude plan’s token allowance; large repos consume more tokens per query.
Common mistakes
- Connecting your entire GitHub account and letting Claude poke around. Slow + privacy risk.
- Asking high-level questions (“is this good code?”) without specifics — get vague opinions.
- Trusting unsourced claims. Always re-ask for file:line refs.
- Expecting Claude to know commits it cannot see (private branches, recent unpushed changes).
- Mixing two repos in one chat — Claude blends conventions and invents file paths.
- Reviewing 3 PRs in one conversation — symptoms of one bleed into another, and you cannot tell whose problem is whose.
Advanced tips
- For multi-PR reviews, do one chat per PR. Mixing PRs makes Claude confuse changes.
- Ask Claude to draft a “tour” of the codebase as a Markdown file you can keep — much faster than re-asking later.
- When Claude misroutes, give it the right file as a hint: “Look in
src/api/rateLimit.tsspecifically.” Anchoring beats arguing. - For repeat onboarding (you onboard new hires to the same repo), save a “tour starter” doc with your favorite prompts; share with new joiners.