Build a Repo Map for Code Navigation
Give your agent compressed, ranked codebase awareness - the tree-sitter repo-map pattern that beats raw file dumps.
The route
4 steps to Done
- 01
Extract symbols per file
The atom of the map is a signature, not a filename.
Preview prompt + verify gate ▾ Hide ▴
Build the extraction layer. Use tree-sitter (with the language grammars my repo needs) to parse each source file and extract: top-level functions and classes with full signatures, methods with signatures under their class, and export/visibility markers where the language has them. Store per-file digests: {path, language, symbols: [{kind, name, signature, line}], mtime, hash}. Skip vendored/generated directories via ignore rules. Handle parse failures gracefully (log, fall back to a names-only entry). Run extraction across the repo and spot-check 5 files: digests must match the code.
- ✓ Signatures include parameters and returns where present
- ✓ Ignore rules skip vendor/generated code
- ✓ Parse failures degrade, not crash
- 02
Rank by relevance
The budget goes to what the task touches.
Preview prompt + verify gate ▾ Hide ▴
Implement ranking to decide what the map shows. Signals to combine: TASK RELEVANCE - lexical/semantic match between the task description (and conversation so far) and file paths + symbol names; GRAPH CENTRALITY - files imported/referenced by many others rank higher (build a light import graph; a PageRank-style pass over it is the proven approach); RECENCY - recently edited or recently discussed files get a boost; CHAT MENTIONS - files already in the conversation rank highest. Output a scored file ordering per request. Test with three task descriptions against my repo and eyeball the top-10 per task - the relevant subsystem should dominate each list.
- ✓ Import-graph centrality computed
- ✓ Task text drives per-request scores
- ✓ Top-10 lists match human judgment
- 03
Render within budget
Graceful degradation: many files shallowly, top files deeply.
Preview prompt + verify gate ▾ Hide ▴
Build the budgeted renderer. Given the ranked files and a token budget (e.g. 1-2k tokens): allocate detail by rank - top files show full symbol listings, middle files show class/function names only, tail files show path only; render compactly (a tree-ish layout with signatures indented under paths); always include a header stating what the map is and that the agent should open files before editing. If even paths overflow, cut the tail and say so. Verify: render maps at 3 budgets (500, 1500, 4000 tokens) for the same task and confirm each is valid, useful, and within budget.
- ✓ Detail allocated by rank
- ✓ Header explains usage
- ✓ All three budget renders within limits
- 04
Integrate, cache, and prove navigation
The map earns its place by changing agent behavior.
Preview prompt + verify gate ▾ Hide ▴
Integrate and validate. INTEGRATION: include the rendered map in context for coding tasks (system section or first user turn); refresh the ranking per task. CACHING: cache digests by file hash - on file change, re-extract only changed files; the import graph updates incrementally; map render is cheap so re-render per request. PROOF: run the navigation benchmark - 5 feature/bug requests phrased without file names ('add rate limiting to the API layer'); compare with-map vs without-map on: correct-file-first-open rate, turns to first correct edit, and tokens spent exploring. The map must win clearly; where it does not, inspect whether ranking or rendering failed that case.
- ✓ Only changed files re-extract
- ✓ Benchmark shows faster correct-file location
- ✓ Losses diagnosed to ranking vs rendering
Research-backed