Giving my agent a map of the codebase (drawn partly from its own footsteps)

<p><em>Originally published at <a href="https://olund.dev/writing/code-map/" rel="noopener noreferrer">olund.dev</a>.</em></p> <p>Watch a coding agent land in an unfamiliar repository and you will see it do<br> what a new hire does on day one: grep for names, list directories, open<br> files, and slowly assemble a mental model. Unlike the hire, the agent does<br> this <em>every session</em>. The model it builds is discarded when the context<br> window closes, and the next session pays for it again - in tokens, in<br> latency, and in the wrong turns an incomplete picture produces.</p> <p>My fix is a per-project <strong>code map</strong>: a queryable navigation layer each<br> repository carries, rebuilt incrementally, that a new session receives a<br> digest of before it reads a single file. The interesting part is not that it<br> exists - static code intelligence is a mature field - but which three<br> signals it fuses, because the third one is something most tooling cannot<br> see at all.</p> <h2> Three signals, one map </h2> <p><strong>Structure</strong> is the conventional axis: symbols, calls, and imports parsed<br> with tree-sitter across whatever languages the repo mixes. This is<br> deliberately the shallow version of static analysis. Dedicated tools do<br> deep type resolution far better than I ever will, and competing with them<br> head-on would be a losing use of my time. Syntactic edges are good enough<br> for navigation, and the edge table records where each edge came from, so a<br> deeper per-language analyzer can add resolved edges later without a redesign.</p> <p><strong>Temporal</strong> comes from git: churn, ownership, and co-change - which files<br> historically change in the same commits. Parsed from plain <code>git log</code><br> output; no library dependency, and the repo's whole history is sitting<br> there with nothing better to do.</p> <p><strong>Behavioral</strong> is the differentiator. My memory system already records<br> every tool call an agent makes - every read, edit, and write, tagged with<br> project and session. Rolled up, that log yields a co-touch matrix: which<br> files did agents actually work on <em>together, in real sessions</em>. Editing<br> weighs more than reading in the rollup, because changing two files together<br> is stronger evidence of coupling than looking at them.</p> <p>The distinction between the axes matters in practice. The call graph tells<br> you A depends on B - true, and sometimes useless, because half of a<br> codebase depends on B. The behavioral signal tells you that in the last<br> thirty sessions, every time A changed, B and C changed too. Those are A's<br> <em>de facto</em> neighbors: the set you should have open when you touch it. Static<br> tools cannot compute this because they never see the work. Git co-change<br> approximates it but only at commit granularity, after the fact, and only<br> for changes - a session that read four files to safely edit a fifth leaves<br> no trace in git at all. The agent's own footsteps are the only place this<br> signal exists.</p> <h2> Cheap at session start, deep on demand </h2> <p>The map is consumed two ways, and the split is deliberate.</p> <p>The cheap path is a small rendered digest injected into every session's<br> context at start: the subsystems, a few key files each, one line of purpose,<br> ordered by community detection over the fused graph. On my main project<br> right now that is 913 files folded into 33 communities. One refinement<br> earns its keep daily: the digest's sections are <em>reordered by relevance to<br> the branch's current task</em>, which the session-start machinery already knows<br> from the pointer file described in the previous post. A session opening a<br> branch about upload quality-control sees the QC subsystem first, not an<br> alphabetical list.</p> <p>The deep path is a set of query tools the agent calls mid-session:<br> neighborhood (structural plus behavioral ne