A codebase map for AI agents is a local index of a repo’s files, symbols, imports, tests and change history that an agent can query, so it finds the right code in a few calls instead of grepping and reading file after file. Fewer files read means less in the context window, and less in the context window means every later turn is cheaper.
This post covers why agents waste tokens on exploration, what a good map contains, and how AgentVera’s project map gives Claude Code, Codex and other CLI agents that index over MCP.
How agents explore a repo without a map
Give a coding agent a task like “add a coupon field to checkout” in an unfamiliar repo and it does what you would do with only a terminal:
grep -r "checkout"and get 200 hits- Open the files that look promising, often whole
- Follow imports by reading more files
- Search again for the test file
Each step pulls text into the context. A 1,000-line file read once is in the conversation for the rest of the session, and the model re-reads the conversation on every turn. If the first guesses were wrong, those files still sit there. This is one of the main reasons a session gets expensive long before the actual change is made. For the other big source, the baseline context, see cut Claude Code token usage.
What a useful codebase map contains
A file list is not enough. An agent needs to answer “where” and “what breaks if I change this” without reading code. A good map holds:
| Layer | Answers |
|---|---|
| Files and modules | What is in this repo and how is it laid out? |
| Symbols with signatures | Where is applyCoupon and what does it take? |
| Imports | Who uses this file, and who uses those? |
| Linked tests | Which tests cover this code? |
| Change-together history | Which files usually change with this one? |
| Entry points and test command | Where does it start and how do I run the tests? |
The last two matter more than they look. Git history knows that checkout.ts and checkout.test.ts and pricing.ts tend to change in the same commit, even when no import links them.
How AgentVera’s project map is built
AgentVera builds a project map for each project folder:
- Symbols. tree-sitter reads functions, classes, methods, interfaces, types, enums and constants with line ranges, signatures and the first sentence of the doc comment, for TypeScript, TSX, JavaScript, Python and Go. About 30 more languages are indexed by path.
- Imports and tests. Imports are resolved to files, and tests are linked to the code they cover.
- Change-together. Files that changed together in at least 2 of the last 500 commits are linked. Commits that touch more than 40 files are ignored, so a big rename does not link everything to everything.
- What it skips. It starts from
git ls-filesand respects.gitignore. It skipsnode_modules,dist,build, files over 1 MB and generated or minified files. In repos with more than 20,000 files it only indexes source folders such assrc,lib,appandpackages/*/src.
The map is built on your computer and costs no tokens. It watches file changes, recounts change-together history when commits land, and re-checks a file when an agent asks about it. One map per folder is shared by all agents working there, so a project and each of its worktrees have their own. It is stored compressed in the app’s data folder.
The MCP tools agents use
AgentVera adds an MCP server named agentvera-map to each agent. Its instructions tell the agent to start a task with map_related, use map_outline before reading a file and map_usages before changing code.
| Tool | Returns |
|---|---|
map_related | Files a task likely involves, ranked, with reasons (name match, imports, changed together, tests) |
map_outline | A file’s symbols with line ranges and signatures, its imports, importers and tests |
map_usages | Who calls or imports a symbol or file, at depth 2 importers of importers, plus covering tests |
map_find | Symbols or files by fuzzy name, with kind, file:line and signature |
map_overview | Modules, sizes, entry points and the test command |
map_api | The real exported API of an installed package, at the version in node_modules, from its type declarations |
map_related takes a task in plain words, in any language. Turkish words like sepet, kupon or ödeme match English code names such as cart, coupon and payment.
map_api fixes a quiet source of bugs: an agent writing calls from memory for a library version you do not have. It reads the .d.ts files of the version that is actually installed.
New agents also get a short summary of the modules, entry points and test command in their instructions, so they do not spend the first turns finding out how to run the tests.
Before and after: the same task
Here is how the coupon task changes. The steps are typical, not a benchmark.
Without a map:
grep -rn "checkout" src # 200 lines of hits
cat src/checkout/index.ts # whole file
cat src/checkout/summary.tsx # whole file, not the right one
cat src/pricing/total.ts # whole file
grep -rn "total(" src test # find callers and testsWith the map:
map_related "add a coupon field to checkout"
-> src/pricing/total.ts (name match, changed together with checkout)
-> src/checkout/CheckoutForm.tsx (imports total.ts)
-> test/pricing/total.test.ts (test)
map_outline src/pricing/total.ts # symbols and lines only
map_usages calculateTotal # callers and testsThen the agent reads only the lines it needs. The first version fills the context with files it did not need; the second fills it with a ranked list and an outline.
Smart tools: when the agent reads anyway
Agents do not always ask the map first. For Claude Code, AgentVera’s smart tools use hooks to step in:
- The first full read of a file over 800 lines and 24 KB returns the outline from the project map instead, so the agent can read the part it needs.
- Repeat reads of a file that has not changed are blocked, since the content is already in context.
- Test runs are narrowed to the tests that matter.
If you want to see how hooks work in general, read the Claude Code hooks guide.
Turning the map on and off
The project map is on by default and part of the free plan.
- Open Settings → Token savings and find the Project map switch. It is on unless you turned it off.
- To leave one agent without it, clear its Project map box in the agent edit dialog.
- To see the map, open the project’s Details page and the Project map tab. It draws a graph with imports in grey and change-together links as dashed orange lines. Type a task and press Show to see what
map_relatedwould return.
If the map is not ready yet, for example right after opening a large repo, the tools answer with the build progress. The agent waits a few seconds and then falls back to its normal tools.
Does it actually save tokens?
The honest answer is: it depends on the repo and the task. A small repo where the agent already knows where to look gains little. A large or unfamiliar repo, where an agent would otherwise read a dozen wrong files, gains a lot.
Rather than trust a number, measure it on your own work. The AI ROI tab has a Project map impact card that compares conversations with and without the map by success, first-time pass, tokens per task and follow-ups.
Limits to know
- Symbol detail is for TypeScript, TSX, JavaScript, Python and Go. Other languages get path-level indexing.
- Agents on a remote SSH host do not get the map.
- An agent reads only the map of its own folder, so a worktree agent sees its worktree, not the main checkout.
- The code map window in AgentVera’s project tour is a separate feature for you to explore the code; the project map is what agents query.
Summary
A codebase map for AI agents replaces blind grep-and-read exploration with a few targeted questions: which files, which symbols, who uses them and which tests cover them. AgentVera’s project map builds that index locally with tree-sitter and git, keeps it fresh, and gives it to every MCP-capable agent through agentvera-map, while smart tools catch large and repeated reads in Claude Code. Pair it with a shared project memory so agents know both where code is and why it is that way, and download AgentVera to try it on your largest repo.