The Codebase Graph as a Two-Way Dashboard for Human and Agent Actions

An interactive codebase graph for AI agent steering must be a two-way control surface. It gives agents an up-to-date structural map to plan changes and lets engineers set constraints, check what the changes do, and enforce boundaries. The codebase graph lets those activities share one model, from the first planning query to the merge gate.

Why a codebase graph is not a visualization and what it needs to be instead

A developer staring at a diagram while an agent is already three commits into a refactor has an observation tool. The diagram may describe the repository clearly, but it cannot direct work if its state never reaches the agent. A static picture falls out of date as the code changes. When agents touch dozens of files autonomously, that gap separates the architecture engineers believe they have from the structure being built.

A control surface gives the model an operational role. Agents read it to understand dependencies and plan changes, while engineers write constraints that define where that work may go. The distinction is whether the graph participates in decisions. An impressive node cloud without that connection remains an artifact to inspect after the consequential choices have been made.

Why agents need structural context that vector search cannot give them

Without structural context, an agent repeatedly lists files, searches keywords, opens likely matches, and infers ownership and dependencies. It then edits code and may discover a dependency that changes the plan. Vector similarity search can retrieve semantically related text, but similarity does not establish a transitive dependency, a call chain, or a layer crossing. A change that looks sound on its own can then break a distant boundary that never appeared in what the agent retrieved.

A graph lets the agent retrieve the relevant call chain, downstream dependents, or architectural boundary instead of reconstructing those relationships from whole files. CodeGraph demonstrated substantial reductions in token usage and tool calls in benchmarks across seven open-source codebases, including VS Code with approximately 10k files and Django. Its largest gains came on the most complex repositories. Because large codebases exceed any context window, the key question is not whether the agent reads everything, but how it decides what to read.

What a graph must expose for agents to act on it deliberately

A useful graph answers questions shaped by the task. During planning, it identifies the files that define a behavior, neighboring modules that supply preferred patterns, and dependencies flowing into and out of the proposed change. During editing, it distinguishes locally changeable symbols from interfaces with callers that need updates, and generated files from files open to hand edits. Review requires a different view of the same relationships. Downstream paths, tests that apply, and incident or migration notes that bear on the change help show what it would affect.

Those answers need explicit provenance. An edge labeled EXTRACTED comes directly from code, while INFERRED identifies a relationship derived from names or call paths, and AMBIGUOUS marks unresolved interpretation. These labels prevent inference from masquerading as fact. Commit identity, timestamps, and content hashes also establish whether the graph describes the source revision the agent is editing. Without them, even a correctly extracted relationship may be out of date.

Understand-Anything illustrates a useful separation between deterministic parsing for structural facts and LLM analysis for summaries and architectural-layer labels. It keeps deterministic work in scripts and semantic work in LLM agents. A control surface that engineers can trust must also encode authorization boundaries, including modules, interfaces, and layers that the agent is barred from changing.

How do you give an AI coding agent a real-time map throughout its session?

A graph read once at setup cannot show changes made later in a long autonomous session. As the agent edits dependencies or callers, its initial planning context can become stale through its own actions. The next query must reflect those edits. Otherwise, the agent reasons about a structure it has already replaced, even if the original map was accurate.

CodeGraph uses a file watcher to keep its local SQLite-backed graph current as code changes. This supplies the continuous-update pattern that a session-long structural map needs without requiring the agent to reconstruct the repository each time. Cognee covers another part of this work with a knowledge graph that agents can query, read, and write through an API. These capabilities serve related but distinct purposes. Updating the structure drawn from source keeps the map current, while writable memory gives agents a place in the shared model to save what they learn.

For orchestration, the requirement is a closed feedback loop. After an edit changes the indexed structure, the next planning query must return a subgraph reflecting that change and the constraints still in force.

The engineer's side of the same interface: observing and constraining agent work on the graph

Archeyes describes itself as “Bidirectional plan diagrams for AI coding agents — the diagram is an input device.” That formulation gives the engineer an active role. Editing the diagram expresses intent that becomes an operating constraint for the agent, rather than a separate illustration of what the engineer hoped would happen. The same structural model can then expose whether the resulting code followed that intent.

A diff shows changed lines. A graph can instead expose a new dependency between modules, a layer crossing, or a cycle introduced across several files. Understand-Anything provides /understand-diff to show which parts of the system a change affects. CodeGraph has blast-radius and call-chain analysis to trace the functions and dependencies that a change touches. These are concrete ways to translate code edits into structural impact before they land.

Archeyes takes visual intent as input, while the other examples show what a change affects or help agents find their way through the structure. The engineer needs both directions of that interface. Steering without observation cannot establish whether the agent complied, and observation without constraints leaves the engineer reacting to decisions already made.

Why the graph must move into CI to be enforceable, not just visible

A displayed constraint does not, by itself, block a merge. Enforcement requires a CI check that exits non-zero when the proposed code violates a defined rule. A directed dependency graph supplies the substrate for those checks, with modules as nodes and dependencies as edges. Prohibited edges, layer crossings, cycles, and improper module placement can then be evaluated as graph queries.

That check must use the exact source revision under test. A stale committed graph describes an earlier state, so it cannot show whether the proposed code obeys the rule. Repository-versioned constraints and a current source-derived graph therefore serve different purposes. The constraints keep the intended architecture in place, while the graph shows what the build is actually checking. Mechanical violations can then be blocked without asking a reviewer to rediscover them in a diff.

Meta’s RADAR system shows how automated review can work at scale in a diff pipeline, having reviewed and landed hundreds of thousands of diffs. Its production incident rate for reviewed diffs was 1/50 that of non-RADAR diffs. RADAR is a risk-based review system. Its eligibility gates, risk scoring, automated review, and deterministic validation support the broader case for decisions before landing, but the result does not establish that graph checks caused the safety difference. Routing lower-risk changes into automation also affects that comparison.

What breaks when the graph is absent: agentic drift and the architecture that disappears

Agentic drift is the gradual departure from a developer’s original intent across a long agent session. Small changes that each look sound can add unwanted dependencies, collapse layer boundaries, and move the implementation away from its intended design. Line-level review does not directly compare architecture with intent. A structural comparison makes that departure visible as changed relationships rather than requiring a reviewer to infer it from scattered edits.

Meta’s production data shows that significant lines of code per human-landed diff rose by 105.9% year over year, and the number of diffs per developer also rose sharply. Meta attributed most of that increase to agentic AI assistance and reported a declining share of diffs receiving timely human review. More code was reaching a constrained review process. CodeRabbit’s research also reports a higher vulnerability rate in AI-generated code than in human-written code, so structural review carries the added pressure of security concerns. That concern strengthens the need for supervision without making dependency checks a substitute for security review.

A graph with intent, timestamps, change ancestry, and commit identity can expose drift by comparing the intended structure with the current one. The comparison identifies new edges and violated constraints. This is why the model and its constraints need to live with the repository and version with the code, while the source-derived index stays current. A slide deck has no equivalent mechanism for detecting divergence.

The limits of the graph: what it cannot verify and where human judgment stays necessary

Graph checks establish structural compliance. They can detect a prohibited dependency, layer crossing, or cycle because each has a defined condition. They cannot tell whether a permitted change uses the right abstraction or makes a sound architectural tradeoff. A technically passing diff may still contribute to an unmaintainable design. Structural consistency also leaves open whether the code matches the product intent behind the developer’s prompt.

Human judgment remains necessary at that boundary. Architecture decisions, security judgment, and consequential tradeoffs require understanding why a constraint exists. The routing limitation of automated review reinforces this division, because results from eligible lower-risk changes do not establish safety for excluded high-stakes work.

Graph tooling also has an overhead to justify. For mid-sized repositories, brute-force navigation and grep-style search can still be faster than graph traversal while the tools mature. The strongest case arises when structural blindness is the binding constraint. A graph is not automatically the best retrieval mechanism simply because it offers a richer representation.

How to put the two-way model into practice: mapping, steering, and enforcing in one workflow

The practical workflow begins by mapping the current source revision into a directed graph of modules, files, classes, functions, and call relationships. A file watcher or incremental update hook must keep that index up to date for the whole session. A committed snapshot alone is not sufficient. The repository should preserve the model’s constraints and provenance while the live index reflects ongoing edits.

Engineers then express scope and intent on that model, marking off-limits modules, stable interfaces, and layer boundaries that may not be crossed. The agent queries the relevant subgraph to plan within those rules rather than inferring the architecture from the file tree. Visual input, current structural retrieval, and explicit constraints are the selection criteria illustrated by Archeyes, CodeGraph, and Understand-Anything. Those examples do not establish that any one product supplies the complete workflow.

After the agent acts, the engineer uses blast-radius and call-chain views to check new edges, changed dependencies, and places where the code may cross layers. CI then regenerates the dependency graph from the exact source under test and blocks defined violations before merge.