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.
Structural graph map of any codebase so LLMs navigate by structure, not guesswork.
REPO_GRAPH_REPO
Последняя проверка
2026-11-09
Звёзды
—
Инструменты
—
Аптайм
—
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).
Upgrading to 0.5.2
Most people don't have to do anything.uvx and pip install mcp-repo-graph pull in the new
engine (glia 0.5.1, pinned exactly). The cached graph in .glia/graph/ is in a new format, so the
first start in each repo rebuilds it once. After that it's back to normal.
You only need to act if you also run glia's own CLI hooks (glia install-hooks) in the same
repo. Reinstall the CLI from the v0.5.1 tag too. If the CLI and the server are on different glia
versions, they rebuild each other's cache on every commit.
The same goes for a team that commits the cache with repo-graph's pre-commit hook: the next
commit re-adds it once in the new format, and anyone whose server still runs the glia 0.5.0 engine
rebuilds it on every load until they upgrade (uv tool upgrade mcp-repo-graph if you installed it
as a uv tool).
What's better: a richer graph (mounted Go routes carry their prefix, frontend endpoints pair through
their base URL, many more calls resolve), read shows the host a WebSocket / gRPC / GraphQL client
dials, and the server no longer creeps up in memory over long sessions.
⚠️ Upgrading to 0.5.0
The engine package was renamed repo-graph-py to glia-py. If you install with uvx or
pip install mcp-repo-graph, you don't have to do anything. The new engine is pulled in for you.
You only need to act if you import the engine directly:
- import repo_graph_py as rg
+ import glia_py as rg
Three other things changed in that same release:
The answers are Python objects, not JSON strings.find, resolve, blast_radius,
cross_stack_trace and governing_docs return a {"results": [...], "absence": {...}} dict.
If you were doing json.loads(...) on a result, drop it.
find_node and find_nodes_by_qname are gone. One find(query, top_k) replaces both.
The graph cache moved from .ai/repo-graph/ to .glia/graph/. It's rebuilt automatically,
so you can delete the old directory. The new one ignores itself and never shows up in
git status.
The six MCP tools are unchanged (orient, find, impact, trace, read, refresh), so
nothing in your agent config needs touching. Full detail in the
0.5.0 release notes.
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.
(Recorded on an earlier engine, which mapped that repo to 566 nodes / 620 edges. The glia 0.5.1 engine extracts far more from the same code, 3,466 nodes and 6,869 edges (measured 2026-10-02), so the graph the model gets today is richer than the one in the video. The token and time figures are from the recorded run and are left as measured.)
Without repo-graph
With repo-graph
Tokens used
75,308
29,838
Time to fix
4m 36s
~30s
Files explored
~15 (grep, read, grep, read...)
2 (trace lookup + handler file)
Outcome
Found and fixed the bug
Found and fixed the bug
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.
Flows: end-to-end paths from entry point to data layer
Then it exposes 6 MCP tools that let the LLM:
Orient — "What languages are in this repo? What are the main features? Where is the graph blind?"
Navigate — "Trace the login flow from route to database" / "What's the shortest path between UserService and the payments API?"
Scope — "Which nodes matter for this bug?" / "Give me just the files I need for this fix"
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, which a text search can't do because the two sides share no string. Point --repo at the monorepo root and a single graph spans every project. (The demo above is exactly this: Go + Angular in one repo.)
Other tools link fetch/axios to Express, Fastify and Koa routes. What differs here is reach: the same pairing runs across Go, Python, Java, C#, Rust, PHP, Ruby and the rest, in one graph, and covers gRPC, GraphQL, WebSockets, queues and events on the same footing. That breadth is not benchmarked against them, so take it as a design difference rather than a measured win.
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 glia-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 glia_py as rg
g = rg.load_from_gmap(rg.default_gmap_dir("."), ".") # builds it if there's no cache yet
g.find("checkout") # ranked, located nodes for a name
g.blast_radius(["checkout", "Cart.add"], "both") # many seeds, one walk, one ranking
g.cross_stack_trace("notifications") # feature path across the stack, mechanism-labelled
g.resolve(open("error.log").read()) # stacktrace / test / diff → the nodes that matter
g.coverage() # where extraction is partial (grep those)
Each of these returns plain Python — a {"results": [...], "absence": {...}} dict for the lookups,
a list for coverage(). When results is empty, absence says why, so a script can branch on it
instead of guessing.
Same graph, same answers — just without the tool schemas in your context. It's the same Rust engine (glia) the MCP server wraps; glia-py is its published wheel. Good for CI checks, batch analysis, or wiring the graph into your own agent.
Cross-cutting extractors (work across all languages):
Cross-stack HTTP: frontend fetch/axios calls linked to the backend route they hit, and the handler behind it
WebSockets: handlers and clients (gorilla, browser, Python, Java, C#), paired by path
gRPC: services, methods and message types from .proto, plus client stubs and server implementations
GraphQL: resolvers and the operations that call them
Queues: consumers and producers (Celery, Dramatiq, BullMQ, Sidekiq, Oban, NATS), with const-resolved topics
Events: emitters and handlers
Cron jobs: scheduled entry points
Page navigation: frontend routes and the links between them (NAVIGATES_TO)
Data sources: DB / cache / queue / blob / search / email clients, and which code touches which
Data entities: shared schemas and the code that reads or writes them
CLI entrypoints: Python click, JS commander/yargs, Go cobra, Rust clap, Java picocli, C# System.CommandLine and Spectre
Contracts: OpenAPI / AsyncAPI / Pact operations linked to the routes that implement them
Dependency injection: constructor injection wired to the thing injected
Config keys: where a key is defined and everywhere that reads it
Infra: Terraform and Kubernetes resources
Docs: doc sections linked to the symbols they govern (what read surfaces as governed by)
Tests: which tests cover which code
Multiple languages can match one repo (e.g., Go backend + Angular frontend + SCSS). Each contributes its nodes and edges into a single unified graph.
Install
One command
uvx mcp-repo-graph install
This detects the AI coding agents you have installed (Claude Code, Claude Desktop,
Cursor, Windsurf, VS Code, Codex, Gemini CLI, opencode, Kiro), writes each one's
MCP config, and adds a short usage block to its instructions file so the agent
reaches for the graph before it greps. Where the agent supports it, it also grants
auto-allow so repo-graph tools don't prompt on every call.
It's safe to re-run, and uvx mcp-repo-graph uninstall reverses everything
(config, instructions, permissions) while leaving your graph data in place.
uvx mcp-repo-graph install --agents all # every supported agent, not just detected
uvx mcp-repo-graph install --scope user # your global config, not this project
uvx mcp-repo-graph install --dry-run # show what it would write, change nothing
uvx mcp-repo-graph install --yes # no prompt (scripts and CI)
uvx mcp-repo-graph install --print-config cursor # print one agent's config, write nothing
Manual, per client
If you'd rather wire it up yourself, the package name is the run command.
uvx mcp-repo-graph just works. No prior pip install, nothing to keep on
PATH. This is the same command VS Code, Cursor, and the MCP registry use under
the hood.
Requirements: Python 3.11+, and uv if you use the
uvx path. Prebuilt wheels ship for the Rust engine on Linux (x86_64, aarch64),
macOS (Intel + Apple Silicon), and Windows (x86_64) — no Rust toolchain needed.
Claude Code
claude mcp add repo-graph -- uvx mcp-repo-graph --repo .
(--repo . points the graph at the current project; use an absolute path to pin it.)
VS Code
One command — adds the server to your user config:
Prefer a persistent install? pip install mcp-repo-graph (or uv tool install mcp-repo-graph) puts a mcp-repo-graph / repo-graph command on your PATH; then
use "command": "mcp-repo-graph" in the config above.
--repo also accepts a git URL. Point it at any public repo without cloning
first — it shallow-clones and maps it (requires git):
This generates the graph, writes .mcp.json and CLAUDE.md instructions, and gets your
AI assistant ready to use repo-graph. If you used the one-liners above, you can skip
this — the server builds the graph on first connect.
2. Use it
The AI assistant now has access to all 6 tools. Example queries it can answer:
"What does this codebase do?" → orient tool
"Trace the checkout flow" → trace tool
"What would break if I change UserService?" → impact tool
"Which nodes are relevant to this bug?" / "Here's a stacktrace — where do I look?" → find tool
"Show me that function's source" → read tool
"Give me the full graph context cheaply" → orient full=true
"Rebuild after a big refactor" → refresh tool
3. Freshness (automatic)
The graph stays current on its own. While the server is running it watches the repo
and does an incremental rebuild a moment after you save, so a structural question
right after an edit reflects the change with no manual refresh. On top of that, the
graph heals itself on cold start — if the cached .gmap is stale, an old format, or missing, the
engine rebuilds it and writes it back, so it's never stale when your assistant connects.
The watcher is on by default. Set REPO_GRAPH_WATCH=0 to disable it (the cold-start
refresh still applies). It needs the watchdog package, which ships as a dependency.
Want the cache pre-built and committed so teammates and CI get it too? Add the
pre-commit hook automatically:
That installs a marker-fenced pre-commit hook that refreshes the graph and stages
.glia/graph/ on every commit. uvx mcp-repo-graph uninstall removes it again.
Tip: The graph dir ignores itself (.glia/graph/.gitignore), so it never shows up in git status unless the hook stages it with git add -f. Skip the hook and the watcher plus cold-start refresh keep it fresh locally.
MCP tools reference
repo-graph exposes 6 tools — one natural verb each, backed by a Rust engine primitive.
Tool
Parameters
Description
orient
seed(optional), full, budget
The first call on a repo: node/edge counts, detected kinds, entry points, and a blind-spots note flagging which languages/edges are under-linked (so you grep those deliberately). seed=<node> → scoped map; full=true → whole-repo dense map
find
query, expand, kind, top_k, budget
Turn any text into the ranked nodes that matter — a symbol/keyword, or a pasted stacktrace / failing-test id / diff (resolved to the code it implicates). expand=true fans out to the surrounding neighbourhood. Every row carries path:line
Blast radius: what a change affects (forward) or depends on / is used by (backward), as a ranked, located closure — each row with the edge via reason and a ⊘ when the engine finds it unreachable (likely dead). Pass several nodes for a whole-diff radius
trace
from_node, to_node(optional), depth, budget
One arg: a feature end-to-end across the stack, each hop labelled with its mechanism (call / HTTP / queue / event) and cross-service hops marked. Two args: the shortest path between two nodes
read
node(comma-separated), context_lines, budget
A node's exact source, sliced from its file by the graph's line span, plus a context: footer (HTTP method, cross-stack callers or a client's dial target, covering tests, governing docs). Comma-separate to batch-read a ranked set
refresh
repo_path(optional), full
Rebuild the graph (incremental by default — only changed files re-parse). repo_path retargets a different path or git URL; full=true forces a clean reparse. Routine edits are auto-picked-up by the file watcher
Most tools also take a budget (max chars) so a result fits a small-model context window.
These 6 collapsed from an earlier 13 once the engine grew answer-shaped primitives — find, blast_radius, cross_stack_trace, resolve, coverage — that return complete, ranked, located, live-filtered results in one call. Fewer tools = less fixed per-turn overhead and less agent confusion.
It tells you when it doesn't know
Most tools answer an empty query with nothing, which leaves the assistant to guess whether that
means "no such edge exists" or "I couldn't see it". Since 0.5.0 an empty result comes back as a
structured absence: the reason, whether that reason is a FACT or a HEURISTIC, and which
extractions are partial for the mechanism that came up empty.
No answer (no_edges, FACT): no carry edge touches `backend::server::server` in this graph;
`backend::server::server` is a container: structural IMPORTS/CONTAINS/DEFINES are not carry
edges, so seed a symbol inside it
looked over: CALLS
blind spots (grep to confirm):
⚠ CALLS (*): calls through reflection, dynamic dispatch, or higher-order indirection are
not resolved — verify: grep the callee name
searched 26 nodes
orient surfaces the same blind spots up front, so the model knows when to grep instead of
trusting a gap.
What we measured. 14 symbols across FastAPI, Gin, Hono and NestJS, each one a case where the
graph honestly has no edge but real callers exist. Same agent, same task, the only difference being
whether an empty answer explained itself. The structured absence cut cost about 3x on identical
tasks, in 28 of 28 matched pairs, at the same number of turns: told why the answer is empty, the
agent stops re-querying. It did not change correctness. Sonnet 5 answered "not safe to delete"
in all 56 runs, so if you were hoping this stops an agent deleting live code, we have no evidence of
that and some evidence against it on a careful model. Harness and raw results are in
bench/absence/. One model, n=14, our own harness: treat it as directional.
0.5.0 also adds whole-diff impact in one call (unresolved names are reported, not dropped), ranked
distinct cross-stack paths in trace, and role-aware labels so a declared component or service isn't
flattened to "class".
How it works
mcp-repo-graph is a thin Python MCP server that wraps glia, a Rust engine.
Parse — per-language tree-sitter parsers extract raw nodes and unresolved references
Extract — cross-cutting extractors layer on HTTP routes, data sources, CLI entrypoints, gRPC services, queue consumers
Store — merged graph lands in .glia/graph/ as a zero-copy sharded .gmap (rkyv + mmap) plus a manifest
Serve — the MCP server loads the graph into memory and exposes the 6 tools
The Rust engine lives in its own glia repo; mcp-repo-graph is the MCP-facing thin wrapper.
Layout detection
repo-graph finds your projects itself — go.mod, package.json, pyproject.toml, Cargo.toml,
pom.xml, build.gradle, composer.json, pubspec.yaml, mix.exs, Package.swift,
CMakeLists.txt and friends. Point --repo at a monorepo root and every project under it lands in
one graph.
It also prunes on its own: node_modules, vendor, .venv, site-packages, build output
(dist, target, .next, .nuxt, .angular, coverage) and hashed bundle directories collapse
to a single region anchor instead of being parsed file by file, and .gitignore is honoured.
Note: earlier versions documented a config.yaml escape hatch with skip: / roots: keys.
That was a Python-era feature and the Rust engine does not read it — if you have one, it is being
ignored. If auto-detection misses your layout, please
open an issue with the shape of the repo;
that's more useful than a config file nobody can see.
Graph data format
Generated files live in .glia/graph/ inside the target repo:
repo-<id>.gmap: the graph itself, sharded, as zero-copy rkyv (mmap'd on load)
manifest.json: format version, repo labels, roots and parse errors, so a warm load equals a fresh generate
parse_cache.bin: per-file content-hashed parse cache, so an incremental rebuild only re-parses edited files
.gitignore: the dir ignores itself, so it never shows up in git status
The whole directory is regenerated: delete it and the next call rebuilds it.
The engine carries 36 edge categories. The ones you'll see most: CALLS, IMPORTS,
CONTAINS, DEFINES, USES, HANDLED_BY, HTTP_CALLS, IMPLEMENTS, INHERITS_FROM,
INJECTS, ACCESSES_DATA, TESTS, DOCUMENTS, NAVIGATES_TO, plus the channel ones
(GRPC_CALLS, QUEUE_FLOWS, WS_CONNECTS, EVENT_FLOWS, GRAPHQL_CALLS, RPC_CALLS).
There are 49 node kinds. Both tables come from the engine, so orient always reports the
set your version actually has.
Privacy Policy
repo-graph runs on your machine and is built to keep your code there. Full text: PRIVACY.md.
Telemetry / analytics: None. No tracking, no update checks, no phone-home.
Data collection & sharing: None. Your source code and graph data are never sent to repo-graph, its author, or any third party.
Local processing & storage: Scanning and graph-building happen locally; the graph is cached in your project's .glia/graph/ directory and stays on your device.
Network access — only two cases, both user-initiated:
Installation — uvx/pip downloads the package and its prebuilt engine wheel from PyPI.
Git-URL targets — if you pass a git URL to --repo, repo-graph runs git clone against the URL you specified; nothing is sent to repo-graph or its author. A local --repo path (the default) makes zero network calls.
Data retention: The local cache persists until you delete it — fully under your control.
Списка инструментов пока нет. У удалённых серверов он появляется после первой проверки состояния.
FAQ
Вопросы
Как установить Repo Graph?
Скопируйте на этой странице конфигурацию stdio для Cursor, Claude Desktop, Claude Code или VS Code. Она использует установку издателя, а не прокси PlugMCP.
Нужен ли API-ключ для Repo Graph?
Издатель указывает следующие переменные окружения: REPO_GRAPH_REPO.
Какой транспорт использует Repo Graph?
Repo Graph работает локально через stdio.
Когда Repo Graph проверялся в последний раз?
Последняя проверка: 2026-11-09. Structural graph map of any codebase so LLMs navigate by structure, not guesswork.