CodeMap

CodeMap — AI エージェントをセマンティックなドラゴンに変える

AI エージェントに生のソースファイルを読み込ませるのはやめましょう。代わりにセマンティックインデックスを与えましょう。

CodeMap は Roslyn を活用した MCP サーバーです。AI エージェントが C#、VB.NET、F# のコードベースを、何千行ものソースコードを力任せに読み取るのではなく、シンボル、呼び出しグラフ、アーキテクチャ上の事実を使って調査できます。ツール呼び出しは 1 回。回答は正確。コンテキストがあふれることもありません。

トークン削減率の平均：90% 以上（ファイルを直接読む場合との比較）。

---

Claude Code 経由または手動でインストール

最も簡単なインストール方法は、以下のプロンプトを Claude Code のシェルに貼り付けることです。Claude が環境を確認し、ツールをインストールして、MCP サーバーとして登録します。手動での操作は不要です。

dotnet --version を実行して .NET 10 SDK がインストールされているか確認してください。表示されたバージョンが 10.0 未満の場合は、インストールしてください。Windows では winget install Microsoft.DotNet.SDK.10 を実行し、macOS/Linux では https://dotnet.microsoft.com/download/dotnet/10.0 からダウンロードしてください。完了したら dotnet --version で確認してください。.NET 10 が確認できたら、CodeMap をインストールします。codemap-mcp がまだインストールされていない場合は dotnet tool install --global codemap-mcp を実行し、インストール済みの場合は dotnet tool update --global codemap-mcp を実行して最新バージョンに更新してください。codemap-mcp --version でバイナリを実行できることを確認してください。最後に claude mcp add codemap-mcp codemap-mcp --scope user を実行して、Claude Code にグローバル MCP サーバーとして登録し、claude mcp list の出力に表示されることを確認してください。

または、手動でインストール：

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

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

.NET 10（LTS）が必要です。C# または VB.NET のコードベースを扱っている場合は、ほぼ確実にインストール済みです。dotnet --version で確認してください。

v2.10.0 へのアップグレード

再インデックスもインデックス形式の変更も不要です。次の点にご注意ください。

• index_cleanup と index_remove_repo には repo_path が必要です。 データを削除するため、登録済みリポジトリが 1 つだけの場合でも、それへのフォールバックは行われなくなりました。クリーンアップでは、各 CodeMap プロセス内のすべてのワークスペースのベースラインが保護されるようになり、使用中のベースラインが中途半端に削除されることはありません（skipped_in_use に報告されます）。
• Blazor コンポーネント、MVC ビュー、Razor Pages からの参照が復活しました（v2.5.2 以降欠落していました）。 サービスまたはモデルに対する graph_callers / refs_find の結果に、.razor / .cshtml ファイル内に記述された使用箇所が含まれるようになりました。 ベースラインが次に構築されるとき（新しいコミットがある場合）に表示されます。
• アイドル時のメモリが解放されます。 インデックス作成後、アイドル状態のサーバーはビルド時のメモリの大部分を解放します （nopCommerce：2.5 分後に 2.9 GB → 1.1 GB、13 分後に 0.2 GB）。
• config.json には log_level と shared_cache_dir の 2 つのキーがあります。 shared_cache_dir が機能するようになりました（以前は読み込まれていませんでした）。budget_overrides は削除されました（以前は効果がありませんでした）。不明なキーがある場合は、ログに警告が 1 件出力されます。 相対パスの shared_cache_dir を指定すると、相対パスの CODEMAP_CACHE_DIR と同様に起動が停止します。
• 文字列として送信されたブール値パラメーター（"include_code": "false"）が、INTERNAL_ERROR を返さずに正しく処理されるようになりました。

詳細：CHANGELOG [2.10.0]。

v2.9.0 へのアップグレード：新しいツール名

ツール名ではドット形式ではなく、アンダースコアを使うようになりました（symbols_search など）。LLM API ではツール名にドットを使用できないためです。Claude Code ユーザーには変更ありません。Claude Code では、以前から mcp__codemap__symbols_search と表示されていました。引き続き古い名前を送信するクライアントやスクリプトのために、古いドット形式の名前も、早くとも v2.11.0 までは引き続き使用できます。そのような呼び出しを行うたびに、新しいツール名を示すメモが追加されます。プロジェクトの CLAUDE.md に CodeMap ブロックがある場合は、docs/CLAUDE-INSERT.MD から最新の内容を反映してください。

v1.x からのアップグレード

v2.0.0 では、新しいバイナリストレージエンジン（SQLite の代わりにメモリマップセグメントを使用）が採用されています。古い .db ベースラインは移行されないため、リポジトリごとに一度 index_ensure_baseline を実行して再構築してください。古い ~/.codemap/baselines/ フォルダーは使用されないため、削除できます。SQLite エンジンは v2.1.0 で削除されました。

---

問題点

CodeMap を使わずに C# コードベースで作業する AI エージェントは、次のようにします。

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.

CodeMap を使うと、次のようになります。

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

これは、エージェントがセッションごとに何十回も行うタスクで、トークン数を 93.9％ 削減します。実際の本番コードベース（10 万行以上）では、削減率は95～99％以上です。

---

機能

CodeMap は、Visual Studio と同じコンパイラーである Roslyn を使い、ソリューションファイルから永続的なセマンティックインデックスを構築します。.sln（すべての Visual Studio バージョン）と .slnx（VS 2022 17.12 以降／.NET SDK 9 以降）の両方のソリューション形式に対応し、solution_path を省略すると自動検出されます（.slnx が優先されます）。短縮コミット SHA は自動的に完全な SHA に展開されます。インデックスには次の情報が含まれます。

• すべてのシンボル（クラス、メソッド、プロパティ、インターフェイス、レコード）
• すべての呼び出し関係と参照（何がどれをどこで呼び出すか）
• 型階層（継承チェーン、インターフェイスの実装）
• コードから抽出されたアーキテクチャ上の情報：HTTP エンドポイント、設定キー、DB テーブル、DI 登録、ミドルウェアパイプライン、再試行ポリシー、例外のスロー箇所、構造化ログテンプレート

これらすべての情報は、MCP 互換の AI エージェントが呼び出せる 28 個の MCP ツールを通じて利用できます。v1.3 以降、CodeMap はDLL の境界もたどれるようになりました。NuGet および SDK のシンボルを初回アクセス時に遅延解決し、オプションで ICSharpCode.Decompiler によるソース再構築や、DLL をまたぐ呼び出しグラフにも対応します。

対応言語： C#、VB.NET、F#。複数の言語が混在するソリューション（C#、VB.NET、F# の各プロジェクトを含む .sln／.slnx）も一度の処理でインデックス化されます。28 個すべての MCP ツールは、どの言語のシンボルに対しても同じように動作します。C# と VB.NET では Roslyn の MSBuildWorkspace を使用します。F# では FSharp.Compiler.Service を使用します（MSBuildWorkspace は .fsproj に対応していません）。F# のアーキテクチャ情報抽出機能（エンドポイント、DI、設定）はまだ実装されていませんが、シンボル検索、呼び出しグラフ、参照、型階層はすべて利用できます。

Blazor／Razor（v2.5.0 以降）： .razor コンポーネントは Razor ソースジェネレーター経由でインデックス化されます。ComponentBase を継承するクラスは symbols_search に表示されます。@page ルートは、HTTP メソッド PAGE とともに surfaces_list_endpoints に表示されます。[Inject] および [Parameter] プロパティは、それぞれ専用の RazorInject／RazorParameter 情報を出力します。v2.10.0 以降、コンポーネント、MVC ビュー、Razor Pages に記述されたコードも参照グラフに含まれます。サービスメソッドに対する graph_callers では、そのサービスメソッドを呼び出すコンポーネントまたはビューが表示されます。ジェネレーターが生成する足場コード（タグヘルパー関連のコード）は含まれません。

マルチターゲットプロジェクト（v2.5.1 以降）： 以前は <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks> によって、TFM ごとに抽出が行われていました（3 倍に重複）。現在の CodeMap は、最も優先順位の高い TFM での抽出 1 回にまとめ、グループ内のすべての TFM を ProjectDiagnostic.TargetFrameworks に列挙します。複数の TFM を対象とする Blazor ライブラリでは、シンボル数が 60～80％減少します。 インターフェースを考慮した graph_callers（v2.6.0+）： DI でディスパッチされるコードベース（本番環境の .NET の大半）では、実際の呼び出し箇所が登録済みのインターフェースを経由するため、具象メソッドに対する graph_callers の結果は、実際より少なく表示されていました。CodeMap はクエリ時にインターフェースの実装を検出し、インターフェースのメンバーと、そこを経由する追加の呼び出し元の推定数を示す interface_implementation_hint を表示するようになりました。follow_interface: true を渡すと、それらを結果に追加できます（from_symbol で重複を除去）。ベースライン形式の変更も、再インデックスも不要です。暗黙的、明示的のどちらのインターフェース実装にも対応しています。

インデックス作成のパフォーマンスと正確性（v2.5.2）： 自動生成されたツリー（*.g.cs、*.Designer.cs、<auto-generated> を含むファイル、obj/ 以下のパス）をスキップし、型の位置にある識別子の分類（typeof／ジェネリック引数／基底リスト／属性）を早期に終了し、プロジェクト間で Pass-2 の参照とファクト抽出を並列化することで、インデックス作成の実行時間を大幅に短縮しました。9 個のリポジトリからなる Blazor コーパスで検証した結果、Blazorise は 408 秒 → 95 秒（−77 %）、ant-design-blazor は 47 秒 → 25 秒（−47 %）、OrchardCore（シングルターゲットのセンチネル）は 131 秒 → 96 秒（−27 %）に短縮されました。また、78 個の csproj を持つ分散データベースプロジェクト（ByTech.Bedrock）は 27 秒でインデックス化され、Pass-2 の並列処理で 11.2 倍の高速化を達成しました。さらに、クエリの正確性に関する 5 件のバグも修正しました。symbols_search の種類別ブラウズで namespace／file_path／project_name フィルターが適用されるようになりました。ワークスペースモードの名前空間フィルターは、大文字と小文字を区別しなくなりました（コミット済みモードと同様）。refs_find のキャッシュキーに resolution_state が含まれるようになりました。ワークスペースの種類別ブラウズに、オーバーレイで追加されたシンボルが含まれるようになりました。codemap_guide の判断表から、登録済みツールではなかった surfaces_list_di_registrations が削除されました。

---

変革

エージェントに CodeMap を使わせると、次のように変わります。

CodeMap なし	CodeMap あり
grep -rn "OrderService" src/	symbols_search { query: "OrderService" }
メソッドを理解するために 5 つのファイルを読む	symbols_get_context — カード＋ソース＋すべての呼び出し先を 1 回の呼び出しで取得
ファイルをまたいで呼び出しチェーンを手作業で追跡する	graph_trace_feature — 注釈付きの完全なツリーを 1 回の呼び出しで取得
grep で適切なインターフェース実装が見つかることを期待する	types_hierarchy — 基底型、インターフェース、派生型を即座に取得
設定の使用箇所を探すためにファイル全体を読む	surfaces_list_config_keys — インデックス化されたすべての IConfiguration アクセスを取得
変更されたファイルを読んで 2 つのコミットを比較する	index_diff — セマンティックな差分。名前変更に対応し、アーキテクチャ上の変更のみを表示

エージェントはコードベースを読むのをやめ、コードベースを理解するようになります。

---

注目機能：graph_trace_feature

最も強力なツールです。手作業での 5〜10 回の呼び出しを、1 回に置き換えます。

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

各ノードにアーキテクチャ上のファクトを付記した呼び出しツリーを返します。

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]

1 回のクエリで、機能の流れ全体を取得できます。アクセスされるすべての設定キー、書き込まれるすべてのテーブル、適用されるすべての再試行ポリシーが、インデックスから自動的に表示されます。

---

トークン削減のベンチマーク

実際の .NET ソリューションで、代表的な 24 種類のエージェントタスクを対象に測定しました。

タスク	通常のトークン数	CodeMap	削減率
名前でクラスを検索	3,609	248	93%
メソッドのソース＋ファクトを取得	3,609	336	91%
すべての呼び出し元を検索（refs_find）	3,609	220	94%
呼び出し元のチェーン（深さ=2）	3,609	287	92%
型階層	3,609	200	94%
すべての HTTP エンドポイントを一覧表示	3,609	360	90%
すべての DB テーブルを一覧表示	3,609	169	95%
ワークスペースの古さを確認	3,609	62	98%
ベースラインのビルド（キャッシュヒット）	~30s Roslyn	~2ms pull	∞
平均			90.4%

通常のトークン数 = すべてのソースファイルを読む場合。本番環境のコードベース（10 万行以上）では、削減率は 95〜99% 以上に達します。

実際に試すには：

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

---

6 つのカテゴリにわたる 28 個のツール

検索

ツール	機能
symbols_search	名前（前方一致、OR）、種類、名前空間、ファイルパスで検索します
code_search_text	ソースファイル全体を正規表現または部分文字列で検索します。ファイル名・行番号・抜粋を返します
symbols_get_card	シンボルの全メタデータ、アーキテクチャに関する情報、ソースコードを取得します
symbols_get_context	カード、ソース、すべての呼び出し先とそのソースを取得し、1 回の呼び出しで深く理解できます
symbols_get_definition_span	余分な情報を含まない、生のソースのみを取得します
code_get_span	行範囲を指定して、任意のソース抜粋を読み取ります

ナビゲーション

ツール	機能
refs_find	シンボルへのすべての参照を分類（呼び出し、読み取り、書き込み、実装など）して取得します
graph_callers	深さを制限した呼び出し元のグラフです。これを呼び出すのは何ですか？
graph_callees	深さを制限した呼び出し先のグラフです。これが連携するのは何ですか？
graph_trace_feature	各ノードの情報を付記した、機能全体のフローです
types_hierarchy	基底型、実装されているインターフェース、すべての派生型を取得します

アーキテクチャ

ツール	機能
codemap_summarize	コードベース全体の概要です。エンドポイント、DI、設定、DB、ミドルウェア、ログ記録を含みます
codemap_export	任意の LLM 向けの、移植可能なコンテキストダンプ（Markdown／JSON、詳細度 3 段階）です
codemap_guide	クイックスタートガイドです。セッション設定、判断表、エージェント向けの使用ルールを含みます
index_diff	コミット間のセマンティック差分です。追加・削除・名前変更されたシンボルや API の変更を確認できます
surfaces_list_endpoints	すべての HTTP ルート（コントローラーと最小限の API）を、ハンドラーとファイル名・行番号とともに取得します
surfaces_list_config_keys	使用パターンとともに、すべての IConfiguration アクセスを取得します
surfaces_list_db_tables	EF Core エンティティ、[Table] 属性、生 SQL のテーブル参照を取得します

ワークスペース

ツール	機能
workspace_create	作業中の編集用に分離されたオーバーレイを作成します
workspace_reset	オーバーレイをクリアし、ベースラインに戻します
workspace_list	古さ、SemanticLevel、ファクト数とともに、すべてのアクティブなワークスペースを表示します
workspace_delete	ワークスペースを削除します
index_refresh_overlay	変更されたファイルを増分再インデックスします（約 63 ms）

インデックス管理

ツール	機能
index_ensure_baseline	セマンティックインデックスを構築します（冪等、キャッシュを考慮、ソリューションを自動検出）
index_list_baselines	キャッシュされたすべてのベースラインを、サイズ、経過時間、コミットとともに表示します
index_cleanup	古いベースラインを削除します（デフォルトはドライラン。repo_path が必須。HEAD やワークスペースのベースラインは削除しません）
index_remove_repo	リポジトリのすべてのベースラインとワークスペースを削除します（デフォルトはドライラン。repo_path が必須。他のプロセスがワークスペースを開いている間は拒否します）

リポジトリ

ツール	機能
repo_status	Git の状態と、現在の HEAD に対するベースラインの有無を確認します

---

ワークスペースモード — 独自の編集内容を確認

CodeMap は、オーバーレイインデックスを使って未コミットの変更を追跡します。各エージェントセッションには、それぞれ分離されたワークスペースが用意されます。

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

3 つの整合性モード：

• コミット済み — ベースラインインデックスのみ（デフォルト。ワークスペースは不要）
• ワークスペース — ベースラインと未コミットの編集内容を統合します
• 一時的 — ワークスペースと仮想ファイルの内容（未保存のバッファーの内容）を使用します

---

マルチエージェントスーパーバイザーのサポート

複数のエージェントを並行して実行していますか？現在利用できる機能は次のとおりです。

• 各ワークスペースは分離されています。異なる workspace_id を使用するエージェント同士が、互いの編集内容を見ることはありません
• workspace_list にはすべてのワークスペースが表示されます。IsStale、SemanticLevel、ファクト数も確認できます
• ワークスペースのベースコミットが HEAD と異なる場合、古さの検出が作動します
• スーパーバイザーは、任意のエージェントのワークスペースを調査、クリーンアップ、または再プロビジョニングできます

把握しておくべき点（マルチエージェントベンチマークでの測定結果。docs/CODEMAP-MULTI-AGENT-SCALING-FINDINGS.md を参照）：

• エージェントごとに CodeMap プロセスが 1 つ必要です。 各 MCP クライアントまたはサブエージェントが独自のサーバーを起動するため、メモリ使用量はエージェント数に応じて増加します。小規模および中規模のソリューションではプロセスあたり約 0.3～0.5 GB、大規模なものでは 2.5～4 GB です。各プロセスは初回に同じベースラインを構築するため、並行してビルドすると互いの処理が遅くなります。共有ホストが予定されている解決策です（ADR-048）。
• ワークスペースをプロセス間で共有することはできません。 別の CodeMap プロセスがその workspace_id を保持している場合、呼び出しは WORKSPACE_IN_USE（再試行可能）を返します。再試行するか、エージェントごとに異なる ID を指定してください。
• 新しいワークツリーのエージェントは、まず復元する必要があります。 新しいクローンまたは git worktree add には復元結果がありません。index_ensure_baseline の前に dotnet restore を実行してください。実行しないとインデックスが不完全になります（semantic_level: partial として報告されます。L-12）。
• エージェント間のクリーンアップは安全です（v2.10.0）。 index_cleanup は、どのプロセスであってもエージェントのワークスペースが使用しているベースラインを削除せず、別のプロセスが開いているベースラインも削除しません。index_remove_repo は、リポジトリ内のワークスペースが別のプロセスで開かれている間は拒否されます（WORKSPACE_IN_USE）。
• アイドル状態のプロセスはメモリを解放します（v2.10.0）。 インデックス作成から 2 分後、サーバーはヒープをコンパクト化します。オーバーレイが 10 分間更新されないと、キャッシュされた Roslyn ソリューションも破棄されます（次回の更新時に再び開かれます）。これにより各プロセスのアイドル時のコストは下がりますが、共有ホストが導入されるまでは、プロセス数に応じたメモリ使用量の増加は続きます。

---

ビルドが壊れても自己修復

ファイルがコンパイルできない場合も、CodeMap は参照を破棄しません。構文上のヒントを含む未解決エッジとして保存します。修正後に再びコンパイルが成功すると、解決ワーカーが自動的にそれらを完全に解決済みのセマンティックエッジへとアップグレードします。

refs_find は両方を返します。確実性が必要な場合は、resolution_state: "resolved" でフィルタリングしてください。

---

DLL 境界のナビゲーション

CodeMap は、エージェントが初めて DLL のシンボルにアクセスしたときに、遅延方式で解決します。DLL 境界で NOT_FOUND となっても行き止まりにはならず、自動的に抽出が行われます。

2 つのレベルがあり、どちらも永続的に保存されます（ベースライン DB にキャッシュされます）。

レベル	トリガー	得られる内容	コスト
1 — メタデータスタブ	任意の NOT_FOUND クエリ	メソッドシグネチャ、XML ドキュメント、型階層	約 1～5ms（初回のみ）
2 — 逆コンパイル済みソース	include_code: true を指定した symbols_get_card	ICSharpCode.Decompiler による、完全に再構築された C# ソース	約 10～200ms（初回のみ）

レベル 2 の後、DLL をまたぐ呼び出しグラフのエッジが抽出され、graph_callees と graph_trace_feature は DLL コードの内部およびその先をシームレスにたどれるようになります。

symbols_get_card のレスポンスに含まれる source 識別子：

• "source_code" — シンボルは独自のソースから取得されています
• "metadata_stub" — レベル 1 のみ（逆コンパイルは利用できません）
• "decompiled" — レベル 2 のソースが再構築され、利用可能な状態です

graph_trace_feature は、未確認の DLL 型に遭遇したとき、逆コンパイルの遅延を抑えるために max_lazy_resolutions_per_query の予算（デフォルトは 20）を適用します。

---

共有ベースラインキャッシュ

一度インデックスを作成すれば、マシン、CI、Docker コンテナを問わず再利用できます：

export CODEMAP_CACHE_DIR=/shared/codemap-cache

または、config.json で設定します（「可観測性」を参照）：{ "shared_cache_dir": "/shared/codemap-cache" }。

• index_ensure_baseline はまずキャッシュから取得します（Roslyn のビルドが約 30 秒かかるのに対し、約 2 ミリ秒）
• マシン上で劣化したベースライン（復元されていないチェックアウトや、読み込みに失敗したソースジェネレーターなど）を除き、新しいベースラインをビルドするたびに自動でプッシュします。他のマシンで不完全なインデックスが使われるのを防ぐためです
• 自己修復：破損したキャッシュエントリを検出して上書きします
• 優先順位：CODEMAP_CACHE_DIR（設定されている場合。空欄は無効） > config.json の shared_cache_dir > 無効。どちらも設定されていない場合、キャッシュ操作はすべて何も行いません
• 絶対パス、または ~/ で始まるパスを指定する必要があります。相対パスを指定するとクライアントの作業ディレクトリを基準に解決されるため、サーバーの起動が停止します（終了コード 2）

---

v2 ストレージエンジン — クエリが 10 倍高速に

v2.0.0 では SQLite を、メモリマップセグメントファイルを使用するカスタムバイナリストレージエンジンに置き換えています。Roslyn の抽出パイプラインに変更はなく、ディスク上の形式だけが新しくなっています。

クエリの高速化（実際のリポジトリで 15 種類のクエリを測定）：

クエリ	v1（SQLite）	v2（mmap）	高速化
graph_trace_feature	13.2ms	0.5ms	26x
codemap_summarize	18.9ms	0.9ms	21x
surfaces_list_db_tables	5.7ms	0.2ms	28x
surfaces_list_config_keys	3.6ms	0.2ms	18x
types_hierarchy	8.7ms	1.0ms	9x
symbols_get_context	28.7ms	5.3ms	5x
symbols_get_card	7.8ms	2.7ms	3x

インデックス作成の高速化（Roslyn のコンパイルが処理の大半を占めますが、I/O は高速化されています）：

リポジトリ	v1	v2	高速化
eShopOnWeb（278 ファイル）	16.2s	5.8s	2.8x
Bitwarden（4,466 ファイル）	~170s	~110s	1.5x
dotnet/roslyn（18,799 ファイル）	138.2s	96.8s	1.4x

変更点：

• ベースラインを、シンボル、エッジ、ファイル、ファクトからなる連続したパック済みバイナリセグメントとして保存し、mmap で読み込みます。SQL の解析オーバーヘッドはありません
• トークン化 FTS を備えたカスタム検索インデックス（CamelCase の分割、シグネチャとドキュメントのインデックス作成）
• ワークスペースの変更に対応する WAL ベースのオーバーレイ（分離モデルは同じ）
• ネイティブ DLL への依存はありません（e_sqlite3.dll は不要）

dotnet/roslyn（174K シンボル、768K 参照）、dotnet/fsharp（FCS 経由で 157K シンボル）、Bitwarden など、9 件以上のリポジトリで検証済みです。機能上のバグはありません。すべてのデータについては docs/ENGINE-COMPARISON-RESULTS.MD をご覧ください。

---

セルフホスティングでの検証

CodeMap は、18 プロジェクトからなる自身のソリューション（5,576 シンボル、20,960 参照）をインデックス化します。 実際のアーキテクチャの複雑さをもとに、28 個すべてのツールを検証しました。セルフホスティングにより、プロジェクト間参照のバグ、CamelCase FTS のエッジケース、オーバーレイの StringId 解決の問題、複数行 SQL の抽出漏れが明らかになり、修正されました。この README に記載されているすべてのツールは、それを実装するコードベースでテスト済みです。

---

インストール

.NET グローバルツール — NuGet（推奨）

Claude Code 用の一括貼り付けプロンプトと手動手順については、先頭の Claude Code 経由または手動でインストール セクションをご覧ください。

NuGet パッケージ： nuget.org/packages/codemap-mcp

Docker

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

MCP は stdio トランスポートを使用するため、-i が必要です。指定しない場合、コンテナは直ちに EOF を受け取ります。

index_ensure_baseline の実行時に MSBuildWorkspace が MSBuild を必要とするため、.NET SDK のベースイメージ（約 800 MB）を使用します。コンテナの起動ごとにインデックスを再構築しないよう、キャッシュボリューム（-v /path/to/cache:/cache）をマウントしてください。

---

AI エージェントへの接続

Claude Code（Claude Desktop / claude.ai）

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "codemap": {
      "command": "codemap-mcp"
    }
  }
}

MCP 対応クライアント全般

CodeMap は標準の MCP を stdin/stdout 経由で使用します（JSON-RPC 2.0）。どの MCP クライアントでも使用できます。

CLAUDE.md との統合

docs/CLAUDE-INSERT.MD の指示ブロックをプロジェクトの CLAUDE.md に貼り付けると、そのプロジェクトで作業するすべての Claude エージェントが CodeMap を自動的に使用するようになります。このブロックには、セッション開始時の手順、ツール置き換えの判断表、およびエージェントをセマンティックモードに保つ「grep の前に更新する」ルールが含まれています。

---

ヒント：XML ドキュメントを記述する — CodeMap が活用します

CodeMap は、すべてのクラス、メソッド、インターフェースにある /// <summary> XML ドキュメントコメントをインデックス化します。これらは symbols_get_card、symbols_get_context、symbols_search の結果に表示されるため、エージェントは実装を読まなくても意図やコンテキストを把握できます。

CodeMap を有効にして C# コードを記述する場合は、必ず XML ドキュメントコメントを追加してください。 これは単なるスタイルの問題ではなく、後続のすべてのクエリの品質を直接向上させます。graph_trace_feature を使用するエージェントには、仕様書のように読める注釈付きの呼び出しツリーが表示されます。 codemap_export は、ほかの LLM 向けのポータブルなコンテキストにドキュメントを含めます。

エージェントのワークフローガイド全体については、docs/CODEMAP-AGENT-GUIDE.MD を参照してください。

---

アーキテクチャ

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)
     │                          │      │        ↕
     │                          │      │   SharedCache  (file-based, optional)
     │                          │      ▼
     │  your uncommitted edits  │      ▼
     ├─────────────────────────►│ OverlayStore        (WAL-backed incremental overlay)
     │                          │      │
     │                          │      ▼
     │                          │ MergedQueryEngine  (baseline + overlay, transparent merge)
     │                          │      │
     │  MCP tool call           │      ▼
     ├─────────────────────────►│ McpServer          (stdio JSON-RPC 2.0, 28 tools)
     │                          │      │
     │  JSON response           │      ▼
     │◄─────────────────────────│ ResponseEnvelope   (answer + evidence + timing + token savings)

レイヤーの依存関係（ビルド時に検証され、違反するとビルドエラーになります）：

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)

---

オブザーバビリティ

すべての応答には、次の情報が含まれます。

• フェーズごとの処理時間 — cache_lookup_ms、db_query_ms、ranking_ms（v2 ではサブミリ秒）
• トークンの節約量 — トークンの節約数と、生のファイル読み取りと比較した回避コスト
• セマンティックレベル — Full / Partial / SyntaxOnly（インデックス品質の指標。下記参照）
• オーバーレイのリビジョン — クエリへの応答に使用したワークスペースのリビジョン
• ワークスペース ID — 応答に使用したワークスペースのコンテキスト（コミットモードでは null）

レベルが Full ではない場合、index_ensure_baseline の project_diagnostics に、プロジェクトごとの理由が示されます。

• compiled: false：プロジェクトをコンパイルできなかったため、構文のみでインデックス化されました。
• missing_restore_output：チェックアウトで復元が一度も実行されておらず（新しいクローンまたは git worktree）、パッケージや、場合によってはフレームワークも未解決です。dotnet restore を実行してから、ベースラインを再ビルドしてください（L-12）。
• generator_load_failures：新しい .NET SDK のソースジェネレーターを読み込めなかったため、そのジェネレーターのコード（例：Razor コンポーネント）が欠落しています（L-11）。

このベースラインに対する以降のすべてのクエリでも、同じレベルが報告されます（v2.8.2 以降でビルドされたベースラインが対象です。古いベースラインにはこれらのフィールドが記録されていません）。

構造化ログは ~/.codemap/logs/codemap-{date}.log に保存されます（日次ローテーション、JSON Lines）。 累積の節約量は ~/.codemap/_savings.json に保存されます（再起動後も保持されます）。 設定は ~/.codemap/config.json にあり、起動時に一度読み込まれます。キーは 2 つです。

{ "log_level": "Information", "shared_cache_dir": "/shared/codemap-cache" }

• log_level：Trace、Debug、Information（デフォルト）、Warning、Error のいずれかです。
• shared_cache_dir：共有ベースラインキャッシュです。CODEMAP_CACHE_DIR が設定されていない場合にのみ使用されます。

それ以外のキー（タイプミスや、効果がなく v2.10.0 で削除された budget_overrides など）は無視され、ログに警告が 1 件記録されます。

データディレクトリ（CODEMAP_HOME）

上記のすべてのデータは、デフォルトでは ~/.codemap という単一のデータルートの下に保存されます。CODEMAP_HOME を設定すると、設定ファイル、ログ、ストア、_savings.json を移動できます。たとえば、テスト実行、CI ジョブ、サンドボックスごとに分ける場合に便利です。絶対パスまたは ~/ で始まるパスを指定してください。相対パスを指定すると、起動時にサーバーが停止します（終了コード 2）。

ベースラインは <data root>/store/<repoId>/baselines/<commitSha>/ にバイナリのセグメントファイルとして保存されます。オーバーレイは <data root>/store/<repoId>/overlays/<workspaceId>/ に保存されます。index_list_baselines で確認し、index_cleanup で領域を再利用してください。

---

既知の制限事項とカバレッジの不足

CodeMap では、grep で見つかる内容がすべて見つかるとは限りません。最も一般的な理由は、docs/KNOWN-LIMITATIONS.md に記載されています。特に注意すべき項目は次のとおりです。

• 複数のターゲットを持つ条件付きシンボル。 #if NET8_0 のみで定義された型は表示されません。抽出は最も高い TFM のみを対象に実行されるためです（L-01）。
• 従来の MVC MapControllerRoute — 規約ベースのルーティングを使用するアクションは、surfaces_list_endpoints に表示されません。抽出されるのは、属性ルーティング、最小 API、Blazor の @page のみです（L-02）。
• F# のファクト抽出器は未接続です — F# ではシンボル／参照／階層のみを取得できます。エンドポイント／DI／構成／DB テーブルは、まだ .fsproj から抽出されません（L-05）。
• 復元されていないチェックアウト — 新規クローンまたは git worktree には obj/project.assets.json がなく、CodeMap は復元を行わないため、パッケージ参照（場合によってはフレームワーク自体）を解決できません。これは missing_restore_output、semantic_level: partial として報告されます。index_ensure_baseline の前に dotnet restore を実行してください（L-12）。
• CodeMap の Roslyn より新しい .NET SDK — その SDK のソースジェネレーター（例：Razor）が読み込まれず、生成結果が欠落する場合があります。generator_load_failures として報告されます。CodeMap を更新してください（L-11）。
• ビルドしていない新規クローン — dotnet build を一度実行するまで、Razor のソースジェネレーターによる出力が表示されない場合があります（L-08）。
• Razor のマークアップのみの使用箇所 — @onclick="Save" や <Greeting /> のようなコンポーネントタグでは、まだ参照が生成されません。また、Razor の参照は .razor ファイルではなく、生成された obj/…_razor.g.cs の行を指します（L-15）。

エディター上で確認できるコードに対して symbols_search が何も返さない場合は、grep に切り替える前に、まず KNOWN-LIMITATIONS を確認してください。

---

ドキュメント

ドキュメント	内容
docs/CLAUDE-INSERT.MD	CLAUDE.md 用のコピー＆ペーストできるブロック — CodeMap を使うようエージェントを設定します
docs/CODEMAP-AGENT-GUIDE.MD	エージェントの完全な操作ガイド：起動、更新、クエリパターン、よくある間違い
docs/KNOWN-LIMITATIONS.md	カバレッジの不足と意図的に実装していない機能 — grep では見つかるものの CodeMap では見つからない内容
docs/DEVELOPER-GUIDE.MD	ツール、抽出器、ストレージメソッドの追加方法
docs/ARCHITECTURE-WALKTHROUGH.MD	リクエストのトレース、データモデル、意思決定ログ
docs/API-SCHEMA.MD	すべての型定義と MCP ツールのコントラクト
docs/SYSTEM-ARCHITECTURE.MD	コンポーネント設計、DB スキーマ、クエリモデル

---

ビルドとテスト

# Build (zero warnings enforced)
dotnet build -warnaserror

# Test per project: `dotnet test` at the solution root starts every test runner at once and can run out of memory
dotnet run --project tests/CodeMap.Core.Tests          # likewise Roslyn, Query, Mcp, Storage.Engine, Daemon, Git

# Integration tests: restore the test fixtures once per checkout first (MSBuildWorkspace doesn't restore)
dotnet restore testdata/SampleSolution/SampleSolution.sln   # likewise SampleVbSolution, SampleBlazorSolution, SampleFSharpSolution
dotnet run --project tests/CodeMap.Integration.Tests   # includes Category=Concurrency (spawns real servers, ~1 min)

# Linux test rig (Docker; see docs/DEVELOPER-GUIDE.MD)
.\tests\docker\run-linux-tests.ps1 integration

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

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

---

パフォーマンスの参考値

CodeMap をコードベースで実行した場合の目安です。v2 エンジンの数値はすべて、v2.0.0 以降のデフォルト値です。

リポジトリサイズ別のインデックス作成時間

リポジトリ	ファイル数	シンボル数	参照数	インデックス作成時間
CodeMap（セルフホスト）	585	6,800	29,200	約24秒
eShopOnWeb	278	—	—	約6秒
dotnet/fsharp	994	157,000	58,000	約131秒
Bitwarden	4,466	—	—	約110秒
dotnet/roslyn	18,799	174,000	768,000	約97秒

同じコミットでの2回目以降の実行は、即座に返ります（already_existed: true）。ファイル編集後の増分オーバーレイ更新には 約63ミリ秒かかります。

クエリ応答時間（v2 エンジン）

クエリ	コールド（初回、L1 キャッシュなし）	ウォーム（L1 キャッシュあり）
symbols_search	1～10ms	<1ms
symbols_get_card	2～10ms	<1ms
symbols_get_context	5～30ms	1～5ms
refs_find	5～20ms	<1ms
graph_callers / callees	10～50ms	1～5ms
graph_trace_feature	10～100ms	1～10ms
types_hierarchy	1～5ms	<1ms
codemap_summarize	50～200ms	5～20ms
surfaces.list_*	1～10ms	<1ms
index_diff	100～500ms	—

コールド時の時間はリポジトリのサイズに応じて増加します（シンボルが多いほど、BFS／結合処理が増えます）。ウォーム時の時間は、リポジトリのサイズにかかわらずほぼ一定です。L1 キャッシュは最大 10,000 件で、LRU 方式で追い出されます。

メモリ使用量（v2 エンジン）

リポジトリのサイズ	ディスク上のベースライン	常駐メモリ（mmap）
小規模（<1K シンボル）	約1～5 MB	約5～20 MB
中規模（10K シンボル）	約20～50 MB	約30～80 MB
大規模（100K+ シンボル）	約200～500 MB	約300～600 MB

mmap ページは OS によって必要に応じて読み込まれるため、常駐メモリはインデックス全体のサイズではなく、実行したクエリに応じた量にとどまります。

アイドル時のプロセスメモリ（v2.10.0+）

サーバープロセスは、インデックスの構築に使った Roslyn のデータも保持しています。v2.10.0 以降は、アイドル時にそのメモリを解放します。インデックス作成から 2 分後に圧縮 GC を 1 回実行し、オーバーレイ更新用にキャッシュされたソリューションは、更新がない状態が 10 分続くと破棄されます。アイドル状態のサーバー 1 台のプライベートメモリの測定値 （PHASE-21-12、docs/benchmarks/phase-21-12/）：

リポジトリ	v2.9.0、アイドル時	v2.10.0、アイドル 2.5 分後	v2.10.0、アイドル 13 分後
eShopOnWeb	363 MB	218 MB	—
Bitwarden server	723 MB	342 MB	352 MB
nopCommerce	2,922 MB	1,116 MB	204 MB

各サーバーは、ワーキングセット、プライベートバイト数、GC ヒープを示す MEMORY_SNAPSHOT の行を ~/.codemap/logs に記録します。

---

28 個の MCP ツール。トークンを 90% 以上節約。Roslyn 品質のセマンティクス。C#、VB.NET、F#、Blazor/Razor。DLL 境界をまたいだナビゲーション。.sln + .slnx の自動検出。v2.10.0 — エージェント間で安全に使える破壊的ツール、アイドル時のメモリ解放、Razor コンポーネントとビューの参照、正確な config.json。dotnet/roslyn（174K シンボル）、dotnet/fsharp（157K シンボル）、および Blazorise、MudBlazor、ant-design-blazor、OrchardCore を含む 9 つのリポジトリから成る Blazor コーパスで検証済みです。あなたのエージェントには grep より優れたツールが必要です。