repo2graph

AST-driven code graphs & zero-dependency GraphRAG for AI coding agents and humans

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

📦  Package	🩺  Health	🗂️  Listed on

What is it · Quickstart · MCP setup · Compare · Benchmarks · Architecture · Docs · Contributing

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

🚀 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+. 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 — 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.1.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.

✨ Key features

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

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

• 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. --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, GitHub Action, and MCP exclude credential files (.env*, private keys, certificates, tokens, .ssh, .aws, .gnupg) automatically. Use --include-secrets only if you explicitly choose to index them.
• 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. Inline matches undergo line-preserving redaction (--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: 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. Details: .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 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.