How AI Coding Agents Actually Understand a Codebase

When people say an AI coding agent "understands" their codebase, they usually picture something like a mental model — a compressed sense of how the pieces fit. That is not what is happening. Under the hood, most agents explore a repository the same way a new hire with no map would: open a file, read it, open the next one it links to, read that, and keep going until enough of the picture is in context to answer the question.

That works. It is also where the tokens go.

Reading is not understanding

A large language model has no persistent memory of your project between turns. Every time it needs a fact about your code — where a function is defined, what calls it, which module owns a type — it has to get that fact into the prompt. The cheapest tool most agents have for that is "read this file." So they read.

The trouble is that a single question rarely maps to a single file. "Why does checkout fail for expired coupons?" might touch a route handler, a service, a validation helper, a shared type, and a test. The agent doesn't know that up front, so it discovers the graph by walking it — pulling whole files into context to find the three lines that matter.

The token math

Say the relevant logic is 40 lines spread across five files that average 300 lines each. To find those 40 lines by reading, the agent ingests ~1,500 lines. That is a 37× overhead on discovery alone, before it writes a single line of a fix. Multiply that across a working session — dozens of questions, each re-walking overlapping neighborhoods — and discovery, not generation, becomes the dominant cost.

The expensive part of agentic coding isn't the thinking. It's the looking.

What a map changes

A code map flips the default from read-to-find to look-up-to-find. Instead of crawling files, the agent queries a structure that already knows the shape of the repo:

• Symbols — every function, class, and type, with its exact path:line.
• Edges — who imports what, who calls what, who depends on whom.
• Ranking — which nodes are central (PageRank over the call graph) so the agent starts from what matters.

With that in place, "where is checkout validation" is a lookup that returns five path:line anchors and their immediate neighborhood — a few dozen lines — not a thousand-line read spree.

# Point an agent at the map over MCP, then it queries instead of crawling
npm install -g openvisio
openvisio serve

Why this matters beyond cost

Fewer tokens is the headline, but the quieter win is accuracy. An agent that starts from a ranked, structural view of the repo is far less likely to miss the one caller it never happened to open, or to "fix" a function while ignoring the three others that depend on its contract. Grounding the model in the real graph of your code is what turns a plausible-looking patch into a correct one.

That is the whole idea behind OpenVisio: parse the repository deterministically with tree-sitter, build the graph locally, and hand the agent a queryable map instead of a filesystem to grope through. No upload, no LLM in the indexing path, nothing leaves your machine.

Where the map still needs human judgment

A structural graph records what the parser can prove, not every fact that matters. Feature flags can disable a caller, configuration can select one implementation, and generated code can hide the boundary an engineer cares about. Business intent also lives outside the syntax tree. An agent should treat graph results as grounded evidence and still inspect tests, configuration, and nearby documentation before it changes behavior.

The healthiest workflow alternates between structure and source. Search the graph to locate the relevant neighborhood, read the small set of implementations that define the contract, then query dependents to validate the proposed scope. After the edit, run tests and inspect the diff. The map removes blind exploration; it does not replace verification.

You can tell this loop is working when the agent explains why each opened file is relevant. A session full of broad searches and repeated full-file reads suggests the retrieval layer is missing relationships or the task is underspecified. That signal is useful: improve the index, narrow the request, or ask for human context before spending more tokens on guesses.

How agents construct a working model

A capable agent usually cycles through orientation, localization, expansion, and verification. Orientation identifies the repository shape and likely subsystem. Localization finds the definitions closest to the request. Expansion follows callers, types, and tests until the relevant boundary is visible. Verification checks the proposed understanding against source and executable evidence. Skipping orientation creates noisy searches; skipping expansion creates locally plausible but incomplete patches; skipping verification turns assumptions into regressions.

Tool design can reinforce this cycle. Symbol search should return stable identities and locations. Relationship queries should distinguish direct evidence from inferred edges. Snippet tools should preserve enough surrounding code to understand contracts without returning entire files. Each response should make the next useful question obvious while keeping the agent aware of revision and coverage gaps.

Memory, summaries, and stale assumptions

Agents often summarize earlier reads to conserve context. That compression is useful, but a summary is not the source of truth. Attach paths, symbols, and revision metadata to important claims so the agent can revalidate them after edits or branch changes. Treat facts from prior sessions as hypotheses until the current repository confirms them. This is especially important for rapidly changing APIs and generated clients.

Good orchestration also separates repository facts from decisions. "Service A calls service B" can be derived; "we should preserve that boundary" is a design judgment. Keeping the two explicit helps reviewers challenge the recommendation without losing the evidence beneath it. An agent understands a codebase well enough to act when it can state the relevant structure, acknowledge what static analysis missed, and name the checks that will falsify its plan.

If your agent feels slow, expensive, or weirdly forgetful about code it read ten minutes ago, this is usually why — and a map is usually the fix.