Cartograph

The problem

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

The reflex is RAG: embed the code, 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.

Live numbers from this repo

Impact analysis, before the edit

The query that earns the whole project. One call names the dependent files and the tests to run.

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

Architecture, extracted not documented

Module graph, layering, cycles and hotspots — computed from imports and the call graph. Edge labels are import counts; PageRank picks out the symbols that carry the codebase.

flowchart LR
  m0["cartograph.indexer.extract"] -- 5 --> m1["cartograph.models"]
  m2["cartograph.mcp_server.server"] -- 5 --> m3["cartograph.service"]
  m4["cartograph.cli"] -- 4 --> m3["cartograph.service"]
  m5["cartograph.graph.store"] -- 4 --> m1["cartograph.models"]
  m6["cartograph.views"] -- 4 --> m3["cartograph.service"]
  m7["cartograph.graph.resolver"] -- 3 --> m5["cartograph.graph.store"]
  m3["cartograph.service"] -- 3 --> m8["cartograph.graph.algorithms"]
  m3["cartograph.service"] -- 3 --> m1["cartograph.models"]
  m6["cartograph.views"] -- 3 --> m1["cartograph.models"]
  m9["scripts.build_docs"] -- 3 --> m3["cartograph.service"]
  m4["cartograph.cli"] -- 2 --> m10["cartograph.indexer.pipeline"]
  m7["cartograph.graph.resolver"] -- 2 --> m11["cartograph.indexer.languages"]
  m12["cartograph.indexer.bindings"] -- 2 --> m11["cartograph.indexer.languages"]
  m0["cartograph.indexer.extract"] -- 2 --> m11["cartograph.indexer.languages"]
  m10["cartograph.indexer.pipeline"] -- 2 --> m5["cartograph.graph.store"]
  m10["cartograph.indexer.pipeline"] -- 2 --> m1["cartograph.models"]
  m3["cartograph.service"] -- 2 --> m5["cartograph.graph.store"]
  m4["cartograph.cli"] --> m13["cartograph"]
  %% showing 18 of 40 module edges by weight

Hotspots — highest PageRank

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 every edge records the rule that produced it and a confidence, and callers choose their own operating point: who_calls is precision-first (≥0.5), blast_radius is recall-first (≥0.3).

The 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 was unique — and surfacing as a confident caller. A method name on a receiver you cannot type is not evidence, so it now sits below the precision line.

Local type inference, and where it refuses

The largest class of unresolvable call is receiver.method(): you cannot know that self.conn.execute(...) means sqlite3.Connection.execute without knowing what conn is. Cartograph works it out from three shallow sources — annotations (def f(store: GraphStore), s *Store), construction (GraphStore(...), new Engine(), &Engine{}) and aliases (self.store = store, chased transitively) — across Python, TypeScript, JavaScript and Go. Attribute chains resolve one hop, so s.conn.Exec() is a Conn.Exec when s is a Store.

What it deliberately will not do is return-type propagation, generics or cross-module dataflow. A wrong inferred type produces a confident edge pointing at the wrong function, and an agent acts on it — strictly worse than an honest unresolved. So a variable reassigned to a second type keeps its first binding, and a real union binds nothing.

Inheritance is answered from the inherits edges the graph already stored: once a rule names the receiver's owner and finds no member on it directly, its declared bases are walked breadth-first. That is worth +6.9 points on django and +5.8 on flask — the mirror image of inference, which pays on annotated code and does almost nothing for class-heavy dynamic Python.

Once a pinned owner's whole ancestry has been searched, where that ancestry ends is itself the answer. Entirely inside the repo, and the member is genuinely not ours. At a third-party base, and the member is unittest’s — django’s self.assertEqual reaches unittest.TestCase through several in-repo base classes, and 15,360 call sites move from “no idea” to a correct, specific answer. At a name we cannot account for, absence proves nothing and the cascade goes on.

Locality is not evidence about ownership either. Same-package name matches used to be broken by a deterministic sort, which produced confident but arbitrary edges — on gin, w.Header().Get resolved to Params.Get. Measured against the edges inference now types at 0.97: where a method name had exactly one owner the old rules were right 100% of the time (n=658), and where it had more than one, 66% (n=296). Multi-owner ties are now reported as ambiguous.

The tool surface

Ten MCP tools, two resources and a prompt. Descriptions are written as routing guidance, because the description is the prompt the model uses to choose.

Benchmarks

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

Warm reindex is fast because resolution is skipped only when both its inputs are provably unchanged. Resolution is counted per call site, and only a above-threshold edge counts — an ambiguous site emits one edge per candidate, so counting edges scored six guesses as six successes. Reproduce with scripts/bench.py --clone.

Try it

uv tool install cartograph-mcp

cartograph index ~/code/my-repo
cartograph arch
cartograph blast src/auth/token.py

# wire it into an agent
claude mcp add cartograph -- cartograph serve ~/code/my-repo

Limitations

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

• Type inference is local only. Annotations, constructors and aliases, one attribute hop, within a file. A receiver whose type is never written down — app.config.get(...) — stays unresolved, which is most of what remains on untyped Python.
• Inheritance is walked, but not linearised. Bases are searched breadth-first, which matches C3 for single inheritance but can pick a different branch of a diamond than the interpreter would.
• Interface dispatch is not modelled. A call through a Go interface or an abstract base resolves to no single implementation.
• Dynamic dispatch is invisible. getattr(obj, name)(), decorator registries and DI containers produce no edges.
• No cross-language edges. A TypeScript frontend calling a Python endpoint is two disconnected subgraphs.