repo-graph

Structural graph memory for AI coding assistants. Map your codebase. Navigate by structure. Read only what matters.

repo-graph gives LLMs a map of your codebase — entities, relationships, and flows — so they can navigate to the right files without reading everything first.

Instead of flooding an LLM's context window with your entire codebase (or hoping it guesses right), repo-graph builds a lightweight graph of what exists, how things connect, and where the entry points are. The LLM queries the graph, finds the minimal set of files it needs, and reads only those.

It pays off most where that's hardest to do by hand: large repos, monorepos that span several languages, and multi-service systems where a feature's path crosses files, stacks, and service boundaries. On a small single-language project a model can just read the files — see Where it fits best for the honest sweet spot.

Install in one click:

Or one command in your terminal wires up every agent you have: uvx mcp-repo-graph install (see Install).

Demo

https://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a

https://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883

Same bug, same model, same prompt — the only difference is whether repo-graph is installed.

The task: fix a reversed comparison operator in a Go + Angular monorepo (566 nodes, 620 edges).

2.5x fewer tokens. ~9x faster. Same correct fix.

How the test was run

Both runs used identical conditions to keep the comparison fair:

• Same model: Claude Opus, 100% (no Haiku routing)
• Same prompt: "Groups that were created recently are showing as closed, and old groups show as open. This is backwards — new groups should be open for members to join. Find and fix the bug."
• Fresh context: each run started from /clear with no prior conversation
• No other tools: CLAUDE.md, plugins, hooks, and all other MCP servers were removed for both runs — the only variable was whether repo-graph was installed
• No hints: the prompt describes the symptom, not the location — Claude has to find group_controller.go:57 on its own

Without repo-graph, Claude greps for keywords, reads files, greps again, reads more files, and eventually narrows down to the bug. With repo-graph, Claude calls trace("groups"), gets back the exact handler function and file, reads it, and fixes it.

Browse pre-generated examples for FastAPI, Gin, Hono, and NestJS — real graph output you can inspect without installing anything.

The problem

LLMs working on code waste most of their context on orientation:

• Reading files that turn out to be irrelevant
• Missing connections between components in different languages
• Not knowing where a feature starts or what it touches
• Loading 50 files when 5 would do

This is expensive, slow, and gets worse as codebases grow.

How repo-graph solves it

repo-graph scans your codebase once and builds a graph of:

• Entities: modules, packages, classes, functions, routes, services, components
• Relationships: imports, calls, handles, defines, contains, cross-stack HTTP
• Flows: end-to-end paths from entry point to data layer

Then it exposes 6 MCP tools that let the LLM:

1. Orient — "What languages are in this repo? What are the main features? Where is the graph blind?"
2. Navigate — "Trace the login flow from route to database" / "What's the shortest path between UserService and the payments API?"
3. Scope — "Which nodes matter for this bug?" / "Give me just the files I need for this fix"
4. Assess — "What's the blast radius of changing this function?" / "What here is dead code?"

The LLM gets structural context in a few hundred tokens instead of reading thousands of lines.

Where it fits best

repo-graph earns its keep when a codebase is bigger or more tangled than the model can hold in its head at once. The payoff scales with three things:

• Size — enough files that reading the relevant ones blows the context budget.
• Complexity — rules, indirection, and layers, so "just read it" stops working.
• Cross-boundary reach — the answer spans files, languages, or services that a text search can't link.

Strong fits:

• Monorepos — a frontend calling a backend across a language boundary. repo-graph links the HTTP call to the route it hits and the handler behind it — the one thing grep structurally can't do. Point --repo at the monorepo root and a single graph spans every project. (The demo above is exactly this: Go + Angular in one repo.)
• Multi-service / polyrepo systems — drop the services under one directory and point --repo at it; the graph traces a feature across service boundaries in one call.
• Large single codebases — thousands of files where orientation itself is the cost.
• Unfamiliar or legacy code — where you don't yet know what touches what.

Where it doesn't pull its weight: a small, single-language repo with a clear task. The model can just read the files — grep wins and the graph is overhead. Don't reach for it to shave tokens, either: the MCP layer is a fixed per-turn cost, so on easy tasks it can cost more. The token win shows up only when it heads off a grep-read-grep spiral (like the demo above). What it reliably buys you is correct, complete, cross-boundary answers in a few calls on code too big or too interconnected to fit in context — yours or the model's. (Don't want the MCP layer at all? Skip it and call the engine directly.)

Use it without MCP

The MCP server is the zero-config path, but the graph isn't tied to it. The engine ships as a plain Python wheel — pip install repo-graph-py — so you can build the graph and call the same answer primitives directly, from a script or your own tooling, with none of the per-turn MCP cost:

import repo_graph_py as rg

g = rg.generate(".")                            # or rg.load_from_gmap(rg.default_gmap_dir("."))
print(g.blast_radius("checkout", "both"))       # ranked, located, live-filtered — JSON
print(g.cross_stack_trace("notifications"))     # feature path across the stack, mechanism-labelled
print(g.resolve(open("error.log").read()))      # stacktrace / test / diff → the nodes that matter
print(g.coverage())                             # where extraction is partial (grep those)

Same graph, same answers — just without the tool schemas in your context. It's the same Rust engine (glia) the MCP server wraps; repo-graph-py is its published wheel. Good for CI checks, batch analysis, or wiring the graph into your own agent.

Supported languages