Repo Graph

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

---

### Upgrading to 0.5.4

Most people don't have to do anything. uvx and pip install mcp-repo-graph pull in the new

engine (glia 0.5.7, pinned exactly). The first start in each repo reparses everything once. Same

six tools, same arguments.

You only need to act in two cases:

- You hand-wrote stanzas in `.glia/overlay.toml`. Add origin = "human" to each [[wrapper]],

[constants] and [[route_prefix]] stanza you wrote yourself. An unmarked stanza is now treated

as model-written, and the links it creates are ranked heuristic.

- You also run glia's own CLI hooks in the same repo. Reinstall the CLI at v0.5.7 too, or the

two rebuild each other's cache on every commit.

What's better: MCP servers (Python @mcp.tool(), the TypeScript SDK's McpServer) are read as

hosts, so their tool functions are entry points, not dead code. Every declared entry (host starts,

scripts, __main__ guards) now starts a flow. Rails nested resources, C# [HttpX] + [Route]

actions, Angular lazy routes and Solidity events come out right. Test-to-code pairing and Python

attributes are less noisy.

### Upgrading to 0.5.3

Most people don't have to do anything. uvx and pip install mcp-repo-graph pull in the new

engine (glia 0.5.6, pinned exactly). The first start in each repo reparses everything once.

Three things changed that you might notice:

- `impact` answers big radiuses as an overview. A hub node used to return every row (thousands

on a large repo). It now returns the top 25, then the areas and files the rest fall in. Drill in

with scope= , page with offset, or pass full=true for the old every-row answer. If a

script parses repo-graph impact output and needs every row, add --full.

- The skills are renamed repo-graph- → glia- (/repo-graph:glia-find). They

now live in glia and also show the glia CLI command. The plugin updates them for you.

- Absence tiers are lowercase: No answer (no_match, fact), not FACT.

If you also run glia's own CLI hooks in the same repo, reinstall the CLI at v0.5.6 too, or

the two rebuild each other's cache on every commit.

What's better: rankings put files that historically change together first (once you've run

uvx --from glia-cli glia history sync .), far fewer phantom edges in every language, routes carry their mount prefix

(Django, Flask / FastAPI, Express / Koa / NestJS, gin groups), the graph knows what a Dockerfile,

compose service, Procfile or systemd unit starts, Lua is parsed, and the file watcher updates the

graph in place instead of rebuilding it. Every tool is also a shell command (`uvx mcp-repo-graph

find checkout`), no server needed.

### 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:

`diff

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

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.

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

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, 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 dir