using-codemap

For structural code questions — who calls X, what breaks if I change Y, where do I start reading, what tests cover this — reach for codemap before grep or opening files: if answering would mean reading more than 2 files, call codemap_context (or codemap_context_batch) first. codemap is a precomputed code graph fused with semantic search, exposed as codemap_context, codemap_impact and friends over MCP (and as codemap … --json on the CLI).

Map the loop to the tools:

• orient on a repo -> codemap_read_order (entrypoints + hubs, ranked)
• locate -> codemap_semantic (by meaning) · codemap_find (by name) · codemap_grep (exact text: a literal, error string, route, env var) · codemap_explore (fuzzy intent → oriented structure)
• resolve a file:line -> codemap_symbol_at (a stack trace / diff hunk / grep hit → a selector; batch positions:[…] for a whole trace)
• orient on a file -> codemap_file_context (symbol outline + file impact + related files in one call)
• understand -> codemap_context, codemap_impact, codemap_source
• before a risky edit -> codemap_risk, codemap_file_impact, codemap_dependencies, codemap_related_files
• after every edit -> codemap_review (it names the tests to run and folds one risk band)
• calibrate trust -> codemap_coverage (per-file precise call-graph coverage)

Trust the honesty signals on every result: stale (reindex first), call_graph (resolved/name/unresolved/none), resolution, and the *_total caps. When a name is ambiguous the response already carries candidates:[…] and accepts a selector, so pick one definition from those instead of a second lookup. Prefer codemap_index --precise for exact call edges — it is also the only call graph for TypeScript, JavaScript and Python.

The workflow

Index once, then query. The typical agent loop for understanding or fixing code:

1. codemap index # build the graph (+ embeddings if Ollama is up)
2. where to start # codemap_read_order (entrypoints + hubs ranked — orient on a new repo)
3. find the entry point # codemap_semantic "" OR codemap_find # OR codemap_grep "" (string literal, error message, route, env-var) # codemap_explore "" (fuzzy goal → bounded context neighborhoods, source-light) # got a file:line? codemap_symbol_at : (batch positions:[…] resolves a whole trace)
4. orient on a symbol # codemap_context (def + callers + callees + tests + test_commands, ONE call) # codemap_context_batch … (several symbols at once + shared callers)
5. go deeper # codemap_impact (blast radius + runnable test_commands) · codemap_source (full body) # codemap_callers / codemap_callees (add precise:true on Go) # codemap_references (callback/RunE/registration value wiring; not callers)
6. before a risky change # codemap_risk (how careful?) # codemap_file_context (ONE call: symbol outline + file impact + related files) # codemap_dependencies (evidence only) · codemap_file_impact (evidence + blast/tests) # codemap_related_files (the other files structurally tied to this one)
7. trace flow # codemap_path (shortest call chain)
8. AFTER you edit # codemap_review (your diff → changed symbols, blast radius, the TESTS TO RUN)
9. survey # codemap_hotspots (hubs) · codemap_orphans (dead code)

Stay fresh: codemap_status returns a "stale" object (files changed/new/deleted since the last index) — normally codemap_index before trusting snapshot-based results. Its "precise" map is true per call-graph language only when every indexed file completed precise resolution at the last index; combine it with stale and each query's call_graph enum. Deletion review is the exception: codemap_review uses retained old definitions when available, emits deletion_analysis, and orders selected tests before the reindex that prunes them. (A registered-but-never-indexed project reports indexed:false — codemap_index first.)