charpcodemap 3.0.1

.NET 10.0

dotnet tool install --global charpcodemap --version 3.0.1

This package contains a .NET tool you can call from the shell/command line.

dotnet new tool-manifest
                    

                            if you are setting up this repo

dotnet tool install --local charpcodemap --version 3.0.1

This package contains a .NET tool you can call from the shell/command line.

#tool dotnet:?package=charpcodemap&version=3.0.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

nuke :add-package charpcodemap --version 3.0.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

CodeMap — Turn Your AI Agent Into a Semantic Dragon

Stop feeding your AI agent raw source files. Give it a semantic index instead.

CodeMap is a Roslyn-powered MCP server that lets AI agents navigate C#, VB.NET, and F# codebases by symbol, call graph, and architectural fact — instead of brute-reading thousands of lines of source code. One tool call. Precise answer. No context flood.

Average token savings: 90%+ versus reading files directly.

Install via Claude Code or manually

The fastest way to install is to paste the prompt below into a Claude Code shell. Claude will check your environment, install the tool, and register it as an MCP server — no manual steps needed.

Check whether .NET 10 SDK is installed by running dotnet --version. If the reported version is below 10.0, install it: on Windows run winget install Microsoft.DotNet.SDK.10, on macOS/Linux download from https://dotnet.microsoft.com/download/dotnet/10.0. Verify with dotnet --version once done. Once .NET 10 is confirmed, install CodeMap: if charpcodemap is not yet installed run dotnet tool install --global charpcodemap, otherwise run dotnet tool update --global charpcodemap to get the latest version. Verify the binary is reachable with charpcodemap --version. Finally, register it as a global MCP server in Claude Code by running claude mcp add charpcodemap charpcodemap --scope user and confirm it appears in the output of claude mcp list.

Or install manually:

# Install .NET 10 SDK if needed (Windows)
winget install Microsoft.DotNet.SDK.10

dotnet tool install --global charpcodemap
charpcodemap --version
claude mcp add charpcodemap charpcodemap --scope user

Requires .NET 10 (LTS). If you're working on a C# or VB.NET codebase you almost certainly have it already — check with dotnet --version.

Build and publish the global tool package

The daemon project is configured as a .NET global tool. A release build produces both the Windows self-contained executable and the NuGet package:

# Windows
./scripts/build-release.ps1 -Version 3.0.1

# Linux/macOS or Git Bash
./scripts/build-release.sh 3.0.1

The package is written to dist/nupkg/charpcodemap.3.0.1.nupkg. Publish it to nuget.org with an API key stored outside the repository:

$env:NUGET_API_KEY = "<your-nuget-api-key>"
dotnet nuget push .\dist\nupkg\charpcodemap.3.0.1.nupkg `
  --api-key $env:NUGET_API_KEY `
  --source https://api.nuget.org/v3/index.json `
  --skip-duplicate

After the package is available on nuget.org, users can install or update it with:

dotnet tool install --global charpcodemap --version 3.0.1
# Upgrade an existing installation:
dotnet tool update --global charpcodemap

Upgrading from v1.x

v2.0.0 uses a new binary storage engine (memory-mapped segments instead of SQLite). The current runtime does not read, migrate, delete, or fall back to legacy data under ~/.codemap. Missing indexes are rebuilt in the active repository data root when source-consistency checks allow it.

The Problem

An AI agent working on a C# codebase without CodeMap does this:

Agent: I need to find who calls OrderService.SubmitAsync.
→ Read OrderService.cs       (3,600 tokens)
→ Read Controllers/...       (3,600 tokens)
→ Grep across src/           (another 3,600 tokens)
→ Maybe find it. Maybe not.

With CodeMap:

md_cs_mp_refs_find { symbol_id: "M:MyApp.Services.OrderService.SubmitAsync", kind: "Call" }
→ 220 tokens. Exact file, line, and excerpt for every call site. Done.

That's 93.9% fewer tokens for a task agents do dozens of times per session. On a real production codebase (100k+ lines), savings are 95–99%+.

What It Does

CodeMap builds a persistent semantic index from your solution file using Roslyn — the same compiler that powers Visual Studio. Supports both .sln (all Visual Studio versions) and .slnx (VS 2022 17.12+ / .NET SDK 9+) solution formats — auto-discovered when solution_path is omitted (prefers .slnx). Short commit SHAs are auto-expanded. The index captures:

Every symbol (classes, methods, properties, interfaces, records)
Every call relationship and reference (who calls what, where)
Type hierarchy (inheritance chains, interface implementations)
Architectural facts extracted from code: HTTP endpoints, config keys, DB tables, DI registrations, middleware pipeline, retry policies, exception throw points, structured log templates

All of this is exposed via 29 MCP tools that any MCP-compatible AI agent can call. Starting from v1.3, CodeMap also navigates DLL boundaries — lazily resolving NuGet and SDK symbols on first access, with optional ICSharpCode.Decompiler source reconstruction and cross-DLL call graphs.

Supported languages: C#, VB.NET, and F#. Mixed-language solutions (.sln / .slnx containing C#, VB.NET, and F# projects) are indexed in a single pass. Semantic query tools work identically for symbols from any language. C# and VB.NET use Roslyn's MSBuildWorkspace; F# uses FSharp.Compiler.Service (MSBuildWorkspace doesn't support .fsproj). F# architectural fact extractors (endpoints, DI, config) are not yet implemented — symbol search, call graphs, references, and type hierarchy all work.

Blazor / Razor (v2.5.0+): .razor components are indexed via the Razor source generator. ComponentBase-derived classes appear in md_cs_mp_symbols_search. @page routes surface in md_cs_mp_surfaces_list_endpoints with a PAGE HTTP method. [Inject] and [Parameter] properties emit dedicated RazorInject / RazorParameter facts.

Multi-target projects (v2.5.1+): <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks> previously produced one extraction per TFM (3× duplication). CodeMap now collapses to a single extraction on the highest-ranked TFM, with ProjectDiagnostic.TargetFrameworks listing every TFM in the group. Symbol counts on heavily multi-targeted Blazor libraries drop 60–80%.

Interface-aware md_cs_mp_graph_callers (v2.6.0+): in DI-dispatched codebases (most production .NET) md_cs_mp_graph_callers on a concrete method silently under-reported because real call sites resolve through the registered interface. CodeMap now detects interface implementation at query time and surfaces an interface_implementation_hint listing the interface members and an estimated count of additional callers routed through them. Pass follow_interface: true to union those into the result (deduped by from_symbol). No baseline-format change, no re-index required. Handles both implicit and explicit interface implementations.

Indexing perf + correctness (v2.5.2): large reduction in indexing wall-clock by skipping auto-generated trees (*.g.cs, *.Designer.cs, files with <auto-generated>, paths under obj/), short-circuiting type-position identifier classification (typeof / generic args / base lists / attributes), and parallelizing Pass-2 reference & fact extraction across projects. Validated on a 9-repo Blazor corpus: Blazorise drops from 408 s → 95 s (−77 %), ant-design-blazor from 47 s → 25 s (−47 %), OrchardCore (single-target sentinel) from 131 s → 96 s (−27 %), and a 78-csproj distributed-database project (ByTech.Bedrock) indexes in 27 s with an 11.2× Pass-2 parallel speedup. Five query-correctness bugs also fixed: md_cs_mp_symbols_search browse-by-kinds now honours namespace / file_path / project_name filters; workspace-mode namespace filter is case-insensitive (matches committed mode); md_cs_mp_refs_find cache key includes resolution_state; workspace browse-by-kinds now includes overlay-new symbols; md_cs_mp_codemap_guide's decision table no longer advertises surfaces.list_di_registrations (which was never a registered tool).

The Transformation

Here's what changes when you give an agent CodeMap:

Without CodeMap	With CodeMap
`grep -rn "OrderService" src/`	`md_cs_mp_symbols_search { query: "OrderService" }`
Read 5 files to understand a method	`md_cs_mp_symbols_get_context` — card + source + all callees in one call
Manually trace call chains across files	`md_cs_mp_graph_trace_feature` — full annotated tree, one call
Hope grep finds the right interface impl	`md_cs_mp_types_hierarchy` — base, interfaces, derived types, instant
Read the whole file to find config usage	`md_cs_mp_surfaces_list_config_keys` — every `IConfiguration` access, indexed
Diff two commits by reading changed files	`md_cs_mp_index_diff` — semantic diff, rename-aware, architectural changes only

The agent stops reading your codebase and starts understanding it.

Showpiece: `md_cs_mp_graph_trace_feature`

The most powerful tool. Replaces 5–10 manual calls with one:

md_cs_mp_graph_trace_feature {
  "repo_path": "/path/to/repo",
  "entry_point": "M:MyApp.Controllers.OrdersController.Create",
  "depth": 3
}

Returns an annotated call tree with architectural facts at every node:

OrdersController.Create  [POST /api/orders]
  → OrderService.SubmitAsync
      → [Config: App:MaxRetries]
      → [DI: IOrderService → OrderService | Scoped]
      → Repository<Order>.SaveAsync
            → [DB: orders | DbSet<Order>]
            → [Retry: WaitAndRetryAsync(3) | Polly]

One query. Full feature flow. Every config key touched, every table written, every retry policy applied — surfaced automatically from the index.

Token Savings Benchmark

Measured across 24 canonical agent tasks on a real .NET solution:

Task	Raw Tokens	CodeMap	Savings
Find a class by name	3,609	248	93%
Get method source + facts	3,609	336	91%
Find all callers (md_cs_mp_refs_find)	3,609	220	94%
Caller chain depth=2	3,609	287	92%
Type hierarchy	3,609	200	94%
List all HTTP endpoints	3,609	360	90%
List all DB tables	3,609	169	95%
Workspace staleness check	3,609	62	98%
Baseline build (cache hit)	~30s Roslyn	~2ms pull	∞
Average			90.4%

Raw tokens = reading all source files. On production codebases (100k+ lines), savings reach 95–99%+.

Run it yourself:

dotnet test --filter "Category=Benchmark" -v normal

29 Tools Across Six Categories

Discover

Tool	What it does
`md_cs_mp_symbols_search`	FTS search by name, kind, namespace, or file path
`md_cs_mp_code_search_text`	Regex/substring search across source files — returns file:line:excerpt
`md_cs_mp_symbols_get_card`	Full symbol metadata + architectural facts + source code
`md_cs_mp_symbols_get_context`	Card + source + all callees with source — deep understanding in one call
`md_cs_mp_symbols_get_definition_span`	Raw source only, no overhead
`md_cs_mp_code_get_span`	Read any source excerpt by line range

Navigate

Tool	What it does
`md_cs_mp_refs_find`	All references to a symbol, classified (Call, Read, Write, Implementation…)
`md_cs_mp_graph_callers`	Depth-limited caller graph — who triggers this?
`md_cs_mp_graph_callees`	Depth-limited callee graph — what does this orchestrate?
`md_cs_mp_graph_trace_feature`	Full annotated feature flow with facts at every node
`md_cs_mp_types_hierarchy`	Base type, interfaces implemented, and all derived types

Architecture

Tool	What it does
`md_cs_mp_codemap_summarize`	Full codebase overview: endpoints, DI, config, DB, middleware, logging
`md_cs_mp_codemap_export`	Portable context dump (markdown/JSON, 3 detail levels) for any LLM
`md_cs_mp_codemap_guide`	Quick-start guide: session setup, decision table, and usage rules for agents
`md_cs_mp_index_diff`	Semantic diff between commits: symbols added/removed/renamed, API changes
`md_cs_mp_surfaces_list_endpoints`	Every HTTP route (controller + minimal API) with handler and file:line
`md_cs_mp_surfaces_list_config_keys`	Every `IConfiguration` access with usage pattern
`md_cs_mp_surfaces_list_db_tables`	EF Core entities + `[Table]` attributes + raw SQL table references

Workspace

Tool	What it does
`md_cs_mp_workspace_create`	Isolated overlay for in-progress edits
`md_cs_mp_workspace_reset`	Clear overlay, back to baseline
`md_cs_mp_workspace_list`	All active workspaces with staleness, SemanticLevel, and fact count
`md_cs_mp_workspace_delete`	Remove a workspace
`md_cs_mp_index_refresh_overlay`	Re-index changed files incrementally (~63ms)

Index Management

Tool	What it does
`md_cs_mp_index_ensure_baseline`	Build the semantic index (idempotent, cache-aware, auto-discovers solution)
`md_cs_mp_index_list_baselines`	All cached baselines with size, age, and commit
`md_cs_mp_index_cleanup`	Remove stale baselines (dry-run default)
`md_cs_mp_index_remove_repo`	Remove ALL baselines for a repo (ignores protection rules)

Repo

Tool	What it does
`md_cs_mp_repo_status`	Git state + whether a baseline exists for current HEAD
`md_cs_mp_repo_diagnostics`	Explicitly scoped storage, activity, bounded disk, token-savings, baseline-health, and cleanup dry-run diagnostics

Workspace Mode — See Your Own Edits

CodeMap tracks uncommitted changes via an overlay index. Agents using the same repository and workspace ID share one overlay through the default shared daemon; use different IDs when isolated overlay state is required:

1. md_cs_mp_index_ensure_baseline   → index HEAD once
2. md_cs_mp_workspace_create        → agent gets isolated overlay
3. Edit files on disk
4. md_cs_mp_index_refresh_overlay   → re-indexes only changed files (~63ms)
5. Query with workspace_id → results include your in-progress code

Three consistency modes:

Committed — baseline index only (default, no workspace needed)
Workspace — baseline + your uncommitted edits merged
Ephemeral — workspace + virtual file contents (unsaved buffer content)

Multi-Agent Supervisor Support

Running multiple agents in parallel? CodeMap has you covered:

Agents using the same workspace ID share one daemon-owned overlay without cross-process lock conflicts
Agents that need isolated overlay state use different workspace IDs
md_cs_mp_workspace_list shows every workspace: IsStale, SemanticLevel, fact count
Stale detection fires when a workspace's base commit diverges from HEAD
Supervisor can inspect, clean up, or re-provision any agent's workspace

Self-Healing Under Broken Builds

When a file doesn't compile, CodeMap doesn't drop references. It stores unresolved edges with syntactic hints. When compilation succeeds again (after a fix), a resolution worker automatically upgrades them to fully-resolved semantic edges.

md_cs_mp_refs_find returns both. Filter with resolution_state: "resolved" if you need certainty.

CodeMap resolves DLL symbols lazily on first agent access — NOT_FOUND at a DLL boundary triggers automatic extraction rather than a dead end.

Two levels, both permanent (cached in baseline DB):

Level	Trigger	What you get	Cost
1 — Metadata stub	Any `NOT_FOUND` query	Method signatures, XML docs, type hierarchy	~1–5ms (once)
2 — Decompiled source	`md_cs_mp_symbols_get_card` with `include_code: true`	Full reconstructed C# source via ICSharpCode.Decompiler	~10–200ms (once)

After Level 2, cross-DLL call graph edges are extracted so md_cs_mp_graph_callees and md_cs_mp_graph_trace_feature traverse INTO and THROUGH DLL code seamlessly.

source discriminator in md_cs_mp_symbols_get_card response:

"source_code" — symbol is from your own source
"metadata_stub" — Level 1 only (decompilation unavailable)
"decompiled" — Level 2 source reconstructed and ready

md_cs_mp_graph_trace_feature applies a max_lazy_resolutions_per_query budget (default 20) when encountering previously-unseen DLL types to bound decompilation latency.

Repository-local Storage

CodeMap stores each repository's data under <repo-root>/.codemap by default. The directory is created lazily on the first write, so repositories do not need per-project configuration for normal use.

Common settings belong in the user-level global configuration:

OS	Global configuration
Windows	`%APPDATA%\CodeMap\config.json`
macOS	`~/Library/Application Support/CodeMap/config.json`
Linux	`$XDG_CONFIG_HOME/codemap/config.json`, or `~/.config/codemap/config.json`

Use <repo-root>/.codemap.json only when a repository needs an allowed storage or resource override. A complete data-root override can also be supplied by CODEMAP_DATA_DIR or charpcodemap --data-dir <path>; these overrides do not create or inspect the default directory.

Legacy CODEMAP_CACHE_DIR and ~/.codemap storage are not compatibility inputs. Existing legacy data is left untouched.

Shared daemon

The default runtime is shared, so all local MCP adapters for the current user converge on one CodeMap host. This keeps workspace registration and owner-lock state consistent when multiple agents use the same repository and workspace ID. The equivalent explicit global configuration is:

{
  "schema_version": 1,
  "runtime": {
    "mode": "shared",
    "auto_start": true,
    "connect_timeout_ms": 1500,
    "start_timeout_ms": 10000,
    "request_timeout_ms": 120000,
    "max_queued_requests": 128,
    "max_concurrent_requests": 4,
    "max_message_bytes": 10485760
  }
}

shared requires the local daemon and reports a structured error if it cannot connect. auto may fall back to standalone only before the first request is sent to a daemon; use it only when that fallback is acceptable. A request interrupted after transmission is never replayed, and overlay mutations include a monotonic operation sequence for reconciliation. --runtime-mode standalone|shared|auto overrides the global mode for the adapter process. Explicit standalone processes must use different workspace IDs.

The local transport is a current-user named pipe on Windows or a user-only Unix socket on Linux/macOS. Election locks and the atomically published endpoint manifest live in the OS user runtime directory, never in a repository cache. The adapter sends repo_path and a deadline but never forwards its --data-dir; the shared host loads the user-level global snapshot and each repository's allowlisted .codemap.json itself.

standalone remains available for diagnostics and performance comparisons. It intentionally retains exclusive per-process workspace ownership and returns WORKSPACE_IN_USE when another process owns the same workspace ID.

v2 Storage Engine — 10x Faster Queries

v2.0.0 replaces SQLite with a custom binary storage engine using memory-mapped segment files. The Roslyn extraction pipeline is unchanged — only the on-disk format is new.

Query speedup (measured across 15 query types on real repos):

Query	v1 (SQLite)	v2 (mmap)	Speedup
`md_cs_mp_graph_trace_feature`	13.2ms	0.5ms	26x
`md_cs_mp_codemap_summarize`	18.9ms	0.9ms	21x
`md_cs_mp_surfaces_list_db_tables`	5.7ms	0.2ms	28x
`md_cs_mp_surfaces_list_config_keys`	3.6ms	0.2ms	18x
`md_cs_mp_types_hierarchy`	8.7ms	1.0ms	9x
`md_cs_mp_symbols_get_context`	28.7ms	5.3ms	5x
`md_cs_mp_symbols_get_card`	7.8ms	2.7ms	3x

Indexing speedup (Roslyn compilation dominates, but I/O is faster):

Repo	v1	v2	Speedup
eShopOnWeb (278 files)	16.2s	5.8s	2.8x
Bitwarden (4,466 files)	~170s	~110s	1.5x
dotnet/roslyn (18,799 files)	138.2s	96.8s	1.4x

What changed:

Baselines stored as contiguous packed binary segments (symbols, edges, files, facts) with mmap reads — no SQL parsing overhead
Custom search index with tokenized FTS (CamelCase splitting, signature/documentation indexing)
WAL-backed overlay for workspace mutations (same isolation model)
Zero native DLL dependencies (no e_sqlite3.dll)

Validated on 9+ repos including dotnet/roslyn (174K symbols, 768K references), dotnet/fsharp (157K symbols via FCS), and Bitwarden. Zero functional bugs. See docs/ENGINE-COMPARISON-RESULTS.MD for full data.

Self-Hosting Validated

CodeMap indexes its own 18-project solution (5,576 symbols, 20,960 references). The semantic tool surface has been validated against real-world architectural complexity. Self-hosting exposed and fixed cross-project reference bugs, CamelCase FTS edge cases, overlay StringId resolution issues, and multi-line SQL extraction gaps. Storage and diagnostic management paths are covered by focused concurrency and lifecycle tests.

Installation

.NET Global Tool — NuGet (recommended)

See the Install via Claude Code or manually section at the top for the one-paste Claude Code prompt and manual steps.

NuGet package: nuget.org/packages/charpcodemap

Docker

docker build -t charpcodemap .
docker run -i \
  -v /path/to/your/repo:/repo:ro \
  -v /path/to/cache:/cache \
  charpcodemap

-i is required — MCP uses stdio transport. Without it the container gets immediate EOF.

Uses the .NET SDK base image (~800MB) because MSBuildWorkspace needs MSBuild at runtime for md_cs_mp_index_ensure_baseline. Mount a cache volume (-v /path/to/cache:/cache) to avoid rebuilding the index on every container start.

Connect to Your AI Agent

Claude Code (Claude Desktop / claude.ai)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codemap": {
      "command": "charpcodemap"
    }
  }
}

Any MCP-Compatible Client

CodeMap speaks standard MCP over stdin/stdout (JSON-RPC 2.0). Any MCP client works.

CLAUDE.md Integration

Drop the instruction block from docs/CLAUDE-INSERT.MD into your project's CLAUDE.md to wire up automatic CodeMap usage for any Claude agent working on that project. The block includes the session startup sequence, a tool substitution decision table, and the "refresh before grep" rule that keeps agents in semantic mode.

Tip: Write XML Docs — CodeMap Uses Them

CodeMap indexes /// <summary> XML doc comments on all classes, methods, and interfaces. They appear in md_cs_mp_symbols_get_card, md_cs_mp_symbols_get_context, and md_cs_mp_symbols_search results — giving agents intent and context without reading implementations.

When writing C# code with CodeMap enabled, always add XML doc comments. This isn't just style — it directly improves every downstream query. Agents using md_cs_mp_graph_trace_feature see annotated call trees that read like specs. md_cs_mp_codemap_export includes docs in the portable context for other LLMs.

See docs/CODEMAP-AGENT-GUIDE.MD for the full agent workflow guide.

Architecture

Your Git repo              CodeMap Server
     │                          │
     │  repo_path               │
     ├─────────────────────────►│ GitService         (repo identity, HEAD SHA)
     │                          │      │
     │  solution.sln/.slnx      │      ▼
     ├─────────────────────────►│ RoslynCompiler     (MSBuildWorkspace for C#/VB, FCS for F#)
     │                          │      │
     │                          │      ▼
     │                          │ Extractors         (Symbols + Refs + TypeRelations + Facts)
     │                          │      │
     │                          │      ▼
     │                          │ CustomSymbolStore   (v2 binary segments, mmap'd)
     │                          │      │        ↕
     │                          │      │   Repo-local .codemap storage
     │                          │      ▼
     │  your uncommitted edits  │      ▼
     ├─────────────────────────►│ OverlayStore        (WAL-backed incremental overlay)
     │                          │      │
     │                          │      ▼
     │                          │ MergedQueryEngine  (baseline + overlay, transparent merge)
     │                          │      │
     │  MCP tool call           │      ▼
     ├─────────────────────────►│ McpServer          (stdio JSON-RPC 2.0, 29 tools)
     │                          │      │
     │  JSON response           │      ▼
     │◄─────────────────────────│ ResponseEnvelope   (answer + evidence + timing + token savings)

Layer dependencies (enforced at build time — violations are build errors):

CodeMap.Core      ← zero dependencies (domain types + interfaces)
CodeMap.Git       ← Core (LibGit2Sharp)
CodeMap.Roslyn    ← Core (Roslyn 5.x + MSBuildWorkspace)
CodeMap.Storage.Engine ← Core (v2 binary segments, sole engine since v2.1.0)
CodeMap.Query     ← Core + Storage.Engine (query engine + cache + overlay merge)
CodeMap.Mcp       ← Core + Query (MCP tool handlers)
CodeMap.Daemon    ← ALL (DI composition root, the executable)

Observability

Every response includes:

Per-phase timing — cache_lookup_ms, db_query_ms, ranking_ms (sub-millisecond on v2)
Token savings — tokens saved and cost avoided vs raw file reading
Semantic level — Full / Partial / SyntaxOnly (index quality signal)
Overlay revision — which workspace revision answered the query
Workspace ID — which workspace context answered (null for committed mode)

Host logs currently go to stderr. Token-savings totals are partitioned by StorageContextId, RepoId, and process instance, then atomically flushed below <data-root>/diagnostics/token-savings/ when a repository context retires. md_cs_mp_repo_diagnostics exposes the current process partition together with bounded storage and cleanup diagnostics. Common configuration is loaded once from the OS-specific global path shown above; repository exceptions come from <repo-root>/.codemap.json.

v2 Data Directory

Baselines and overlays are stored beneath the effective <data-root>/store/repos/<repo-id>/ using versioned binary artifacts and repository/workspace isolation. md_cs_mp_index_list_baselines, md_cs_mp_index_cleanup, and md_cs_mp_repo_diagnostics require an explicit repository scope; cleanup defaults to dry-run, and automatic cleanup remains disabled unless enabled in the global configuration.

Known Limitations & Coverage Gaps

CodeMap won't surface a hit in every situation a grep would. The most common reasons are documented in docs/KNOWN-LIMITATIONS.md. Top items to be aware of:

Multi-target conditional symbols. #if NET8_0-only types are invisible — extraction runs on the highest TFM only (L-01).
Legacy MVC MapControllerRoute — convention-routed actions don't surface in md_cs_mp_surfaces_list_endpoints. Only attribute routing, minimal API, and Blazor @page are extracted (L-02).
F# fact extractors not yet wired — F# gets symbols/refs/hierarchy only; endpoints / DI / config / DB tables don't extract from .fsproj yet (L-05).
Fresh clone with no build — Razor source-generator output may be invisible until you dotnet build once (L-08).

When md_cs_mp_symbols_search returns nothing for code you can see in the editor, scan KNOWN-LIMITATIONS first before falling back to grep.

Documentation

Doc	What's in it
`docs/CLAUDE-INSERT.MD`	Copy-paste block for CLAUDE.md — wires up agent to use CodeMap
`docs/CODEMAP-AGENT-GUIDE.MD`	Full agent operating guide: startup, refresh, query patterns, common mistakes
`docs/KNOWN-LIMITATIONS.md`	Coverage gaps and intentional non-features — what `grep` finds that CodeMap doesn't
`docs/DEVELOPER-GUIDE.MD`	How to add tools, extractors, storage methods
`docs/ARCHITECTURE-WALKTHROUGH.MD`	Request traces, data model, decision log
`docs/API-SCHEMA.MD`	Every type definition and MCP tool contract
`docs/SYSTEM-ARCHITECTURE.MD`	Component design, DB schema, query model

Build & Test

# Build (zero warnings enforced)
dotnet build -warnaserror

# Fast unit tests
dotnet test --filter "Category!=Integration&Category!=Benchmark"

# Integration tests (requires MSBuild)
dotnet test --filter "Category=Integration"

# Token savings benchmark
dotnet test --filter "Category=Benchmark" -v normal

# Performance microbenchmarks (BenchmarkDotNet)
cd tests/CodeMap.Benchmarks && dotnet run -c Release

Performance Reference

What to expect when running CodeMap on your codebase. All v2 engine numbers (default since v2.0.0).

Indexing time by repo size

Repo	Files	Symbols	Refs	Index time
CodeMap (self-hosted)	585	6,800	29,200	~24s
eShopOnWeb	278	—	—	~6s
dotnet/fsharp	994	157,000	58,000	~131s
Bitwarden	4,466	—	—	~110s
dotnet/roslyn	18,799	174,000	768,000	~97s

Subsequent runs on the same commit return immediately (already_existed: true). Incremental overlay refresh (after editing files) takes ~63ms.

Query response time (v2 engine)

Query	Cold (first hit, no L1 cache)	Warm (L1 cache)
`md_cs_mp_symbols_search`	1–10ms	<1ms
`md_cs_mp_symbols_get_card`	2–10ms	<1ms
`md_cs_mp_symbols_get_context`	5–30ms	1–5ms
`md_cs_mp_refs_find`	5–20ms	<1ms
`md_cs_mp_graph_callers / callees`	10–50ms	1–5ms
`md_cs_mp_graph_trace_feature`	10–100ms	1–10ms
`md_cs_mp_types_hierarchy`	1–5ms	<1ms
`md_cs_mp_codemap_summarize`	50–200ms	5–20ms
`surfaces.list_*`	1–10ms	<1ms
`md_cs_mp_index_diff`	100–500ms	—

Cold times scale with repo size (more symbols = more BFS/join work). Warm times are nearly flat across all repo sizes — L1 cache caps at 10,000 entries with LRU eviction.

Memory footprint (v2 engine)

Repo size	Baseline on disk	Resident memory (mmap)
Small (<1K symbols)	~1–5 MB	~5–20 MB
Medium (10K symbols)	~20–50 MB	~30–80 MB
Large (100K+ symbols)	~200–500 MB	~300–600 MB

mmap pages are demand-loaded by the OS — resident memory stays proportional to queries made, not total index size.

29 MCP tools. 90%+ token savings. Roslyn-grade semantics. C#, VB.NET, F#, Blazor/Razor. DLL boundary navigation. .sln + .slnx auto-discovery. v2.5.1 — multi-target compilation collapse (one extraction per .csproj, not per TFM), KNOWN-LIMITATIONS register surfaced via md_cs_mp_codemap_guide. Validated on dotnet/roslyn (174K symbols), dotnet/fsharp (157K symbols), and a 9-repo Blazor corpus including Blazorise, MudBlazor, ant-design-blazor, OrchardCore. Your agent deserves better than grep.

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version	Downloads	Last Updated
3.0.1	43	8/15/2026

charpcodemap 3.0.1

CodeMap — Turn Your AI Agent Into a Semantic Dragon

Install via Claude Code or manually

Build and publish the global tool package

Upgrading from v1.x

The Problem

What It Does

The Transformation

Showpiece: md_cs_mp_graph_trace_feature

Token Savings Benchmark

29 Tools Across Six Categories

Discover

Navigate

Architecture

Workspace

Index Management

Repo

Workspace Mode — See Your Own Edits

Multi-Agent Supervisor Support

Self-Healing Under Broken Builds

DLL Boundary Navigation

Repository-local Storage

Shared daemon

v2 Storage Engine — 10x Faster Queries

Self-Hosting Validated

Installation

.NET Global Tool — NuGet (recommended)

Docker

Connect to Your AI Agent

Claude Code (Claude Desktop / claude.ai)

Any MCP-Compatible Client

CLAUDE.md Integration

Tip: Write XML Docs — CodeMap Uses Them

Architecture

Observability

v2 Data Directory

Known Limitations & Coverage Gaps

Documentation

Build & Test

Performance Reference

Indexing time by repo size

Query response time (v2 engine)

Memory footprint (v2 engine)

Showpiece: `md_cs_mp_graph_trace_feature`