Skip to content

MCP server ​

codemap is a stdio Model Context Protocol server, so AI agents can query your code graph directly instead of reading dozens of files. This page is the full tool reference — for registering codemap in one command with a playbook included, see codemap for agents; for the order to call these tools in, see the agent loop. Tool text payloads use compact JSON to avoid spending context tokens on indentation; the structured result fields are identical to CLI --json reports.

For SQL/sqlc, YAML, Markdown, and HTML/CSS, start with Data, configuration, and documentation. Use dependencies for inbound evidence and traverse for typed relationships. These formats do not gain function calls from --precise. The same guide is available through codemap docs formats and codemap_docs with topic: "formats". MCP traverse requires the full profile.

Register it ​

Install codemap (brew install abdul-hamid-achik/tap/codemap, or go install github.com/abdul-hamid-achik/codemap/cmd/codemap@latest), then register codemap serve with your agent. Most CLIs have a one-liner:

Claude Code

bash
claude mcp add codemap -- codemap serve        # add --scope user to share across all projects

OpenAI Codex

bash
codex mcp add codemap -- codemap serve

GitHub Copilot CLI

bash
copilot mcp add codemap -- codemap serve

Any other MCP client — add a stdio server to its config (the key may be mcpServers, mcp, or context_servers depending on the client):

json
{
  "mcpServers": {
    "codemap": { "command": "codemap", "args": ["serve"] }
  }
}

Once connected, an agent can call codemap_docs to learn the tools and the index → understand → read workflow on its own.

Tool profiles ​

By default codemap serve registers all 50 tools. That's a real cost: a hermetic benchmark measured +95% input tokens on the codemap arm, driven by every tool's schema riding in every session's context — and some clients (Cursor) cap total MCP tools at ~40 across all servers combined, so a full codemap registration can crowd out every other server.

Set CODEMAP_MCP_PROFILE=agent (env), mcp.profile: agent (codemap.yaml), or pass --profile agent to codemap serve for the exact 28-tool surface derived from the canonical taught workflow: the 27 tools it names plus codemap_docs for self-discovery. The shipped core profile remains compatible and currently has the same 28-tool inventory; its contract stays stable while agent is pinned to what the playbook actually teaches. full remains the default for backwards compatibility and is the explicit expert/admin surface.

codemap_index, codemap_status, codemap_docs, codemap_read_order, codemap_semantic, codemap_find, codemap_grep, codemap_context, codemap_context_batch, codemap_impact, codemap_source, codemap_callers, codemap_callees, codemap_references, codemap_risk, codemap_dependencies, codemap_file_impact, codemap_file_context, codemap_review, codemap_path, codemap_hotspots, codemap_orphans, codemap_coverage, codemap_explore, codemap_symbol_at, codemap_related_files, codemap_features, codemap_flow.

The current offline microbenchmark drives real tools/list calls through the Go MCP SDK's in-memory transport, with no model, network, embeddings, or language server. On an Apple M5 over 100 iterations, agent/core each serialize 36,705 schema characters (≈9,177 tokens using the declared chars/4 planning estimate); full serializes 57,809 characters (≈14,453 estimated tokens). That is about 37% less schema context for the taught surface. Reproduce it with:

bash
go test ./internal/mcp -run '^$' -bench '^BenchmarkProfileSchemaTax$' -benchtime=100x -benchmem

Everything else — codemap_init, codemap_doctor, codemap_projects, codemap_symbols, codemap_refactor_plan, codemap_secret_impact, codemap_required_keys, codemap_annotate / codemap_annotations / codemap_unannotate, codemap_branch_status / codemap_branch_switch, and codemap_cache_save / codemap_cache_restore / codemap_cache_list / codemap_cache_drop, plus the full-profile orientation surfaces codemap_map, codemap_atlas, codemap_traverse, codemap_task_context, and codemap_affected — is admin/ecosystem/extended surface, available under the default full profile and excluded from both current lean profiles. Precedence is the same three-way order as every other codemap setting: config file < environment < CLI flag. An unrecognized value is a startup error, not a silent fallback. codemap agent setup cursor defaults its generated .cursor/mcp.json entry to CODEMAP_MCP_PROFILE=core for exactly this reason; every other harness stays on full since only Cursor has the tool-count ceiling.

Tools ​

Project-scoped tools take an optional path (the project directory; defaults to the server's working directory) and return JSON. Global helpers such as codemap_projects, codemap_docs, and codemap_doctor do not need a project path.

ToolDescription
codemap_initRegister a project directory
codemap_indexIndex/reindex a project (reindex, no_embed, precise → exact call edges via go/types for Go and LSP callHierarchy for TypeScript/JavaScript/Python; Vue remains symbols + imports only). Base TS/JS indexing already carries name-based import, JSX component-usage, Next.js framework-wiring, same-file call, and imported-binding call edges; Ruby and Lua index name-based with no server
codemap_statusIndex statistics plus freshness — a stale count of files changed/added/removed since indexing, so an agent reindexes before trusting results. The health call skips the local vector-store count (vectors_known:false) to stay bounded; use the CLI's explicit codemap status --full for that diagnostic
codemap_doctorCheck the environment (go toolchain, gopls, TS/JS + Python language servers, Ollama) with install hints — diagnose why a language isn't indexed or semantic search is off
codemap_semanticSemantic search by meaning (query, top_k). Adaptively balances the vector/BM25 hybrid-search fusion by query shape — an identifier-looking query leans BM25, a natural-language question leans vector — and reports the chosen profile as fusion (identifier/natural_language/balanced). Set semantic.fusion: balanced (or CODEMAP_SEMANTIC_FUSION=balanced) on the server for exact equal weighting
codemap_callersFunctions/methods that call a symbol (precise: true → language-server resolution; selector → one exact definition). Carries a stable call_graph enum (resolved/name/unresolved/none)
codemap_calleesFunctions/methods a symbol calls; accepts the same precise and exact selector inputs. Same call_graph enum
codemap_referencesPlaces a function/method is used as a value rather than called (callbacks, handlers, registrations — and, for TS/JS, Next.js framework wiring). Accepts an exact selector; returns capped source sites with totals plus independent coverage and confirmed/candidate confidence. Coverage is partial and name fan-out remains candidate, so an empty result is not proof of no runtime wiring.
codemap_impactCallers + blast radius + covering tests + test_commands (copy/paste-ready runner invocations derived from those tests, same derivation as codemap_review) (depth). selector scopes all traversal to one definition. Also returns buckets (blast radius grouped into depth-1 direct and depth-2+ transitive nodes, the counts are always true totals; the flat blast_radius is unchanged; a budget or task_context's cap rebuilds the lists from the kept blast_radius prefix only), blast_radius_total (the true size before any trimming), and a per-node confidence (confirmed = every edge on a shortest path is precise, or a same-file name edge whose target symbol is unique in its file; candidate = name-based cross-file fan-out or a heuristic test). min_confidence:"confirmed" drops candidate nodes from blast_radius/buckets/tests/direct_callers and reports the dropped count as filtered:{candidate:N}; the default (candidate) changes nothing. Carries call_graph alongside the human resolution note — unresolved means callers/blast/tests are unknown, not absent (for example, uncovered TS/JS/Python definitions or Vue, whose call graph is not supported yet). Optional max_tokens bounds the payload (see Response token budgets)
codemap_reviewDiff-scoped impact + test selection — maps a working/staged/since diff to changed symbols, blast_radius, covering_tests, test_commands, aggregate risk, confidence, and bounded next actions. analysis_complete plus total/analyzed/truncated counts and bounded partial_errors prevent stale, capped, or partially failed analysis from looking authoritative; structural-source mapping errors include failed symbol lookup, deletion-only hunks, recognized callable/type declaration lines removed in mixed or equal-count hunks, and exact source renames with no mapped symbols. Documentation/assets remain visible in changed_files without structural mapping failures. Fresh indexed untracked source files and exact source renames map as whole files. Incomplete analysis forces risk.level:"unknown". The additive coverage block (verdict covered/partial/uncovered/unknown plus covered_symbols/uncovered_symbols/unknown_symbols) answers "is each changed symbol tested?" separately from risk: a changed or new test file in the same diff whose code references a uniquely named changed symbol counts toward coverage only (never untested_symbols, risk, or the untested gate), and unknown (unresolved call graph and no test link) is never evidence of missing tests. gate.would_fail_on.uncovered is the report-level form of CLI --fail-on-uncovered. Nodes carry confidence as on codemap_impact. Deleted source files are analyzed from retained last-index definitions when available; deletion_analysis reports completeness and test actions precede reindexing.
codemap_affectedChanged files → the test files to run (full profile). Inputs: files (project-relative; absolute paths under the root accepted), since / staged (take the git diff; with no inputs the whole working tree is used), filter (glob over the reported test paths), depth (call-graph and import hops, default 3, max 10; out of range is rejected, not clamped). since and staged are mutually exclusive; both, a bad depth, or a since ref that does not exist return an invalid_input error, and a git-sourced run outside a git repository returns not_a_repo. Returns schema_version: 1, files, sorted unique tests each with reasons (covers:<symbol>, imports:<file>, changed), unmapped, deleted_tests (changed test files that no longer exist, never in tests), call_graph (weakest confidence among contributing symbols), analysis_complete (staleness/caps/failures only), stale, and a note whenever coverage is name-based, unresolved or absent, so an empty list is never silent. Lighter than codemap_review when only the test list is needed.
codemap_dependenciesDirect inbound dependency evidence for a file, grouped and capped by dependent file and calls/references/imports. Every sample carries confidence/confidence_reason; confirmed/candidate totals, file-vs-package scope, truncation, freshness/call_graph, and domain coverage stay explicit.
codemap_file_impactFile-level impact — returns confidence-aware dependency_evidence, blast/tests, and a conservative delete_verdict. Only fresh confirmed file-scoped evidence proves unsafe; name-fanout candidates, stale snapshots, Go package imports, and missing evidence remain unknown. Legacy safe_to_delete stays false.
codemap_required_keysLeast-privilege key set — for an entrypoint, the candidate secret key NAMES its transitive call tree actually reads. Supply keys directly or use via_vault plus optional prefix; operates on names only, never values. Candidate input is capped at 256 unique names, 256 bytes per name
codemap_secret_impactSecret-key rotation blast radius — for each key NAME, the symbols that read it (os.Getenv/os.environ/process.env), the transitive callers affected, and covering tests (untested:true warns a key no test reaches). Operates on key NAMES only — never reads/returns values. Pairs with tinyvault; via_vault fetches names from it. Each request is capped at 256 unique names, 256 bytes per name. Name-based unless the index is --precise
codemap_hotspotsMost-referenced symbols (top), ranked by effective_in_degree (precise callers plus name-based callers divided by the number of same-named definitions). Test code is ignored unless include_tests is true. Carries project-wide call_graph/resolution so incomplete rankings are explicit
codemap_riskChange-risk score for a symbol or exact selector — untested coverage + fan-in + cross-package spread + name ambiguity combined into a 0..1 score + level (unknown/low/medium/high), with the factors behind it. An unavailable call graph is unknown, never a reassuring low
codemap_orphansDead-code candidates (top), with project-wide call_graph/resolution so an unresolved graph never reads as proven dead code
codemap_coveragePer-file precise call-graph coverage — rollups by language/directory (worst-covered first) always included; prefix/language/uncovered filters or files:true add the bounded per-file list (top, default/max 200/2000; files_total/files_truncated disclose the real count). Each file reports resolver/resolved_at/stale. Complements the per-query call_graph enum — use it to calibrate trust per package before asking a symbol question.
codemap_read_orderWhere to start reading — ranks entrypoints (main() and functions wired by value such as handlers, module index files, exported API) + call-graph hubs into a reading guide, each with a reason and score. Tests are ignored unless include_tests is true. Optional query narrows it. Run on first contact with an unfamiliar repo, then drill the top entries with codemap_context
codemap_atlasThe repo as a described directory/file tree (full profile) — per node: files, symbols, lines, tests, roles (source/tests/docs/config/entrypoint/examples/bench/generated/vendor), a summary with summary_source (README first paragraph, Go package doc, Python module docstring, leading file comment, Markdown; extracted, never generated), key symbols with durable selectors, inbound/outbound/internal coupling, and top neighbours. Inputs: prefix (zoom into a directory), depth (default 2, max 8), files (include file leaves), max_nodes (default 1500, max 20000), key_symbols (default 5, max 20). Carries schema_version: 1, call_graph, resolution, stale, truncated, and partial_errors.
codemap_featuresCapability inventory (agent, core, and full profiles) — what the software can do and where each capability lives: program, cli_command, rpc_tool, http_route, api_route, and page features, each with label, invocation, description (from the registration or a docstring), handler with durable selector (null for inline handlers), parent for nested CLI commands, and a bounded call footprint (symbols, files, subsystems, feature-specific tests, ambiguous_edges). Go registrations are read from the syntax tree (confidence: confirmed); TS/JS and Python are pattern-detected (candidate). Inputs: kind (comma-separated), query, top (default 200, max 2000), depth (default 3, max 6), no_footprint. Ruby, Lua, and GDScript detection is not implemented and notes says so. Pass a handler selector to codemap_flow or codemap_context.
codemap_processesExecution flows from every entry point (full profile) — for each CLI command, HTTP route, MCP/RPC tool, page, or program with a resolved handler, the chain of definitions it reaches in call order: id (kind:name), kind, name, entry selector, steps[{symbol,fqn,kind,file,start_line,depth}], files, truncated, call_graph, and partial_errors when its symbols live in unreadable source files (step order is then name order). Each definition appears once per process, at its first appearance in call order. Same-name fan-out is collapsed as in codemap_flow. Computed on demand from the stored graph; nothing is persisted. Inputs: kind (comma-separated), query (content words matched against the name and every step), top (default 50, max 200), depth (default 4, max 8), max_steps (default 40, max 200). Returns processes_total, entrypoints_total, evaluated (a query inspects at most the first 300 entry points; truncated is true when it could not inspect them all), truncated, call_graph, resolution, stale, notes, and partial_errors. Pass an entry selector to codemap_flow for the full annotated tree.
codemap_flowHow one feature works (agent, core, and full profiles) — a bounded call tree from one entry, given as symbol or exact selector, in the order the code calls things. Each step carries file:line, subsystem, signature, one-line doc, and confirmed/candidate confidence. Same-name fan-out on a name-based graph is collapsed to the most plausible definition (alternatives) or left as an unexpanded leaf_reason: "ambiguous" step with candidates; precise edges are never collapsed. Repeats, cycles, and depth or node cuts are explicit. Inputs: depth (default 4, max 8), max_nodes (default 120, max 1000), include_tests.
codemap_mapArchitecture overview (full profile) — bounded source-path subsystems, directed cross-subsystem bridges with edge type/provenance, likely entrypoints, and hubs. Test code is excluded from bridges, subsystem edge counts, and hubs (tests_excluded: true). Independent top_subsystems/top_bridges/top_hubs/top_entrypoints caps; response carries totals/truncation plus freshness and call-graph honesty.
codemap_exploreIntent to exact neighborhoods — accepts query plus bounded seeds, edges, and depth; searches semantically when embeddings exist (otherwise name search, topped up by a BM25 lexical floor over names, paths, and docs — search_mode name, lexical, or name+lexical), joins usable hits to durable selectors, and returns compact context neighborhoods without source bodies. Limits: seeds 1–10, edges per context 1–20, depth 1–10. Unjoined hits and optional failures remain explicit. The result also carries processes (up to 3): entry-point flows whose steps contain a joined seed (id, kind, name, entry, matched_seeds, call-order steps capped at 8, call_graph), empty when the project has no detected entry points or no flow reaches a seed. codemap_task_context embeds the same field in its explore section. Optional max_tokens bounds the payload (see Response token budgets).
codemap_task_contextMode-scoped task orientation (full profile) — one call that composes freshness, explore neighbourhoods, brief contexts, impact drill-downs, and related files for a task, with mode understand, change, or debug (and optional selectors) (schema codemap.task-context.v1). The task text is the retrieval query verbatim. Optional max_tokens bounds the payload (see Response token budgets).
codemap_traverseTyped heterogeneous graph walk (full profile) — requires selector:{file,start_line,fqn,kind} and never accepts an ambiguous name union. direction is outgoing, incoming, or both; edge_types is a list drawn from calls, references, imports, implements, overrides, depends_on, tests, and defines; depth is 1–10 and limit is 1–500 nodes. Each hop returns durable child/parent selectors, edge provenance, and confirmed/candidate confidence; the report is cycle-safe, bounded, and exposes truncation/domain totals.
codemap_pathShortest call path (from, to, or paired from_selector/to_selector), with endpoint-scoped call_graph/resolution distinguishing disconnected from unresolved. Unique FQNs are exact endpoints too
codemap_related_filesFiles structurally related to a file via the call/test graph — its callers', callees', and covering-test files, each with a reason (caller/callee/test) and confidence. Graph-accurate alternative to import-text heuristics
codemap_symbolsList the symbols defined in a file (structured alternative to reading it)
codemap_symbol_atResolve a file:line position to its enclosing symbol (FQN, kind, range) — join external file:line results (search hits, stack traces, diffs) onto the graph. resolution is exact/enclosing/none. The indexed field is false when the project hasn't been indexed yet, so an agent knows to call codemap_index before concluding "no symbol". Pass positions:[{file,line}] instead of file/line to resolve several positions — e.g. every frame of a pasted stack trace — in one call (up to 25; each self-reports its own resolution)
codemap_findFind symbols by name (offline; no embeddings). In no-Ollama/structure-only degraded mode it tokenizes the query on whitespace/camelCase and matches symbol/FQN or docstring; each hit carries matched_in ("symbol", "fqn", or "docstring") explaining the match
codemap_grepExact text search (pattern, regex, ignore_case, top) over indexed file content — each hit resolved to its enclosing symbol (symbol/fqn/kind/selector). Offline, no embeddings. Distinct from codemap_semantic (meaning) and codemap_find (name)
codemap_sourceReturn source code by symbol, or exactly one body by selector. brief:true drops each match's source (keeping signature/doc/location) and sets source_omitted:true
codemap_contextEverything about a symbol in one call — definition (with source), callers, callees, value-reference wiring, covering tests + test_commands, blast-radius size, and annotations. selector keeps the full bundle on one definition; lists are capped with *_total counts (test_commands is derived from the full, uncapped test list). Uses the indexed graph only; optional component failures are explicit in partial_errors. brief:true drops each definition's source (keeping signature/doc/location) and sets source_omitted:true — everything else in the bundle is unchanged; follow up with codemap_source for the one body you actually need. Optional max_tokens bounds the payload (see Response token budgets) When the definition takes part in declared inheritance, hierarchy lists what it extends/implements, its subtypes, and the methods it overrides or that are overridden_by it.
codemap_context_batchContext for several symbols in one call — each symbol's bundle (including its own test_commands) plus combined_blast_radius and common_callers (callers that reach two or more of them — a shared entrypoint/coupling). Build a component's mental model without N round-trips; deduped and capped at 25. Aggregate source bodies are capped at 64 KiB with source_budget and per-definition source_truncations metadata — or pass brief:true to drop every body up front (source_omitted:true per definition) instead of spending that budget
codemap_projectsList all registered projects and their index sizes
codemap_docsReturn the agent guide (topic: overview/formats/workflow/commands/annotations/accuracy/ecosystem) so a harness can learn the tool
codemap_annotatePin a note / opaque data to a symbol or a from→to path (source label). Automated writers should pass a stable external_id; retries upsert within project + source and return the same annotation id with action:"created|updated|unchanged".
codemap_annotationsList annotations: all, for a symbol, or for a from→to path
codemap_unannotateRemove an annotation by id — prune/correct the knowledge layer
codemap_branch_statusRead-only git branch/commit state + the stable repo/branch keys used to key per-branch index snapshots
codemap_branch_switchSwitch the code index to a git branch — snapshot the old branch into fcheap, restore/reindex the new one. Defaults to to the current git branch; a non-git dir or detached HEAD is a no-op
codemap_cache_saveSave the current index (graph + vectors) to the fcheap stash vault, keyed by a tree hash — two identical working trees share one entry
codemap_cache_restoreRestore a matching fcheap cache entry (same tree hash + embedding profile), skipping extraction + embedding entirely; a miss is a no-op
codemap_cache_listList cached indexes for a project (stash IDs, tree hashes, dates)
codemap_cache_dropDrop a cached index by stash_id or tree_hash (from codemap_cache_list), or all cached indexes for the project

The two an agent reaches for first: codemap_context bundles everything about a symbol (definition, callers, callees, covering tests, blast radius) in one call instead of four, and codemap_status reports index freshness so the agent reindexes before trusting a stale answer. codemap_impact remains the deep change-analysis query — definition sites, callers, the transitive blast radius, and which tests cover those paths, replacing many file reads.

Response token budgets ​

codemap_context, codemap_explore, codemap_impact, and codemap_task_context accept an optional integer max_tokens: an approximate token budget for the JSON result (omitted or 0 means no budget). The estimate is deterministic and deliberately simple — the compact JSON byte length divided by four, rounded up — so it is a proportional bound, not a tokenizer count.

When the report exceeds the budget it is trimmed in a fixed order, least important first, until it fits or nothing more can be trimmed:

  1. source bodies (source_omitted:true is set on the definitions that lost theirs), then recalled memories and advisory next actions;
  2. list tails, shrinking from the end so the best-ranked items survive longest: value references, callees, callers, test commands, covering tests (and for codemap_impact the buckets node lists go first, then the blast radius, before the direct callers and tests; buckets only ever list nodes still in blast_radius, budget.dropped counts them, and blast_radius_total and the bucket counts stay the true sizes);
  3. whole trailing sections: surplus merged definitions, then explore processes (a process never names a dropped seed in matched_seeds), trailing explore contexts and seeds (the top definition and top seed always stay).

Identity and honesty fields are never removed: schema_version, query/symbol, selectors, call_graph and confidence enums, freshness, notes, partial_errors, and every *_total count. references_truncated is recomputed to match what is left.

A budgeted result carries an additive budget object (schema_version is unchanged):

json
{
  "budget": {
    "max_tokens": 800,
    "estimated_tokens": 790,
    "truncated": true,
    "dropped": { "source": 1, "callers": 12, "references": 3 }
  }
}

dropped counts the items removed per list, summed across nested reports (for example every explore context's callers); it is {} when nothing was trimmed. If the identity fields alone exceed the budget, trimming stops there and estimated_tokens stays above max_tokens. A negative max_tokens is an invalid_input error.

Exact source selectors ​

A name-only query stays backward-compatible: if six methods are named Close, it returns their union and says so. Precise indexing makes the stored edges exact; to choose one definition, project the fields already present on any symbol result:

json
{
  "selector": {
    "file": "internal/graph/store.go",
    "start_line": 91,
    "fqn": "graph.Store.Close",
    "kind": "method"
  }
}

The same shape works on source, context, callers, callees, references, impact, and risk; path accepts from_selector and to_selector. File+FQN+kind is the preferred identity and start_line disambiguates/falls back, so inserting lines above the declaration does not break the selector after reindex. A move or rename can invalidate it and returns found:false rather than selecting an arbitrary node. Database node IDs are deliberately absent from the public contract.

Honesty signals (stable machine contract) ​

The analysis tools carry three kinds of signal so a consumer can act on confidence instead of guessing:

  • candidates — on codemap_callers/codemap_callees/codemap_impact/codemap_risk/codemap_source/codemap_context, an ambiguous name-only query returns its merged result and candidates:[{selector,signature,file,start_line}] — the exact same merged set, already shaped as selectors. Re-query with candidates[i].selector to pin one definition without a separate codemap_find/codemap_symbols round-trip.

  • matched_in — on codemap_find in no-embeddings/degraded mode, each hit reports whether it matched the query on "symbol", "fqn", or "docstring", so a docstring-only hit (ranked below a name match) is distinguishable from an exact name hit.

  • fusion — on codemap_semantic, the hybrid vector/BM25 weighting profile actually used ("identifier", "natural_language", or "balanced"), chosen adaptively from the query's shape unless the server is configured with semantic.fusion: balanced (or CODEMAP_SEMANTIC_FUSION=balanced).

  • next — at most two executable {tool,args,why} follow-ups on context, context_batch, impact, risk, file_impact, and review. These are conditional recommendations, not a generic tool list: reindex when resolution is weak, run selected tests after a diff, or inspect risk for an untested hub.

  • partial_errors — non-fatal optional-component failures on context/context_batch (callers, callees, references, impact, or memory_recall) and on the composed map/explore orientation reports. Hard prerequisites still fail the tool; otherwise usable sections are returned alongside bounded error entries.

  • source_budget / source_truncations — explicit context-batch body budgeting. The aggregate source limit is 64 KiB; signatures, docs, and locations remain complete when bodies are shortened.

  • source_omitted — on codemap_source/codemap_context/codemap_context_batch, set per definition when brief:true dropped its source body. Signature/doc/location stay; call codemap_source (without brief) for the one definition you actually need the body of. Pass brief:true any time a hub symbol's response feels heavy — it's the response-side counterpart to mcp.profile (which trims the tool list, not individual response bodies).

  • budget — present on codemap_context, codemap_explore, codemap_impact, and codemap_task_context only when max_tokens was passed: {max_tokens, estimated_tokens, truncated, dropped}. See Response token budgets.

  • Structured errors — MCP failures preserve stable {code,message,hint} metadata when the service returns a CodedError, while the visible text includes the remediation hint for clients that only render text.

  • call_graph — a stable enum on codemap_impact/codemap_callers/codemap_callees/codemap_references/ codemap_review/codemap_context/codemap_hotspots/codemap_orphans/codemap_path/ codemap_map/codemap_traverse/codemap_atlas/codemap_features/codemap_processes/codemap_flow that a consumer switches on (no prose parsing):

    • resolved — every matched definition file has precise coverage (go/types for Go, language-server callHierarchy for TS/JS/Python/Vue)
    • name — name-based call graph (the Go/Ruby/Lua default; same-named symbols may over-match)
    • unresolved — the language has no complete call graph and the index isn't precise (TS/JS/Python/Vue) — callers/blast/tests are incomplete, not absent (TS/JS still carry name-based candidates for JSX component usage, same-file calls, calls through imported bindings, and typed Temporal workflow wiring; Python and Vue have none); reindex with codemap_index precise:true
    • none — no matching symbol / nothing to classify

    The free-form resolution sentence stays for humans. Map resolved→high, name→medium, unresolved/none→low confidence.

  • codemap_coverage — the project-wide, per-file view behind call_graph: which files have a persisted precise-resolution row, when it was recorded, and whether that file's on-disk content has since drifted (independent of codemap_status's aggregate stale/staleness counts, which describe the whole index, not one file). Use it to find out WHICH packages to trust before a call_graph:"name" on a broad query forces a worst-file assumption.

  • Reference honesty — codemap_references and the embedded context.references list carry separate coverage, confidence, and stale signals. These describe stored callback/value wiring; call_graph:"resolved" never upgrades them, and empty partial/unavailable coverage is not proof of no registration.

  • risk on codemap_review — one band for the whole diff (level unknown/low/medium/high, score 0..1, factors), folded from every changed symbol so a harness can gate verification on a single call instead of fanning codemap_risk out per symbol. unknown means at least one changed symbol lacks a usable call graph or analysis_complete is false, including mapping failures with zero safely identified symbols. It is absent for a complete zero-symbol diff and early no-repository/no-index degradation.

  • stale / staleness on codemap_review (and codemap_status) — index drift since the last index. Normally refresh before trusting snapshot-based impact. A deleted file is the intentional exception: when its old nodes remain, deletion_analysis identifies source:"last_index" and selected tests come before the reindex action that will prune those nodes.

  • confidence on dependency samples — confirmed means fresh precise or exact same-package evidence; candidate covers qualified name fan-out, package-scoped imports, and stale snapshots. Additive confirmed_total/candidate_total fields remain available when samples are capped.

  • blast_radius / covering_tests element shape — both are ImpactNode objects (symbol, fqn, kind, file, start_line, depth, …; no end_line). depth is the blast-radius hop distance. This is the stable element contract.

  • test_commands — codemap_review, codemap_impact, codemap_context, and each codemap_context_batch result carry a test_commands array: the same covering-test list turned into copy/paste-ready go test -run/bun test/pytest invocations by one shared helper, deduped and capped at 10. The same symbol yields identical commands on every surface, so a pre-edit codemap_impact/codemap_context call is just as directly runnable as post-edit codemap_review. Omitted (not an empty array) when there are no covering tests.

  • schema_version on codemap_review — every successful review emits version 1 and conforms to schemas/codemap.review.v1.schema.json (Draft 2020-12, urn:codemap:review:v1). Consumers may accept an absent version as legacy v1, but must reject unknown future versions rather than treating contract drift as an authoritative empty radius.

Branches & caching ​

Six tools keep the index aligned with the working tree and make reindexing cheap — both best-effort over the sibling fcheap stash vault, degrading to a normal index when fcheap isn't on $PATH (see Branches & caching for the concepts):

  • codemap_branch_status / codemap_branch_switch — a git checkout switches the code index too: snapshot the branch you're leaving into fcheap, restore the target branch's snapshot (or reindex when stale/absent). Keyed on the branch tip sha + embedding profile, so a restore only lands when it's still valid.
  • codemap_cache_save / codemap_cache_restore / codemap_cache_list / codemap_cache_drop — content-addressed index caching: a tree hash of all indexed (path, content_hash) pairs keys each entry, so two identical working trees share one. A restore skips extraction + embedding entirely. codemap_index does this automatically around a --reindex (auto-restore before, auto-save after) unless cache: false is set.

All six are no-ops on a non-git directory or detached HEAD and never fail the index.

Transport

codemap's MCP server uses newline-delimited JSON-RPC over stdio (what Claude Code, Codex, and OpenCode expect). codemap also speaks LSP to language servers, which uses Content-Length framing — the two transports are kept strictly separate.

This docs site uses cookie-free Vercel Web Analytics. codemap sends no usage telemetry.