DEV Community

Cover image for Stop letting your AI agent read whole files: a code map for Claude Code, Cursor and MCP

Stop letting your AI agent read whole files: a code map for Claude Code, Cursor and MCP

Makra Gergő on November 10, 2026

When an AI coding agent needs to change one method, it usually reads the whole file first. Then the next file. Then it greps, and reads a few more....
Collapse
 
itsvicmoreno profile image
Vic Moreno •

Agreed on where the tokens go: 412 lines read versus a 12-line outline is the right trade. The catch I'd watch is staleness, since once the agent edits OrderService mid-session the line ranges in the map drift. Does callgraph re-index on file change, or on each query?

Collapse
 
makra_gerg_8b963cb7a1cfd profile image
Makra Gergő •

Good catch — staleness is the first thing that bites with any code map. Both, actually:

  • Every query checks the files it touches (mtime + size) against the project map in .callgraph/ and re-analyses only what changed before answering. So if the agent edits OrderService and asks again, the next outline already has the new line ranges — no manual step.
  • The MCP server also watches the project and refreshes a changed file a moment after it's saved, so queries stay fast during a long session.
  • In Claude Code there's an optional hook that refreshes a file in the background right after the agent writes it, and callgraph.sh refresh does the whole project after a git pull.

A file with a syntax error mid-edit is still outlined up to the broken part, and the output says so ("⚠ syntax error at L…") instead of silently returning stale or empty results.

Collapse
 
itsvicmoreno profile image
Vic Moreno •

Checking mtime + size per query instead of a full rescan is the right trade. The one case it can miss: a restore that keeps timestamps (rsync -t, cp -p, tar) or a same-size rewrite inside the filesystem's 1 s granularity. Do you fall back to a content hash anywhere, or is the post-pull refresh enough in practice?

Thread Thread
 
makra_gerg_8b963cb7a1cfd profile image
Makra Gergő •

Fair point. Two details: the stamp is the nanosecond mtime plus size (on ext4, APFS and NTFS, so the 1 s window mostly doesn't apply), and there's no content hash yet — so a timestamp-preserving restore that keeps the same size is exactly the case it would miss. In practice that's rare in an agent session, and deleting .callgraph/ rebuilds the map quietly on the next query. A cheap content-hash check for files whose stamp matches but that were touched by a restore is a good idea — I've noted it.

Thread Thread
 
itsvicmoreno profile image
Vic Moreno •

Thanks, the nanosecond stamp settles the 1 s worry. One cheap step before a content hash: add ctime to the stamp, since cp -p, rsync -t and tar can put mtime back but setting it bumps ctime, which userland can't set back (Linux and macOS at least; on Windows ctime means creation time). Have you seen branch switches in big repos trigger a lot of re-analysis?

Thread Thread
 
itsvicmoreno profile image
Vic Moreno •

Thanks, the nanosecond stamp closes most of the gap I had in mind. For the restore case there may be an option cheaper than hashing: ctime. On ext4 and APFS the kernel sets it on every write or metadata change, and tools like cp -p or rsync -t can restore mtime but cannot set ctime, so storing it next to mtime and size flags those restores without reading the file. Would that fit how the stamp is stored today?

Collapse
 
makra_gerg_8b963cb7a1cfd profile image
Makra Gergő •

Thanks, everyone, for the comments. Several of these requests made it into callgraph v0.7.0, released today:

  • itsvicmoreno — the file stamp now includes ctime (on Linux and macOS), so a restore that keeps the mtime and the size (rsync -t, cp -p, tar) is now detected. Windows keeps mtime + size, since its ctime is the creation time. I left out a content hash for now, because ctime covers that case.
  • kolmopdf — signatures are in the outline: a --signatures flag prints the parameters and the return type on the method line (PHP, Rust, Swift, and TS/Vue now too), and the api view also shows the PHP DocBlock @return / @param shapes. Python and Go are on the list; they need a new language analyzer, so I won't promise a date yet.
  • liorbuilds — the "do-not-touch" list became a protect <pattern> line in .callgraphignore (e.g. protect migrations/): a protected file stays visible and searchable, but gets a 🔒 marker, and the agent instructions say to read it, not edit it.

Update with callgraph.sh update. If anything doesn't behave the way you expected, tell me.

Collapse
 
liorbuilds profile image
Lior •

The low-effort version that works for me is a short map file in the repo: one line per folder saying what lives there, plus where the shared helpers are. The agent reads that first and only opens the files it points to. Keeping it to a page matters, because a long map gets skimmed just like a long codebase.

Collapse
 
makra_gerg_8b963cb7a1cfd profile image
Makra Gergő •

That works well — and it's close to what callgraph.sh profile generates: about 15 lines with which folder holds which layer, the patterns in use and the call direction. The difference is it's computed from the code, so it can't drift when someone moves a folder and forgets the map file. A hand-written note on top (the "why" a folder exists) is still worth keeping.

Collapse
 
liorbuilds profile image
Lior •

Computed beats hand-written for the what, agreed. The part I'd still keep by hand is the short do-not-touch list: generated folders, vendored code, migrations that must never be edited. A code map can tell the agent where things live, but not which parts it should leave alone, and that's where most surprise edits come from.

Collapse
 
kolmopdf profile image
KolmoPDF •

Extracting an AST outline instead of dumping whole source files cuts token bloat dramatically. Where we see agents struggle with compact outlines is dynamic dispatch and generic repository wrappers: if an outline lists updateOrders() calling $orders->update(), the agent knows the call exists but lacks the parameter shape or return type.

Without that local contract in the outline, the model frequently guesses the payload structure before invoking --body. In our document ingestion and pipeline agents, pairing the method entry with its concise type signature (or DocBlock return shape) gives the agent enough context to decide if it even needs the method implementation.

Python and Go support would be great additions next, especially given how common AST inspection is across CLI tools and microservices.

Collapse
 
makra_gerg_8b963cb7a1cfd profile image
Makra Gergő •

Agreed — the call edge alone isn't enough to decide whether you need the body. Part of this already exists: --format api prints the full signature with parameter and return types for PHP, e.g. updateOrders(array $ids, OrderDto $dto, bool $notify = false): array L4, so the agent can check the contract without the body.

Two gaps you've made me notice: TypeScript return types aren't shown there yet, and a DocBlock @return array{...} shape isn't surfaced at all — both are going on the list, along with an option to put the compact signature right on the outline line. Python and Go are the most requested next languages; noted.