James-Chahwan/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.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**:
>
>
>
> 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.)*
| | 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."*