using-codemap

Calling codemap

If codemap_* tools are in your tool list, use them. Otherwise run the CLI from the repository: every codemap_ below is codemap <tool> --json with underscores turned into dashes (codemap_file_impact is codemap file-impact --json), codemap_context_batch is codemap context <a> <b> --json, and the MCP path parameter is -C <dir>. If neither the tools nor the codemap binary are available, say so plainly instead of guessing: the one-time setup is to install codemap, then run codemap agent skill (this skill, for every detected harness) and optionally codemap agent setup <harness> (the MCP server).

Before the first question in a repository, check the index with codemap status --json. When registered is false, indexed is false, or nodes is 0, run codemap index; when a result says stale, reindex first. Check codemap coverage --json before trusting exact callers on a partly covered repo: status's per-language precise flag is all-or-nothing, while coverage is per file. Add --precise for exact TypeScript/JavaScript/Python call edges when its cost is justified and the language server is installed; for one symbol, prefer codemap_callers/codemap_callees with precise:true first.

If codemap_explore or codemap_task_context reports lexical mode or a semantic-owner error, semantic retrieval is unavailable, not empty: treat seeds as keyword/name matches and name the remediation from the error (for vecgrep, build its project index). If a helper is a nested arrow const or local closure that find/impact cannot address by bare name, resolve its file:line with codemap_symbol_at and work from the enclosing symbol.

CLI exit codes: 0 answered, 2 not found, 3 index missing, 6 a review/risk gate failed.

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 the only complete call graph for TypeScript and JavaScript (the default index has same-file and imported-binding candidates only) and the only call graph for Python. On a large, partly covered repo, scope trust with codemap_coverage and use one-off precise codemap_callers/codemap_callees for the symbol in question before paying for a full precise reindex.