⚡ 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

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

✨ Key features

🛠️ MCP tools exposed

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.

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

Environment variables (only read by rag --answer, in this precedence order): GEMINI_API_KEY → OPENAI_API_KEY → ANTHROPIC_API_KEY → OLLAMA_HOST. 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.