Cartograph

Agent-native code intelligence. Turn any repository into a queryable code graph and serve it to coding agents over MCP — so an agent can ask "what breaks if I change this?" instead of grepping and hoping.

tree-sitter + SQLite. No embeddings, no vector store, no API keys, no server, no cost.

→ Live demo — generated from a real index of this repo on every push.

The problem

Give a coding agent a large unfamiliar repo and watch what it does: grep, read a file, grep again, read another file. It burns context reconstructing structure that a parser could have told it in one call — and it still misses the caller three modules away that its change just broke.

The usual fix is RAG: embed the codebase, retrieve "similar" chunks. But "who calls this function?" is not a similarity question. It has an exact answer, and that answer lives in the call graph.

Cartograph builds the graph, then hands agents ten tools shaped for how they actually work.

$ cartograph blast src/cartograph/graph/store.py

## Blast radius — file `src/cartograph/graph/store.py`

17 dependent file(s), 31 affected symbol(s), 7 test file(s).

**Tests to run first**
- `tests/test_cli.py`
- `tests/test_docs.py`
- `tests/test_incremental.py`
- `tests/test_mcp.py`
- `tests/test_resolver.py`
- `tests/test_traversal.py`
- `tests/test_views.py`

**Dependent files** (by import distance)
- `src/cartograph/graph/resolver.py` · d1
- `src/cartograph/indexer/pipeline.py` · d1
- `src/cartograph/service.py` · d1
- `src/cartograph/cli.py` · d2
…

One call, before the edit. Not seven greps after the test suite goes red.

Quickstart

uv tool install cartograph-mcp     # or: pipx install cartograph-mcp

cartograph index ~/code/my-repo    # builds .cartograph/cartograph.db
cartograph arch                    # modules, layers, cycles, hotspots
cartograph blast src/auth/token.py # what a change here could break
cartograph callers validate_token  # reverse call tree

Wire it into an agent

Claude Code:

claude mcp add cartograph -- cartograph serve /path/to/repo

Or any MCP client, via mcp.json:

{
  "mcpServers": {
    "cartograph": {
      "command": "cartograph",
      "args": ["serve", "/path/to/repo"]
    }
  }
}

serve indexes on first run if no index exists. Then ask your agent "what would break if I changed the token validator?" and it will call blast_radius instead of guessing.

The ten tools

Plus MCP resources (cartograph://architecture, cartograph://stats) and an orient prompt for a graph-first first pass at an unfamiliar repo.

Languages: Python, TypeScript, TSX, JavaScript, Go.

Design decisions worth arguing about

1. Confidence is a first-class column

Without a type checker you cannot know that store.who_calls() means GraphStore.who_calls. You can only rank hypotheses. So rather than pretending, every edge records the rule that produced it and a confidence:

Callers then choose their own operating point. who_calls defaults to ≥0.5 — precision first, because an agent acts on the answer. blast_radius drops to 0.3 — recall first, because a missed impacted test is the expensive mistake and a false positive only costs a reviewer a glance.

That name-only tier exists because of a real bug. seen.add(...) on a builtin set was resolving to a repo class's add method, purely because the name happened to be unique — and it showed up as a confident caller. A method name on a receiver you cannot type is not evidence, so it now lands below the precision line. (test)

external exists for honesty about metrics: on most repos the "unresolved" bucket is dominated by typer.Option and sqlite3.execute. Lumping those in makes coverage look far worse than it is, so Cartograph reports internal resolution — of the call sites that could hit a repo symbol, how many did.

2. Parsing is incremental; resolution never is

A file is reparsed only when its sha256 moves. But raw references are stored as facts in a refs table, and edges is recomputed as a pure function of (refs × symbols) whenever anything changed.

This is what makes "reindex after every edit" trustworthy. If resolution were also incremental, editing one file could leave an edge in another file pointing at a symbol that had moved. Global re-resolution makes that structurally impossible. (test)

The cost is real, so there is exactly one safe shortcut: if no file was added, reparsed, or removed, both input tables are unchanged and resolution is provably identical — so it is skipped. That took a no-op reindex of Django from 7.5s to 0.67s with a byte-identical graph.

3. PageRank instead of embeddings

"Which get did you mean?" is a structural question. The get that forty call sites depend on is the one the agent wants, and the call graph already knows that. So symbol ranking is weighted PageRank over the call graph — stable, explainable, and free. No model, no index build, no vector store.

related_symbols extends the same idea: personalized PageRank seeded on one symbol, treating the graph as undirected, because when you are about to change a function both its callers and its callees are relevant context. It is the structural analogue of semantic search, and it needs no embeddings.

4. Tools return Markdown, not JSON, under a token budget

The consumer is a context window. A 40-symbol JSON array spends thousands of tokens on braces and repeated keys, and the model reformats it anyway. Every view here is compact Markdown with a hard token budget.

Critically, every truncation is announced. An agent handed 20 of 87 callers with no marker will confidently conclude the other 67 do not exist, and then delete something.

5. Traversal runs in SQLite, not Python

who_calls at depth 4 is a recursive CTE, so the whole traversal stays inside SQLite's C loop. On Django's 252k-edge graph that is ~5ms. Pulling the edge table into Python to walk it would not be.

Benchmarks

Real repositories, M-series laptop, single process. Cold = full index from scratch; warm = no-op reindex.

Query latency (median of 5, warm):

Reproduce with scripts/bench.py.

Architecture

flowchart LR
  subgraph index["cartograph index"]
    W[walker<br/>git ls-files] --> P[tree-sitter<br/>+ .scm queries]
    P --> X[extract<br/>defs · refs · imports]
  end
  X --> DB[(SQLite<br/>symbols · refs<br/>edges · FTS5)]
  DB --> R[resolver<br/>rule cascade]
  R --> DB
  DB --> RK[PageRank<br/>Tarjan SCC]
  RK --> DB
  DB --> S[service facade]
  S --> V[views<br/>token-budgeted MD]
  V --> M[MCP server<br/>10 tools]
  V --> C[CLI]
  M --> A((coding agent))

Scoping without combinatorial queries

The trick that keeps queries/*.scm small: scope is never encoded in the query. Every captured definition is indexed by its tree-sitter node id, and a reference's enclosing symbol is found by walking its parent chain until it hits one. That is O(tree depth) per reference and handles closures, methods, inner classes, and arrow functions for free — no per-shape patterns.

Adding a language

Subclass LanguageAdapter (~40 lines) and drop in a .scm file. GoAdapter is the shortest complete example. tests/test_queries.py then automatically compiles your queries against the grammar and asserts they capture something.

Development

git clone https://github.com/GokulRaj2210/cartograph-mcp && cd cartograph-mcp
uv sync
uv run pytest -q          # 209 tests
uv run ruff check .
uv run mypy               # strict

CI runs the suite on Python 3.11/3.12/3.13 (plus macOS), then dogfoods: it indexes this repo, fails on import cycles, asserts a no-op reindex reparses nothing, and drives the MCP server over real stdio. It also installs the built wheel into a clean venv and indexes with it, because packaged .scm files are easy to leave out of a wheel and impossible to notice locally.

The cycle gate has already earned its keep — it caught a store → resolver → store cycle that I introduced in this repo, which was fixed by moving the offending helper rather than by relaxing the gate.

Notable tests

• tests/test_queries.py — every .scm compiles against every grammar that loads it, and captures something. A pattern valid in JavaScript ((class_heritage (identifier))) is an Impossible pattern in TypeScript, which wraps supertypes in extends_clause. That one line silently produced zero TypeScript symbols.

• tests/test_incremental.py — no stale edges after edits, deletions, or a symbol moving between files.

• tests/test_resolver.py — every rule fires, and none over-claims its confidence.

• tests/test_cli.py — a reader and an indexer can hold the database at once.

• tests/test_docs.py — the generated demo page is well-formed HTML with balanced tags, which is how the Markdown renderer's crossed-tag bug on min_confidence was caught.

Limitations

Stated plainly, because a code-intelligence tool that oversells its precision is worse than useless:

• No type inference. self.conn.execute(...) cannot be resolved to a repo symbol without knowing conn's type. Those land in unresolved, and they are the bulk of what remains at ~85% internal resolution.

• Dynamic dispatch is invisible. getattr(obj, name)(), decorator registries, and DI containers do not appear as edges.

• Cross-language edges are not tracked. A TypeScript frontend calling a Python endpoint is two disconnected subgraphs.

• Definitions only, not every reference. A symbol used as a value (passed as a callback) is weaker in the graph than one that is called.

Roadmap: Rust and Java adapters, optional LSP enrichment for exact resolution where a language server is available, and a --changed-since <ref> mode for PR-scoped blast radius.

Why this exists

I wanted to know whether a coding agent's biggest weakness on large repos — no structural model of the code — could be fixed with static analysis and a well-shaped tool surface rather than a bigger model or a vector database. Mostly, it can.

License

MIT