The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Repo2graph listing page.
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
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.
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.
🧭 Joining a new codebaseThe problem: week one goes on reading files to find out which ones matter. Build once, open the map, and start from the hub files instead of the root directory. Then ask whole questions — "how does a request get from the router to the handler" — and read the answer as source, with the callers and callees already attached. |
🤖 Driving a coding agentThe problem: the agent greps, pulls in three whole files, and still edits the wrong one. Point Claude Code, Cursor or any MCP client at the repo. The agent gets cited blocks under a hard 12k-token ceiling instead of raw file dumps, and can walk from a symbol to its callers in one hop. Secrets are excluded from agent replies unconditionally — no flag turns that off. |
🔍 Reviewing a pull requestThe problem: the diff is 40 lines; the blast radius is unknown. Ask the graph what touches the changed symbol — callers, importers, subclasses — and what the
repository's own history says usually changes alongside it ( |
🌱 Maintaining a projectThe problem: every new contributor asks the same "where do I start" question. Commit a fresh graph on every push with the GitHub Action, and publish |
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.
| grep / ripgrep | Embedding search | repo2graph | |
|---|---|---|---|
| Finds | the exact string | text that reads similarly | the symbol, then everything wired to it |
| Different words than the code uses | returns nothing | handles it | BM25 seeds, then graph hops reach code the query never named |
| "What calls this?" | can't answer — a match in a comment ranks like the definition | can't answer — neighbours aren't in the embedding | CALLS edges, with direction and a confidence score |
| "What breaks if I change this?" | you read every hit by hand | not represented | callers, importers and subclasses in one hop |
| What comes back | matching lines, or whole files an agent then dumps into context | top-k similar chunks, callers unretrieved | the source that answers it, each block headed [cite: path:start-end] |
| Token cost | unbounded — the agent decides how much file to read | unbounded | hard ceiling on the whole pack, re-measured before it returns |
| "Which files keep changing together?" | — | — | CO_CHANGE, mined from git history |
| Setup | none | index build + an embedding model (~90 MB) | one parse pass, no model, no API key, no language server |
| Ranking is explainable | n/a | a cosine number | repo2graph explain retrieval "<q>" names the seed and the edge that pulled each block in |
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.
Same graph, same chunk format, same .r2g output — pick the interface for where you're
standing right now.
| 🐍 Python / CLI | ⚙️ GitHub Action | 🔌 MCP server | 🐳 Docker |
|---|---|---|---|
|
Local dev, scripting, ad-hoc questions from a terminal. |
A fresh graph committed next to your code on every push, zero Python setup. |
Give Claude, Cursor or any MCP client live, cited access to the codebase. |
Enterprise-ready, read-only, non-root container deployment. |
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:
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:
Or install it properly:
Two minutes end to end, with the expected output at each step: docs/quickstart.md.
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.
| Ask your repo | What comes back that grep cannot give you |
|---|---|
Where is authentication enforced? | the guard itself, plus every route that calls it |
What calls <function>? | CALLS edges in, so callers come back even when the name is shadowed |
What tests cover <module>? | IMPORTS edges from the test module back to the code under test |
What would be affected by changing <api>? | the blast radius: direct callers and what they are called from |
Trace <a request> from route to persistence. | a whole path across modules, each block cited to file and line |
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.
Published on the GitHub Marketplace — one step, no Python setup on the runner:
@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:
All inputs/outputs, private-repo tokens and the vector-embedding step: docs/github-action.md.
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 Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json) — same block:
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.
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.
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.
| Deterministic graph, not embeddings-only search | Callers, callees, imports and class hierarchies resolved from the actual AST — not a nearest-neighbour guess. |
| Hybrid retrieval | BM25 + graph-neighbour expansion by default; optional dense vector fusion (repo2graph embed) with zero required extra dependencies. |
| Hard token ceilings, enforced twice | pack_context()'s budget bounds the entire rendered markdown, not just chunk text — and the MCP server clamps and re-measures before returning. |
| 17 grammars, full treatment | Python, JS, TS, TSX, Go, Rust, Java, Ruby, C, C++, C#, PHP, Kotlin, Swift, Scala, Bash and Lua get functions/classes/calls — 29 file extensions in all. Everything else still appears as files on the map. See our strategic language scorecard and framework relationship RFC. |
| CI-native | Published as a GitHub Action — commit a fresh graph next to your code on every push. |
| Local by default | build, query, rag and the MCP server over stdio make zero network calls — asserted by socket-level tests. rag --answer is the only path that ever sends your code anywhere, and it prints the provider + hostname first. No telemetry. |
| Export to real graph tooling | graph.graphml (yEd, Gephi, NetworkX) and graph.cypher (Neo4j, Memgraph) come out of every build, no extra step. |
A retrieval tool that oversells itself is worse than no retrieval tool, because you stop checking its answers. So, plainly:
It does
path:start-end, inside a token budget
it enforces rather than requests.CO_CHANGE from git history — the files that keep being edited together, which no
parser can tell you.It does not
| Limitation | What that means in practice |
|---|---|
| Resolve calls by type | Calls are matched by name, with same-class / same-file / import scoping to break ties. When scoping can't isolate one target, the call fans out to up to 5 candidate edges at confidence = 1/n, flagged ambiguous. Filter to confidence == 1.0 when you need certainty over recall — 4.6%–21% of CALLS edges are ambiguous across our five benchmark repos. |
| See dynamic dispatch | A string-keyed lookup, a plugin registry, getattr-style dispatch, a virtual call resolved at runtime — none of it is written down as syntax, so no edge is drawn. No arrow does not prove no call. |
| See reflection or computed imports | importlib.import_module(name), Java reflection, a dynamic import() with a computed specifier. Nothing literal to resolve, so nothing to link. |
| Follow dependency injection to the implementation | A DI container wires an interface to a concrete class at runtime. The call site names the interface method, so the edge lands on the declaration (or fans out across every same-named implementation), never on the class the container actually injected. Walk INHERITS to enumerate the candidates. |
| Distinguish generated code | A .pb.go, a bundled .js, a codegen'd client — all indexed exactly like hand-written code, with no marker. They can dominate a symbol count without representing a line anyone maintains. Exclude them with --exclude. |
| Notice that your files changed | The index is a snapshot of the tree you built it from. Nothing watches the filesystem: edit a file and the graph keeps describing the old one. Rebuild (build --incremental re-parses only what moved), or let the GitHub Action rebuild on every push. repo2graph doctor checks index integrity and vector drift — not whether your working tree moved on. |
| Cross a language boundary | Python calling into C++ through generated bindings becomes a CALLS_EXTERNAL edge, not a link to the C++ function. That is a structural limit of source-only analysis, not a matching bug. |
| Parse macro-heavy C/C++ cleanly | tree-sitter emits ERROR nodes around unexpanded macros; a cpp preprocessor fallback recovers some. Expect a non-trivial parse_errors count in stats.json and read it as a floor on missed symbols. |
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.
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.
| repo2graph | Graphify | Code Graph (Obsidian) | grep / embedding RAG | |
|---|---|---|---|---|
| What a query returns | the source, packed — every block headed [cite: path:start-end] | a scoped subgraph, a path, or a concept explanation to traverse | a force-directed picture to read | matching lines, or nearest-neighbour chunks |
| How hits are ranked | BM25 seeds, then k-hop graph expansion; optional dense fusion | graph traversal (explicitly not a vector index) | n/a — it is a view | lexical only, or vectors only |
| Token budget | hard cap on the whole pack, re-measured before returning (12k ceiling over MCP) | not a packing layer | n/a | usually unbounded |
| Edges from git history | CO_CHANGE, from --git-history | — | — | — |
| Runs with no assistant, no model, no account | yes — CLI, MCP, or the GitHub Action | code pass is local; the docs/media pass uses a model | needs Obsidian desktop 1.7.2+ | varies |
| Corpus | code in 17 parsed grammars, every other file as text | code in ~40 languages, plus docs, PDFs, images, video | TS/TSX/JS/Python parsed, imports-only for 8 more | anything |
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.
Five tools. Three answer questions about the code; two report on the server itself.
| Tool | Arguments | What comes back |
|---|---|---|
repo_map | none | Languages, hub files, and top entry points. Stable across calls — read this first. |
repo_search | query, optional k (default 8, max 50), hops (default 1, max 4), budget_tokens (default 6000, max 12000) | Seed chunks plus graph neighbours, each block headed [cite: path:start-end]. |
repo_neighbours | node_id, optional hops (default 1, max 4), limit (default 20, max 50) | One graph hop from a symbol/file/dir id: callers, callees, base classes, defining file. |
repo_cache_stats | none | Result-cache counters: hits, misses, size, max_size, ttl_s, evictions, hit_rate. Never itself cached. |
repo_build_status | task_id | Progress of a background --async-build: building, ready, failed or unknown, with progress_pct and eta_s. |
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.
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.
repo, dir, file, symbol (function/method/class/struct/trait/interface/type),
module (external dependency), external (an unresolved call target).CONTAINS, DEFINES, IMPORTS, CALLS (carries count + confidence),
CALLS_EXTERNAL, INHERITS, CO_CHANGE (from --git-history, requires 3+ co-edits).confidence = 1/n; filter to confidence == 1.0 when you need certainty over recall.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().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.
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.
| Repository | Language(s) | Scope | Nodes | Edges |
|---|---|---|---|---|
| Kubernetes | Go | scoped (controllers, scheduler, API server) | 14,451 | 110,246 |
| TensorFlow | C++ / Python | scoped (Python/C++ boundary) | 21,380 | 115,984 |
| Django | Python | full repository | 55,810 | 303,339 |
| VS Code | TypeScript | scoped (src/vs/) | 113,080 | 656,158 |
| Linux kernel | C | scoped (extreme-scale) | 136,219 | 256,413 |
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).
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:
| Metric | repo2graph (GraphRAG) | ripgrep Search | Agent Baseline Search |
|---|---|---|---|
| Query Correctness | 100% (25/25) | 80.0% (20/25) | 56.0% (14/25) |
| Citation Precision | 97.9% (46/47) | 80.9% (38/47) | 55.3% (26/47) |
| Mean Query Latency | 1.82 ms | 12.44 ms | 31.84 ms |
| Token Budget Compliance | 100% (Clamped) | 0% (Unbounded) | 72% |
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.
| Command | Does |
|---|---|
repo2graph build <path> -o .r2g [--git-history N] | Parse a local repo into a graph + chunks. |
repo2graph github <owner/repo> -o <dir> | Fetch, build, and clean up — no local clone needed. |
repo2graph query "<question>" -o .r2g | Lexical search + one-hop graph expansion. |
repo2graph rag "<question>" -o .r2g [--vectors] [--answer] | Budget-bounded GraphRAG pack; --answer sends it to an LLM (opt-in, network). |
repo2graph embed -o .r2g [--verify-rag] | Compute/verify dense vectors for hybrid search. |
repo2graph map -o .r2g [--viz-nodes N] | Regenerate graph.html with a different node cap. |
repo2graph stats -o .r2g [--format text] | Node/edge/function counts for an existing index; --format text for a quality summary. |
repo2graph index-status -o .r2g [--json] [--check] | Indexed commit/branch, build time, counts, languages, skipped paths, size, and freshness. --check exits 1 when stale. |
repo2graph doctor [path] | Diagnose environment, dependencies, permissions, and index integrity. |
repo2graph bug-report -o .r2g [--category CAT] | Privacy-preserving diagnostic bundle for an issue. No source code, no paths by default. |
repo2graph explain-path <path> [-r <repo>] | Say whether a path would be indexed, and which precedence rule decided. |
| `repo2graph explain <edge | node |
repo2graph impact -i .r2g [--base main] | PR / diff architectural blast radius & impact analysis. |
repo2graph completion [shell] | Print shell tab completion setup script (bash, zsh, fish). |
repo2graph-mcp <path> [--no-auto-build] [--async-build] | stdio MCP server over .r2g. |
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.
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.--secret-policy redact-match|exclude-file|warn-only|off).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.
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.
LANG-01 to LANG-11) for deep language and framework support.repo2graph/.MIT. See LICENSE.
Found repo2graph useful? Star the repo — it's the easiest way to help other people find it.