repo2graph

Give coding agents trustworthy, cited answers about unfamiliar codebases.

Ask a repository a question; get back the actual source that answers it, every block stamped with the file and line range it came from.

English · 简体中文 · 日本語 · Français · Español · Deutsch

📦  Package	🩺  Health	🗂️  Listed on

What is it · Who it's for · vs. grep · Quickstart · MCP setup · What it won't do · Benchmarks · Architecture · Docs · Contributing

⚡ What is repo2graph?

An agent dropped into a codebase it has never seen has two bad options. Grep for a word and it either floods its context with whole matching files, or finds nothing because the code spells the idea differently than you did. Guess from training data and it writes something confident and wrong. Either way you cannot tell which of the two just happened.

repo2graph answers questions about a repository with the repository's own source. Ask "how does a request get authenticated" and you get back the function that does it, the functions that call it and the ones it calls — each block headed [cite: path:start-end], so every claim in the answer is one click from the line it came from. If the answer is wrong, the citation shows you where it went wrong. That is the whole point.

It gets there by reading the code rather than searching it: one parse pass records who calls whom, who imports what, and which class extends which, and retrieval follows those links instead of matching more text. The result is served straight into Claude Code, Cursor or any Model Context Protocol client, or packed into a markdown context with a hard token ceiling for any other LLM.

flowchart LR
    A[your code] --> B[tree-sitter<br/>reads the code]
    B --> C[graph<br/>dots + arrows]
    C --> D[graph.html<br/>the picture]
    C --> E[chunks.jsonl<br/>pieces for an AI]
    C -->|MCP stdio| F[Claude / Cursor /<br/>any MCP client]

No project setup, no language server, no build step — point it at a folder and it works.

Interactive canvas, zoomed	Filter & inspector controls

graph.html is one self-contained file — no server, no internet, drag to pan, scroll to zoom, click a node to inspect its code and neighbours.

👥 Who it's for

uvx repo2graph build . -o .r2g
open .r2g/human/graph.html
repo2graph rag "how does routing work" -o .r2g

claude mcp add repo2graph -- \
  uvx --from "repo2graph[mcp]" repo2graph-mcp .

repo2graph build . -o .r2g --git-history 500
repo2graph explain node "sym:src/auth.py::verify" -o .r2g

- uses: Srinivasan-78/repo2graph@v2
  with: { git-history: "500", commit-branch: graph }

🔎 Why repo2graph instead of grep or vector search?

Both of those are still in the box — repo2graph seeds every query with BM25, and dense vectors are an opt-in fusion. The difference is what happens after the first match.

Use grep when you want every occurrence of a literal string — a config key, an error message, a TODO. repo2graph has no special knowledge of string literals and will not beat it. Use repo2graph when the question is about relationships: what calls this, what breaks if I change it, how does data get from A to B. Longer version: docs/why-graph.md.

🚀 Four ways to run repo2graph

Same graph, same chunk format, same .r2g output — pick the interface for where you're standing right now.

🐍 1. Python / CLI

Requires Python 3.10+. The fastest way to see what it does — a bundled example repo, indexed and interrogated, with nothing to configure and no repository of your own:

uvx repo2graph demo

That writes a small orders service to a scratch directory, builds a real graph over it, and answers five questions against it, each one citing files and line ranges. Then point it at your own code:

uvx repo2graph build . -o .r2g && open .r2g/human/graph.html

Or install it properly:

pip install repo2graph
repo2graph build /path/to/project -o .r2g --git-history 200
repo2graph query "how does routing match a path" -o .r2g

Two minutes end to end, with the expected output at each step: docs/quickstart.md.

Five questions to start with

The ones that show what a graph gives you over a text search. Copy any of them onto your own repo — or run repo2graph demo to watch each answered against the bundled fixture.

repo2graph rag "What would be affected by changing pack_context?" -o .r2g

Something not working? repo2graph doctor . checks the environment, the index and your MCP client config, and prints a fix for anything it finds.

One pass over this repository — 195 files, 2,552 nodes, 11,118 edges — takes about three seconds and needs no configuration file, no language server and no API key. Ask it something, and the answer comes back as source you can check, not a summary you have to trust:

Full flag tables, budget accounting and the Python API: docs/cli.md · docs/python-api.md.

⚙️ 2. GitHub Action

Published on the GitHub Marketplace — one step, no Python setup on the runner:

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }   # full history, so CO_CHANGE edges are meaningful

- uses: Srinivasan-78/repo2graph@v2
  with:
    path: .                  # or: repo: some-org/other-repo
    git-history: "500"       # commits scanned for CO_CHANGE edges (0 = skip)
    artifact-name: repo-graph

@v2 follows every 2.x release; pin an exact tag (@v2.2.0) to upgrade by hand instead. It never calls an LLM — --answer is deliberately not exposed — and it writes a job-summary table (hub files, CO_CHANGE hotspots, the graph delta since the last build) straight from the artifacts, so the shape of the map shows up in the run without downloading anything.

Also pack a cited context for a fixed question, and push the map to a browsable branch:

- uses: Srinivasan-78/repo2graph@v2
  with:
    query: "how does auth middleware validate a token"
    commit-branch: graph     # force-pushed; this repo's own /graph branch is built this way

All inputs/outputs, private-repo tokens and the vector-embedding step: docs/github-action.md.

🔌 3. MCP server

repo2graph-mcp is a stdio MCP server. It builds its own index on the first call if one doesn't exist yet — nothing to run ahead of time.

Claude Code

claude mcp add repo2graph -- uvx --from "repo2graph[mcp]" repo2graph-mcp /path/to/project

Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json) — same block:

{
  "mcpServers": {
    "repo2graph": {
      "command": "uvx",
      "args": ["--from", "repo2graph[mcp]", "repo2graph-mcp", "/path/to/project"]
    }
  }
}

Any other stdio-based MCP client (Windsurf, Zed, generic clients) takes the same command/args pair — see docs/mcp.md for config file locations per platform and client.

That is the hop grep cannot do: one symbol in, and its definer, its callers and its callees come back with file and line — the relationship, not a text match that happens to contain the name.

🐳 4. Docker

For enterprise and shared deployments, an official Dockerfile is provided. It's a multi-stage build running as a non-root user (10000:10000), fully compatible with a read-only root filesystem and dropped capabilities.

docker build -t repo2graph .
docker run --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --network=none \
  -v /path/to/repo:/repo:ro \
  -v repo2graph-index:/repo/.r2g \
  repo2graph build /repo -o /repo/.r2g

See docs/ENTERPRISE_DEPLOYMENT.md for full container hardening and HTTP server instructions, and docs/deployment-security.md for the trust boundary and supported/not-recommended verdict per deployment shape — including whether HTTP without TLS is safe (short answer: only on loopback) and a worked hardened reverse-proxy example.

✨ Key features

⚖️ What it does — and what it does not

A retrieval tool that oversells itself is worse than no retrieval tool, because you stop checking its answers. So, plainly:

It does

• Return the source that answers a question, cited to path:start-end, inside a token budget it enforces rather than requests.
• Resolve callers, callees, imports and class hierarchies from a real parse of the code, and let you walk them in either direction from any symbol.
• Mine CO_CHANGE from git history — the files that keep being edited together, which no parser can tell you.
• Run entirely locally, with no model, no account and no network call, in the CLI, in CI and over MCP.
• Degrade gracefully: an unparsed language still appears as file nodes and is still retrievable as text; a missing vector index falls back to BM25 rather than failing.

It does not

Every one of these is measured, not asserted — the rates, the repositories they were measured on, and the reproduction commands are in docs/limitations.md. See also the dynamic pattern evaluation in BENCHMARK.md and the framework relationship proposal in docs/rfcs/rfc-framework-relationship-graph.md.

🆚 How it compares to other graph tools

Several tools build a graph out of a codebase. The thing that separates them is what comes back when you ask a question — a picture, a subgraph, or the code itself.

Reach for Graphify when the graph itself is the product: community detection, shortest path between two concepts, and your PDFs and design docs in the same graph as the code. Reach for the Obsidian plugin when a human wants to read the graph beside their notes. Reach for repo2graph when an agent needs cited source inside a fixed token budget, when it has to run in CI with no model and no account, or when "which files keep changing together" is part of the answer.

Longer version, with the trade-offs each choice implies: docs/comparison.md.

🛠️ MCP tools exposed

Five tools. Three answer questions about the code; two report on the server itself.

The three content tools exclude secrets unconditionally — no flag turns that off — and every numeric argument is clamped in the handler, so a caller cannot widen a bound by asking. Full contract, argument ceilings and client configs: docs/mcp.md. Running it shared, over HTTP, with bearer or OIDC auth and an audit log: docs/ENTERPRISE_DEPLOYMENT.md.

📐 Architecture & token economics

The retrieval layer is a GraphRAG pipeline: tree-sitter parses the source into a typed graph, BM25 picks the seed chunks, and the graph — not further text similarity — decides what else is worth spending the budget on. Optional dense vectors (repo2graph embed) fuse into the seed ranking; nothing downstream requires them.

• Nodes: repo, dir, file, symbol (function/method/class/struct/trait/interface/type), module (external dependency), external (an unresolved call target).
• Edges: CONTAINS, DEFINES, IMPORTS, CALLS (carries count + confidence), CALLS_EXTERNAL, INHERITS, CO_CHANGE (from --git-history, requires 3+ co-edits).
• Call resolution is name-based, not type-based — a deliberate trade-off that keeps repo2graph language-agnostic and setup-free. Ambiguous calls fan out to up to 5 candidate edges at confidence = 1/n; filter to confidence == 1.0 when you need certainty over recall.
• Two budget models, on purpose: Index.retrieve()'s budget_chars bounds only the chunks' own text (a back-compat surface); Index.pack_context()'s budget_chars bounds the entire rendered markdown — citation headers, separators, everything. New retrieval code should be built on pack_context().
• Chunking: roughly one chunk per function/class, cut at ~4000 characters with 8 lines of overlap so nothing is lost at a seam; each chunk's header names its callers and callees, which is what makes graph-expanded retrieval better than plain top-k text search.

Full breakdown of every node/edge kind and the chunk schema: docs/reference.md. The pipeline, the Python API, and where the graph guesses (and why): TECHNICAL.md.

📊 See it on real repositories

Not a toy demo — five real, large, public repositories, each indexed at a pinned commit, with the generated graph committed and the exact reproduction command recorded. Every number is measured, from benchmarks/results.json, not estimated.

See examples/README.md for the full index and reproduction commands, docs/benchmarks.md for methodology, and docs/limitations.md for what running against five real repositories actually surfaced (parse-error rates on macro-heavy C/C++, call-name ambiguity, cross-language resolution limits).

🧪 Reproducible benchmark & regression suite

Beyond full-scale public codebase indexing, repo2graph includes a reproducible 25-task benchmark across 5 application archetypes (benchmarks/corpus/: TypeScript app, Python backend, modular monolith, React frontend, and dynamic patterns) comparing repo2graph against ripgrep and agent-baseline search:

Full methodology, ground truth evidence, failure cases, and reproduction scripts: BENCHMARK.md. Continuous benchmark regression checking is enforced in CI via .github/workflows/benchmark.yml.

📖 CLI & server reference

Environment variables (only read by rag --answer, in this precedence order): GEMINI_API_KEY → OPENAI_API_KEY → ANTHROPIC_API_KEY → OLLAMA_HOST. --model overrides the provider's best-effort default. No other command makes a network call or reads these. Full flag tables and budget accounting: docs/cli.md.

🔐 Security

• Secure-by-default secret exclusion: build, github, auto-building query/rag, the GitHub Action and MCP all skip credential files automatically — .env*, private keys, certificates, .ssh, .aws, .gnupg, .kube, credentials/, secrets/ and more. --include-secrets opts out; the MCP tools have no equivalent, because an agent returning .env is a different problem from a human choosing to read it.
• Content-aware secret scanning: Chunks are scanned for high-entropy tokens, cloud API keys (AWS, OpenAI, Google, Slack, GitHub), JWTs, DB URLs and private keys. Matches are redacted line-preservingly (--secret-policy redact-match|exclude-file|warn-only|off).
• Sanitized logs and events: Audit logs and structured event sinks enforce cycle detection, container size limits, recursion depth ceilings, and scrub URL basic-auth credentials.
• Local by default, and only one path ever sends your code: build, query, rag, map, stats and the MCP server over stdio open no socket at all — asserted by socket-level tests, not just by reading the code. Four commands can reach the network, and only the first sends anything of yours: rag --answer (uploads the pack; prints provider + hostname first), repo2graph github (clones), repo2graph embed (downloads an embedding model once), and repo2graph-mcp --auth-oidc-issuer (fetches public keys). No telemetry of any kind, and no setting to turn off.

Where every byte goes and how to delete it: docs/PRIVACY.md. What an attacker could try, and what is out of scope: docs/THREAT_MODEL.md. Hardened configurations to copy: docs/secure-configuration.md. Reporting a vulnerability: .github/SECURITY.md.

🤝 Contributing & community

git clone https://github.com/Srinivasan-78/repo2graph
cd repo2graph
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
make lint format-check typecheck test    # the four gates CI runs

Branch from develop and open the PR against it — main is the release branch. make lint alone is only ruff check .; ruff format --check . is a separate gate and the one people miss.

• docs/good-first-issues.md — seven starter tasks, each with a file and line to start from, acceptance criteria, and the catch that makes it harder than it looks.
• .github/CONTRIBUTING.md — local setup, the CI gates, the branch model, the test house style, and the registry/Glama release process.
• docs/ARCHITECTURE.md — the module map: what each module owns, which way dependencies run, and where a change of each kind goes.
• docs/BACKLOG.md — deliberately deferred work and why; the closest thing to a roadmap.
• LANGUAGE_SUPPORT.md — strategic language roadmap, scorecard generator, and ecosystem relationship extraction (routes, test links, DI, ORMs).
• BENCHMARK.md — reproducible 25-task evaluation across 5 archetypes, comparison against ripgrep and agent baseline, and regression gating.
• PR_IMPACT.md — flagship PR & diff architectural blast radius analysis, reverse caller exposure, test coverage mapping, and CI workflow.
• docs/ROADMAP_LANGUAGE_ISSUES.md — prioritized tracking issues (LANG-01 to LANG-11) for deep language and framework support.
• AGENTS.md — this codebase's non-obvious conventions (Windows encoding, text slicing, the two budget models) before editing repo2graph/.
• POSITIONING.md — what repo2graph claims, what it deliberately does not claim, and the copy for every outward-facing surface. Read it before changing any of them.
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
• Found a bug or have a feature idea? Open an issue.

License

MIT. See LICENSE.