repo2graph

---

⚡ What is repo2graph?

When an AI coding agent searches a codebase with grep or plain keyword matching, it either dumps whole matching files into context — burning the token budget and losing structure — or misses the implementation entirely because it used different words than the search query.

repo2graph parses source with tree-sitter into a graph of real code relationships — CALLS, IMPORTS, INHERITS, DEFINES, CO_CHANGE — and serves that graph to agents over the Model Context Protocol, or packs it into a budget-bounded markdown context for any LLM. Every returned block carries an exact [cite: path:start-end] anchor, so answers are traceable back to source instead of paraphrased from a guess.

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.

🚀 Quickstart (under 30 seconds)

Requires Python 3.10+. Run via uv, no install step:

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

One pass over this repository — 185 files — takes about two 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:

🔌 MCP client configuration

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.

✨ Key features

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.
15 languages, full treatment	Python, JS/TS/TSX, Go, Rust, Java, Ruby, C, C++, C#, PHP, Kotlin, Swift, Scala, Bash get functions/classes/calls. Everything else still appears as files on the map.
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 make zero network calls. The one opt-in exception (rag --answer) prints the provider + hostname before sending anything.
Export to real graph tooling	graph.graphml (yEd, Gephi, NetworkX) and graph.cypher (Neo4j, Memgraph) come out of every build, no extra step.

🆚 How it compares

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 15 parsed languages, 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.

🛠️ MCP tools exposed

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 (max 4), limit (default 20, max 50)	One graph hop from a symbol/file/dir id: callers, callees, base classes, defining file.

Secrets are excluded unconditionally on every tool call — no flag turns that off. Full contract, including the two diagnostic tools (repo_cache_stats, repo_build_status) added for long-running server deployments: docs/mcp.md.

📐 Architecture & token economics

• 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.

Repository	Language(s)	Scope	Nodes	Edges
Kubernetes	Go	scoped (controllers, scheduler, API server)	14,197	83,525
TensorFlow	C++ / Python	scoped (Python/C++ boundary)	20,641	96,013
Django	Python	full repository	54,544	228,461
VS Code	TypeScript	scoped (src/vs/)	113,115	431,453
Linux kernel	C	scoped (extreme-scale)	136,182	257,655

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).

📖 CLI & server reference

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	Node/edge/function counts for an existing index.
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.

🔐 Security

build, query, rag, and the MCP server make no network calls. rag --answer is the one opt-in exception — it sends the assembled pack to an LLM provider and prints the provider + hostname before doing so. The MCP server excludes credential-shaped files unconditionally, with no flag to turn that off. Details: 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 test   # or: ruff check . && pytest

• .github/CONTRIBUTING.md — full local dev setup, code style, and the registry/Glama release process.
• docs/BACKLOG.md — deliberately deferred work and why; the closest thing to a roadmap, plus a "good first issues" section.
• AGENTS.md — this codebase's non-obvious conventions (Windows encoding, text slicing, the two budget models) before editing repo2graph/.
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
• Found a bug or have a feature idea? Open an issue.

License

MIT. See LICENSE.

---