CodeMap — Turn Your AI Agent Into a Semantic Dragon

dotnet tool install --global codemap-mcp --version 1.3.2

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# 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.

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:

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. 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 26 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.

The Transformation

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

The agent stops reading your codebase and starts understanding it.

Showpiece: graph.trace_feature

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

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:

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

26 Tools Across Six Categories

Discover

Navigate

Architecture

Workspace

Index Management

Repo

Workspace Mode — See Your Own Edits

CodeMap tracks uncommitted changes via an overlay index. Every agent session gets its own isolated workspace:

1. index.ensure_baseline   → index HEAD once
2. workspace.create        → agent gets isolated overlay
3. Edit files on disk
4. 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:

• Each agent gets its own isolated workspace — no cross-contamination
• 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.

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

DLL Boundary Navigation

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):

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

source discriminator in 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

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

Shared Baseline Cache

Index once, reuse everywhere — across machines, CI, Docker containers:

export CODEMAP_CACHE_DIR=/shared/codemap-cache

• index.ensure_baseline pulls from cache first (~2ms vs ~30s Roslyn build)
• Auto-push after every new baseline build
• Self-healing: corrupt cache entries are detected and overwritten
• Zero config when CODEMAP_CACHE_DIR is unset — all cache ops are no-ops

Self-Hosting Validated

CodeMap indexes its own 17-project solution (5,112 symbols, 23,540 references). All 26 tools verified against real-world architectural complexity. Self-hosting exposed and fixed cross-project reference bugs, CamelCase FTS edge cases, and multi-line SQL extraction gaps. Every tool in this README was tested against the codebase that implements it.

Installation

.NET Global Tool — NuGet (recommended)

dotnet tool install --global codemap-mcp --version 1.3.0
codemap-mcp --version

Requires .NET 9 runtime. Install it from dot.net if needed.

NuGet package: nuget.org/packages/codemap-mcp

Self-Contained Binary (no .NET required)

Build from source — produces a single executable, batteries included:

# Linux/macOS
./scripts/build-release.sh 1.3.0

# Windows PowerShell
.\scripts\build-release.ps1 1.3.0

Outputs dist/win-x64/, dist/linux-x64/, dist/osx-arm64/. Drop the binary anywhere and run it — no runtime, no SDK, no install step. No trimming (Roslyn uses runtime reflection).

Docker

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

-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 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": "codemap-mcp"
    }
  }
}

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.

Architecture

Your Git repo              CodeMap Server
     │                          │
     │  repo_path               │
     ├─────────────────────────►│ GitService         (repo identity, HEAD SHA)
     │                          │      │
     │  solution.sln/.slnx      │      ▼
     ├─────────────────────────►│ RoslynCompiler     (MSBuildWorkspace → full semantic model)
     │                          │      │
     │                          │      ▼
     │                          │ Extractors         (Symbols + Refs + TypeRelations + Facts)
     │                          │      │
     │                          │      ▼
     │                          │ BaselineStore      (SQLite WAL + FTS5, one DB per commit)
     │                          │      │        ↕
     │                          │      │   SharedCache  (file-based, optional)
     │                          │      ▼
     │  your uncommitted edits  │      ▼
     ├─────────────────────────►│ OverlayStore       (SQLite per workspace, incremental)
     │                          │      │
     │                          │      ▼
     │                          │ MergedQueryEngine  (baseline + overlay, transparent merge)
     │                          │      │
     │  MCP tool call           │      ▼
     ├─────────────────────────►│ McpServer          (stdio JSON-RPC 2.0, 26 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   ← Core (SQLite + WAL + FTS5)
CodeMap.Query     ← Core + Storage (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
• 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

Structured logs to ~/.codemap/logs/codemap-{date}.log (daily rotation, JSON lines). Cumulative savings to ~/.codemap/_savings.json (persists across restarts). Config at ~/.codemap/config.json (log level, cache dir, budget overrides).

Documentation

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

26 MCP tools. 90%+ token savings. Roslyn-grade semantics. DLL boundary navigation. .sln + .slnx support. v1.3.0. Your agent deserves better than grep.