Foundations

The claim

A coding agent that only reads files in isolation will get small things wrong over and over: edit a function, miss a call site, break a test it never opened. The fix isn't a smarter agent — it's a better view of the codebase.

Causalist gives that view: a typed graph of every file, every dependency, every test. Claude Code reads it through tools, not by re-grepping the repo each turn.

What we model

For each repository:

• Files and modules — every source file, classified into a semantic layer (infra, data, logic, api, ui, test, config).
• Typed edges — imports, calls, reads, writes, extends. Every edge carries a verified flag based on whether the AST actually backs it up.
• Importance tiers — top 10% by fan-in are "hot" (changing them ripples), the next 15% are "core", everything else is "leaf" (safe to refactor).

That's it. No probability scores. No interventional / counterfactual edges. We ship the parts that produce a useful graph today and skip the parts we haven't earned yet.

Why it actually helps

When Claude Code asks affected_tests instead of grepping for test files, it gets back exactly the tests that depend on the changed nodes — usually 3 instead of 300. When it asks blast_radius, it gets the actual reverse-reachable set. The agent stops re-discovering structure on every turn and starts reasoning about it.

That's the whole pitch. The math behind why graph-aware retrieval helps multi-hop QA is in HippoRAG (2024); the case for graph-guided code localization is in LocAgent (2025) and RepoGraph (2025). We borrow the conclusion: graphs work better than flat retrieval. We don't reproduce the proof here — read the papers if you want it.