Blog post

Your AI assistant reads too much. Give it a map.

AI coding assistants grep and read across a repo before they answer. A structural map lets the model read only what matters. Proof in the numbers.

Watch your AI assistant work on an unfamiliar repo and you'll see the same loop: grep, read a file, grep again, read another, repeat. It's reconstructing the structure of your codebase from scratch, one file at a time, on every task. That's tokens spent, time spent, and a model still partly guessing when it finally edits something.

The fix isn't a bigger context window. It's giving the model the map up front.

What repo-graph does

repo-graph is an MCP server that builds a structural graph of your codebase: the entities, how they connect, and the feature flows that run frontend to backend. The model queries the graph to find the right files instead of reading everything to find them. The engine is Rust and tree-sitter, and it handles 20+ languages and frameworks, cross-stack.

It exposes 11 tools across four tiers. Three carry most of the day-to-day load:

• status — orient first. The shape of the repo before anything else.
• dense_text — the whole graph as dense text. The primary context dump.
• activate — spreading activation (Personalized PageRank) from seed nodes, so the model pulls in what's actually related to the thing it's working on.

The pattern is simple: before grepping or reading files, call status to orient, then dense_text for full context, or activate/find/flow to scope down.

How it reads in practice

You ask your assistant questions in plain English. Behind the scenes it picks the tool:

• "Where does the groups action hit the backend?" → trace finds the shortest path from the frontend node to the handler.
• "What's the request flow for creating a group?" → flow returns entry → service → data for that feature.
• "If I change this handler, what breaks?" → impact gives the blast radius by tier.
• "What's directly wired to this function?" → neighbours for the one-hop connections.

No reading fifteen files to answer any of them.

The numbers

We ran the same bug twice on quokka-stack, a Go + Angular monorepo (~566 nodes / 620 edges). A reversed comparison operator. Same model, same prompt, both runs.

Without repo-graph: 75,308 tokens, 4m36s, ~15 files explored. Grep, read, grep, read, narrowing in.

With repo-graph: 29,838 tokens, ~30s, 2 files touched — one flow lookup to locate the handler, then the handler file itself.

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

Install

Zero-install with uvx:

uvx mcp-repo-graph --repo .

Or pin it:

pip install mcp-repo-graph

Wire it into your assistant:

claude mcp add repo-graph -- uvx mcp-repo-graph --repo .
codex mcp add repo-graph -- uvx mcp-repo-graph --repo .
gemini mcp add repo-graph uvx mcp-repo-graph --repo .

For Cursor, Windsurf, Antigravity, or any MCP client, add an mcpServers block:

{
  "mcpServers": {
    "repo-graph": {
      "command": "uvx",
      "args": ["mcp-repo-graph", "--repo", "."]
    }
  }
}

VS Code has an extension (code --install-extension james-chahwan.repo-graph), and Claude Desktop has the .mcpb desktop extension.

Point generate at a local path or a git URL and it'll scan and build the graph. Run reload after you change code.

Try it: uvx mcp-repo-graph --repo . — more at repo-graph.com.