Codegraph Rust

CodeGraph（更新情報）

コードベースを理解する。

ヒント

コーディングエージェントに、プロジェクトの記憶を持たせましょう。

CodeGraph Agent Memoryをご紹介します。 CodeGraph を基盤に、アーキテクチャ上の意思決定、調査結果、失敗したアプローチ、再利用可能な手順を永続的な記憶として保持する姉妹プロジェクトです。記憶の検索を有効にすると、セッションをまたいで、現在のコードに関する証拠とともにその知識をエージェントのワークフローに取り込めます。

エージェントメモリーガイドを見る →

CodeGraph はコードベース全体を、AI エージェントが単に grep で検索するだけでなく、実際に推論できる、意味的に検索可能なナレッジグラフに変換します。

さっそく始めますか？ 手順に沿ってセットアップするには、インストールガイドをご覧ください。

セットアップは済んでいますか？ AI アシスタントで CodeGraph を最大限に活用するヒントについては、使用ガイドをご覧ください。

シェルコマンドを使いますか？ codegraph agent context "your question"を実行してください。同じ4つのエージェント用ツールをCLI とプロジェクトローカルの Claude Code／Codex フックから利用できます。 codegraph initではフックをセットアップでき、インデックス作成前にエージェント向けの指示を追加します。

---

課題

AI コーディングアシスタントは強力ですが、状況を把握できていません。ファイルを1つずつ見て、パターンを grep で検索し、アーキテクチャを理解するためにトークンを浪費しています。会話は毎回ゼロから始まります。

AI アシスタントが、すでにコードベースを理解していたらどうでしょうか？

---

CodeGraph が異なる点

1. グラフ + 埋め込み = 真の理解

多くのセマンティック検索ツールは、埋め込みを生成してそれで終わりです。CodeGraph は実際のナレッジグラフを構築します。

Your Code → Build Context → AST + FastML → LSP Resolution → Enrichment → Graph + Embeddings
              ↓               ↓              ↓              ↓              ↓         ↓
          Packages        Nodes/edges    Type-aware     API surface      Graph    Semantic
          Features        Fast patterns  linking        Module graph   traversal   search
          Targets         Spans          Definitions    Dataflow/Docs             (hybrid)

検索すると、単に「似たコード」が得られるのではなく、関係性が保たれたコードが得られます。クエリに一致する関数だけでなく、その関数を呼び出すコード、依存先、アーキテクチャ内での位置も確認できます。

インデックス作成時の拡充により、次の情報が追加されます。

• ファイルをまたいだナビゲーションのためのモジュールノードと、モジュールレベルのインポート／包含エッジ
• 影響分析のための Rust のローカルなデータフローエッジ（defines、uses、flows_to、returns、mutates）
• README.md、docs/**/*.md、schema/**/*.surql内のバッククォートで囲まれたシンボルにリンクされたドキュメント／仕様ノード
• アーキテクチャ上のシグナル（パッケージ循環 + 任意の境界違反）

インデックス作成のティア（速度と情報の豊富さ）

インデックス作成はティア制になっているため、速度とストレージ使用量、グラフの情報の豊富さのバランスを選べます。デフォルトは fast です。

ティア	有効になる機能	一般的な用途
fast	AST ノードと基本的なエッジのみ（LSP やエンリッチメントなし）	すばやいインデックス作成、ストレージ使用量の削減
balanced	LSP シンボルとドキュメント／エンリッチメント、モジュールのリンク	アナライザーの負荷を適度に抑えながら、ナビゲーションとドキュメントを充実
full	すべてのアナライザー、LSP 定義、データフロー、アーキテクチャ	グラフの情報量とアナライザーの網羅性を最大化

エージェントの回答精度は別途評価されます。詳しくはCLI の精度結果を参照してください。

ティアの動作の詳細：

• fast：ビルドコンテキスト、LSP、エンリッチメント、モジュールのリンク、データフロー、ドキュメント／コントラクト、アーキテクチャを無効にし、Uses／References エッジを除外します。
• balanced：ビルドコンテキスト、LSP シンボル、エンリッチメント、モジュールのリンク、ドキュメント／コントラクトを有効にし、References エッジを除外します。
• full：すべてのアナライザーと LSP 定義を有効にし、エッジのフィルタリングは行いません。

ティアを設定する方法：

• CLI：codegraph index /path/to/project --index-tier balanced
• 環境変数：CODEGRAPH_INDEX_TIER=balanced
• 設定：[indexing] tier = "balanced"

ディレクトリのインデックス作成ではデフォルトでサブディレクトリもスキャンされるため、 codegraph index --languages Rust --index-tier balanced . を実行すると、ワークスペースのクレート内にある Rust ソースが見つかります。意図的にルートディレクトリだけをスキャンする場合は --no-recursive を使用してください。-r／--recursive も引き続き使用できます。 codegraph estimate も同じデフォルトの走査方法を使用します。

インデックス作成の前提条件（LSP を有効にするティア）

ティアで LSP（balanced／full）が有効になっている場合、必要な外部ツールがないとインデックス作成は即座に失敗します。 Rust のインデックス作成では、解析の前に対象プロジェクトで rust-analyzer --version も実行します。 rustup のシムが存在していても、アクティブなツールチェーンにコンポーネントが含まれているとは限りません。 rustup を使用している場合は、そのプロジェクトのディレクトリで rustup component add rust-analyzer を実行し、 続けて rust-analyzer --version で確認してください。言語サーバーのエラーでは、stderr の末尾 4 KiB が保持されるため、起動時および実行時のエラーにサーバーの診断情報が含まれます。

言語ごとに必要なツール：

• Rust：rust-analyzer
• TypeScript/JavaScript：node と typescript-language-server
• Python：node と pyright-langserver
• Go：gopls
• Java：jdtls
• C/C++：clangd

ウォーム状態の言語サーバーセッションでは、バージョン管理されたドキュメントが保持され、定義リクエストの重複排除とパイプライン処理が行われます。 シンボルおよび定義のリクエストでは、一時的な ContentModified （-32801）応答に対して、30 秒の期限内にバックオフを挟み、最大 5 回まで再試行します。 ドキュメントのバージョンが変更された場合、再試行回数を使い切った場合、またはその他のエラーが発生した場合は、インデックス作成に失敗します。その際、診断情報にはリクエストのメソッドとファイル URI が含まれます。CODEGRAPH_LSP_REQUESTS はサーバーごとの未処理リクエスト数に上限を設定します（デフォルトは 32）。CODEGRAPH_ANALYZERS=0 を設定すると、ティアとは独立してアナライザーが無効になります。LSP の代わりにコンパイラーインデックスを使用するには CODEGRAPH_SCIP_INDEX=/path/index.scip を設定してください。ソースの検証とサイドカーの要件については、インデックス作成の実装ガイドで説明しています。

インクリメンタルインデックス作成と推論ポリシー

--batch-size は、ローカルプロバイダーとクラウドプロバイダーの両方について、バッチあたりの埋め込みテキスト数の上限を設定します。明示的に指定した値は、CODEGRAPH_EMBEDDINGS_BATCH_SIZE、その旧エイリアスである CODEGRAPH_EMBEDDING_BATCH_SIZE、TOML の [embedding] batch_size よりも優先されます。優先順位はこの順で、デフォルトは 64 です。メモリに基づく調整によって明示的な値が変更されることはありません。--batch-size 100 も同様です。

codegraph index --languages Rust --index-tier balanced --batch-size 512 .

トークン／バイトの予算、キャッシュヒット、プロバイダー API の制限によって、実際のリクエストが小さくなる場合があります。より大きなリクエストを送信するには、必要に応じて CODEGRAPH_EMBEDDING_BATCH_TOKENS（デフォルトは、解決済みの入力コンテキスト以上で、ローカル／リモートの下限はそれぞれ 8192／32768）と CODEGRAPH_EMBEDDING_BATCH_BYTES（デフォルトは 1 MiB）を調整してください。 ログでは、推論の上限とデータベース書き込みのバッチが別々に表示されます。CODEGRAPH_CHUNK_DB_BATCH_SIZE のデフォルトは最大 32 行で、上限は 512 です。 Ollama と LM Studio には、追加の固定テキスト数上限 256 はありません。

全体、単一ファイル、監視インデックス作成では、完全なプロジェクトの照合処理が共有されます。変更されていないソースでは、キャッシュされた AST／アナライザーの成果物が再利用されます。一方、完全なカタログによって、編集、名前変更、削除後も呼び出し元の情報が保持されます。書き込まれるのは、変更されたグラフレコードとファイルメタデータのみです。ソーススナップショット、解析、推論、書き込みキューにはそれぞれ独立したリソース上限があります。完了は、永続化の確認応答と最終的な入力チェックの後に行われます。 --force を指定すると、前のカタログを信頼せずに再度準備と照合を行います。

埋め込み処理と意味解決処理は、抽出ティアから独立しています。それぞれ sync（機能がコンパイルされている場合のデフォルト）、deferred、off を指定できます。

CODEGRAPH_EMBEDDING_POLICY=deferred CODEGRAPH_SEMANTIC_RESOLUTION=off \
  codegraph index /path/to/project --index-tier fast --stats-json indexing.json
codegraph index /path/to/project --complete-deferred --stats-json completed.json

遅延実行では、再開可能なジョブが保存され、グラフの準備完了と推論待ちが区別されます。準備済みテキストの埋め込みキャッシュには、モデル／タスク／トークナイザー／ランタイムの識別情報が含まれます。チャンク分割では Unicode を保持し、プロバイダーのトークン予算が適用されます。変更可能なモデルエイリアスには有効期限があります。CODEGRAPH_MODEL_REVISION では、変更されないリビジョンを指定します。

埋め込み入力とチャンク分割

チャンク計画は、関数やクラスなど、AST ノードのソース範囲を基準に開始します。入力予算内に収まる単位は分割せず、そのまま保持します。予算を超える単位は、Tree-sitter の文／ブロック境界で分割し、収まる隣接部分を結合します。大きすぎるリーフノードや未対応の構文には、UTF-8 に対応した行／トークン分割を使用します。 Unicode と構造上の空白は保持され、オーバーラップの計算にはトークン数を使用します。

Ollama の予算は、モデルメタデータとサービングコンテキストに基づきます。Qwen3 の埋め込みモデルは32K 入力に対応しています。 nomic-embed-text-v2-moe は 512 トークンに対応しています。カウントには、ドキュメント／クエリのプレフィックスと特殊トークンが含まれます。 Nomic のテキストモデルには search_document: ／search_query: が付与されます。Qwen3 のクエリには検索用の指示が付与されます。すべての Ollama リクエストでは truncate=false を使用します。コンテキストの不一致は、ソースが暗黙に切り捨てられるのではなく、明示的なエラーになります。

認識されたモデルでは、対応する公開元のトークナイザーが自動的に読み込まれ、tokenizer.json がキャッシュされます。ファイルが存在しない場合は、初回使用時にダウンロードされます。モデルの重みはダウンロードされません。カスタムモデルやオフラインモデルでは CODEGRAPH_TOKENIZER_PATH を指定できます。不明なモデルでは、このパスまたは CODEGRAPH_TOKENIZER_REPO が必要です。

制御項目	動作
CODEGRAPH_CHUNK_MAX_TOKENS	入力全体の目標値を下げます。上限はサービングコンテキストによって制限されます。従来の CODEGRAPH_MAX_CHUNK_TOKENS の優先度は低くなります。
CODEGRAPH_CHUNK_SMART_SPLIT=0	サイズ超過の単位を AST の境界ではなく、トークン単位で分割します。デフォルト：AST 分割。
CODEGRAPH_CHUNK_OVERLAP_TOKENS	トークン単位の末尾の重複部分の最大値です。デフォルトは 64 で、0 にすると無効になります。次の入力に収まるよう縮小されます。
CODEGRAPH_EMBEDDING_SKIP_CHUNKING=1	ノードを分割せずに保持します。いずれかのノードが設定された入力上限を超える場合、推論の前に失敗します。
CODEGRAPH_OLLAMA_NUM_CTX	モデルの最大値を上限として、リクエストのコンテキストを設定します。それ以外の場合は、報告されていれば Modelfile／実行中のコンテキストを使用します。
CODEGRAPH_MODEL_MAX_TOKENS	欠落しているモデルのコンテキストメタデータを補うか、公開されている最大値を下げます。
CODEGRAPH_TOKENIZER_PATH	ダウンロードせずに、一致するローカルの tokenizer.json を使用します。
CODEGRAPH_TOKENIZER_REPO、CODEGRAPH_TOKENIZER_REVISION	発行元のトークナイザーリポジトリ／リビジョンを上書きします。デフォルトのリビジョンは main です。
CODEGRAPH_EMBEDDING_DOCUMENT_PREFIX、CODEGRAPH_EMBEDDING_QUERY_PREFIX	カスタムモデルの検索用プレフィックスを上書きします。

--batch-size は、チャンクの長さとは独立して、推論リクエストごとのテキスト数を制御します。 デフォルトのリクエストトークン予算は、解決された入力コンテキストに合わせて増加します （ローカルの下限は 8192、リモートの下限は 32768）。明示的に指定した CODEGRAPH_EMBEDDING_BATCH_TOKENS と CODEGRAPH_EMBEDDING_BATCH_BYTES は引き続き別々の上限として扱われます。入力が いずれかの上限を超えると、その上限を引き上げるかチャンクの目標値を下げるよう案内して失敗します。

アップグレード後は再インデックスしてください。トークナイザー／タスク／コンテキストやチャンクポリシーの変更により、 古いアーティファクトと埋め込みは無効になります。オフラインのモックでは準備処理とリクエスト上限を検証できますが、 検索品質とインデックス作成速度は、引き続きプロジェクトで測定する必要があります。

CODEGRAPH_VECTOR_INDEX_MODE=all|selected|deferred|off は、新しい埋め込みストアの HNSW 構築を制御します。 デフォルトではすべてのスキーマ次元が保持されます。selected はアクティブな次元を構築し、deferred は永続的な取り込み後に構築し、off はベクターの準備状態を false として報告します。既存の共有インデックスは保持されます。別の分割方式、候補数の上限、実行時／精度の選択肢は、引き続きオプトインです。

設定と不変条件および 再現可能な速度／品質ベンチマークを参照してください。オフラインのデバッグ用 フィクスチャの結果では動作を検証できますが、本番環境のスループットとモデル品質の評価には、 代表的な条件での測定が必要です。

セマンティック関係のスコアリングでは、ベクトルノルムをキャッシュし、未解決の名前を個別にスコアリングします。この処理は、既存のワーカー数制限付き CPU プールで行われ、非同期ランタイムのワーカーの外部で実行されます。 候補の順序、コサイン閾値、曖昧な同点の処理は変更されません。--stats-json では、関係解決中の完全一致／字句一致、セマンティック候補の選択、シンボルの埋め込み、 CPU スコアリング、エッジの準備／書き込みが個別に表示されるようになりました。

LSP による解決が直ちに失敗し、エラーに Unknown binary 'rust-analyzer' in official toolchain ... のような内容が含まれる場合、rust-analyzer はインストール済みのバイナリがない rustup シムです。実行可能な rust-analyzer をインストールするか（例：brew install rust-analyzer）、それを提供するツールチェーンに切り替えてください。

オプションのアーキテクチャ境界ルール

CodeGraph で禁止されたパッケージ依存関係を検出するには、プロジェクトのルートに codegraph.boundaries.toml を追加します。

[[deny]]
from = "your_crate"
to = "forbidden_crate"
reason = "explain the boundary"

インデックス作成時に、depends_on 関係が拒否ルールに一致すると violates_boundary エッジが出力されます。

2. 検索だけではないエージェント型ツール

CodeGraph はファイルの一覧を返して、あとは運任せにするわけではありません。考える処理を担う4 つの統合型エージェントツールを提供します。

ツール	実際の機能
agentic_context	必要なコンテキストを収集します。コードを検索し、包括的なコンテキストを構築し、意味に関する質問に答えます
agentic_impact	変更の影響をマッピングします。依存関係の連鎖、呼び出しフロー、何かを変更した場合にどこが壊れるかを示します
agentic_architecture	全体像を示します。システム構造、API の表面、アーキテクチャパターンを確認できます
agentic_quality	リスクを評価します。複雑さのホットスポット、結合度の指標、リファクタリングの優先順位を示します

各ツールは、必要に応じて精度を高めるための任意の focus パラメーターを受け付けます。

ツール	Focus の値	デフォルトの動作
agentic_context	"search", "builder", "question"	クエリに基づいて自動選択します
agentic_impact	"dependencies", "call_chain"	両方を分析します
agentic_architecture	"structure", "api_surface"	両方を提示します
agentic_quality	"complexity", "coupling", "hotspots"	包括的に評価します

各ツールは、計画を立て、検索し、グラフの関係を分析して回答をまとめる推論エージェントを実行します。検索結果ではなく、回答を返します。

エージェントによるコンテキスト収集フローを表示 - エージェントがグラフツールを使ってコンテキストを収集する仕組みを示すインタラクティブな図です。

エージェントのアーキテクチャ

CodeGraph のエージェントはRigフレームワークを基盤としています。実行するエージェントは、CODEGRAPH_AGENT_ARCHITECTURE（.env または環境変数）で実行時に選択します。

• react（デフォルト。エイリアスとして rig も使用できます）：グラフツールを使ったツール呼び出しのループです。
• lats：ReAct と同じグラフツールを呼び出す候補をツリー検索します。各ブランチは独自の観測結果を保持し、評価器はその証拠に基づいて採点します。選択されたブランチが回答を提供します。成功したグラフ観測がない場合、実行は失敗します。
• reflexion：ReAct を、前回のエラーをエージェントにフィードバックする再試行でラップします。

どのエージェントを選択しても、実行に失敗すると、エラーをコンテキストとして自動的に再試行します。

# Default: ReAct
./codegraph start stdio

# Tree search with graph-tool grounding
CODEGRAPH_AGENT_ARCHITECTURE=lats ./codegraph start stdio

すべてのエージェントは、同じ 4 つの統合型エージェントツールを提供し、ティアを考慮したプロンプトを使用します。 LATS は展開ごとに 3 つの候補を探索し、評価器の呼び出しも行うため、ReAct よりコストがかかり、時間も長くなる場合があります。ティア別の予算により、検索の展開回数、深さ、および各候補のツールループが制限されます。候補は実行全体の結果サイズ予算を共有します。 CLI にはワークフロー全体の制限時間も適用されます。アーキテクチャと制限を参照してください。

3. ティアに応じたインテリジェンス

便利な仕組みがあります。CodeGraph は、codegraph エージェントに設定した LLM のコンテキストウィンドウに応じて、動作を自動的に調整します。

小規模なローカルモデルを実行していますか？焦点を絞った効率的なクエリが得られます。

200K のコンテキストを持つモデルを使用していますか？包括的で探索的な分析が得られます。

1～2M のコンテキストを持つ gpt-6、Opus-5.5、または Grok-4.7 を使用していますか？インテリジェントな結果管理を備えた詳細な分析が得られます。

エージェントは、回答を生成するために必要なステップ数だけを使用するため、ツールの実行時間はクエリとデータベースにインデックス化されたデータ量によって異なります。

開発中、エージェントはテストシナリオの回答生成に平均3～6ステップを使用しました。

エージェントはステートレスです。ツールの実行中のみ会話メモリを保持し、連鎖した複数のツール呼び出しにわたってコンテキストやメモリを蓄積しません。コンテキストの蓄積は選択したクライアントがすでに処理するため、CodeGraph は回答を提供するだけで済みます。

使用モデル	CodeGraph の動作
50K トークン未満	簡潔なプロンプト、最大3ステップ
50K～150K	バランスの取れた分析、最大5ステップ
150K～500K	詳細な探索、最大6ステップ
500K 超（gpt-6 など）	包括的な分析、最大8ステップ

上限： ティアにかかわらず、最大8ステップです。これにより、徹底した分析を可能にしながら、コストの肥大化やコンテキストのオーバーフローを防ぎます。

同じツールが、設定に合わせて自動的に最適化されます。

4. コンテキストのオーバーフロー保護

エージェントが受け取った各ツール結果は、その後の各ラウンドでモデルに再送されます。そのため CodeGraph は、1回の実行でモデルのコンテキストに含められる内容を、次の3つのレベルで制限します。

コンテンツスニペット。 結果行の長い content（ドキュメント全体や impl ブロックなど）は、先頭部分のスニペット（デフォルトで2,000文字）に切り詰められ、元の長さとともに content_truncated としてマークされます。行にはファイルパスと行範囲が保持されるため、クライアントは残りの内容を読み取れます。

結果ごとの上限。 1つのツール結果は context_window × 2 バイトまでに制限されます。ただし、ウィンドウがどれほど大きくても上限は200 KBです。サイズ超過した配列の結果は先頭の項目を保持し、_truncated メタデータが付与されます。

実行ごとの予算。 1回のエージェント実行におけるすべてのツール結果は、コンテキストウィンドウの約3分の1（トークンあたり4バイトとして計算）、48 KB～600 KBの範囲で予算を共有します。残りの予算を超える結果は収まるように切り詰められ、_budget の注記が付与されます。予算を使い切ると、それ以降の呼び出しは、これまでに得た根拠に基づいて回答するようエージェントに伝える注記を返します。

環境変数で設定：

# Set this to match your agent LLM's real context window
CODEGRAPH_CONTEXT_WINDOW=128000            # default: 128K

# Optional overrides
CODEGRAPH_TOOL_CONTENT_CHARS=2000          # snippet length per row; 0 disables shortening
CODEGRAPH_AGENT_RESULT_BUDGET_BYTES=400000 # per-run tool-result budget

これが重要な理由： このリポジトリのフルティアのインデックスでは、これらの制限を適用する前のセマンティック検索1回で228 KBが返される場合があります。1回の実行で検索を12回行うと、モデル呼び出しが停止するまでに、各モデルリクエストへ数メガバイトが送られてしまいます。

5. 実用的なハイブリッド検索

「埋め込み対キーワード」の議論で、どちらか一方に肩入れすることはありません。CodeGraph は次の要素を組み合わせます。

• 70％のベクトル類似度（意味の理解）
• 30％の字句検索（完全一致も重要です）
• グラフ探索（関係性とコンテキスト）
• 任意の再ランキング（クロスエンコーダーによる精度向上）

その結果、「login logic」で検索しても handleUserAuth が見つかり、「handleUserAuth」で検索しても見つかります。

---

AI コーディングにおいて重要な理由

CodeGraph を Claude Code、Cursor、または MCP 互換エージェントに接続すると、次のようになります。

導入前： AI はファイルを1つずつ読み、grep であちこちを検索しながら、コンテキスト収集にトークンを消費します。

導入後： AI は agentic_impact({"query": "UserService"}) を呼び出すだけで、リファクタリング時に何が壊れるかをすぐに把握できます。

これは段階的な改善ではありません。コードを 検索する AI と、コードを 理解する AI の違いです。

コーディングエージェントにとって強力な理由

CodeGraph は、認知負荷（検索＋関連性判断＋依存関係の推論）を CodeGraph のエージェント型ツールに移します。これにより、コーディングエージェントはコンテキストの予算を、変更内容の 発見 ではなく、変更の実施 に使えます。

エージェント型ツールが返すもの (例)

agentic_impact は構造化された出力 (ファイルパス、行番号、範囲を限定したスニペット/ハイライト) と分析結果を返します:

{
  "analysis_type": "dependency_analysis",
  "query": "RigAgentBuilder",
  "structured_output": {
    "analysis": "…what depends on RigAgentBuilder and why…",
    "highlights": [
      { "file_path": "crates/codegraph-mcp-rig/src/agent/builder.rs", "line_number": 48, "snippet": "pub struct RigAgentBuilder { … }" }
    ],
    "next_steps": ["…"]
  },
  "steps_taken": "5",
  "tool_use_count": 5
}

コードエージェントがそうでなければ行う必要があること

CodeGraph のエージェント型ツールがなければ、コードエージェントは通常、同じ確信度に到達するために複数の「単一目的」の呼び出しを必要とします:

• シンボルを検索する (多くの場合、複数の戦略: テキスト + セマンティック + ripgrep 風の検索)
• 複数のファイルを開いて読む (定義 + 使用箇所 + 呼び出し元 + 関連モジュール)
• 部分的な証拠から依存関係/呼び出しグラフを頭の中で再構築する
• 推測が外れたら繰り返す (さらに読み込み、さらにトークンを消費)

これはコンテキストを急速に消耗します: 「ほんの」中規模のファイルをいくつか読むだけでも、周辺のコンテキストを含めれば数万トークンを容易に消費し、大規模なリポジトリでは、どれだけのコードがコンテキストに取り込まれるかによって数十万トークンに達することもあります。

CodeGraph を使えば、エージェントは的確な位置と関係性 (および範囲を限定したコンテキスト) を取得でき、コンテキストウィンドウのはるかに多くの部分を計画と変更の実装のために確保できます。

---

クイックスタート

1. インストール

# Clone and build with all features
git clone https://github.com/Jakedismo/codegraph-rust
cd codegraph-rust
./install-codegraph-full-features.sh

macOS でのより高速なビルド (LLVM lld)

macOS で開発する場合、より高速なリンクのために LLVM の lld リンカーを利用できます:

# Install LLVM so ld64.lld is on PATH (Homebrew)
brew install llvm

# Use the repo-provided Makefile targets
make build-llvm
make test-llvm

2. プロバイダーを設定する

CodeGraph は、インデックス作成用の埋め込みモデルと、エージェント型ツール用の LLM を必要とします。設定はプロジェクト内の .env ファイルに記述するか (またはエクスポートし) てください。codegraph init がそれを読み込みます。

# Embeddings
CODEGRAPH_EMBEDDING_PROVIDER=ollama          # ollama | lmstudio | jina | openai | onnx
CODEGRAPH_EMBEDDING_MODEL=qwen3-embedding:0.6b
CODEGRAPH_EMBEDDING_DIMENSION=1024

# Agent LLM
CODEGRAPH_LLM_PROVIDER=anthropic             # ollama | lmstudio | anthropic | openai | xai | openai-compatible
CODEGRAPH_LLM_MODEL=claude-sonnet-4
CODEGRAPH_CONTEXT_WINDOW=200000              # your model's real limit; selects the prompt tier
ANTHROPIC_API_KEY=sk-ant-...

モデルは明示的に設定してください。設定しない場合、エージェントはプロバイダーの組み込みデフォルトを使用します。同じ設定は、代わりに設定ファイルの [llm] セクションに記述することもできます (設定 を参照)。環境変数が優先されます。.env.example には対応するすべての変数が一覧されており、AI_PROVIDERS.md にはプロバイダーごとの例があります。

Jina v5 の埋め込みには、対応している検索タスクを使用してください:

CODEGRAPH_EMBEDDING_PROVIDER=jina
CODEGRAPH_EMBEDDING_MODEL=jina-embeddings-v5-text-small
CODEGRAPH_EMBEDDING_DIMENSION=1024
JINA_API_KEY=...
JINA_API_TASK=retrieval.passage
JINA_TRUNCATE=true
JINA_NORMALIZED=true

明示的な JINA_API_TASK=retrieval.query も尊重されます。JINA_API_TASK は従来の JINA_TASK および TOML の [embedding] jina_task より優先されます。タスクを設定しない場合、v3/v5 では retrieval.passage、v4 では code.passage がデフォルトとなり、検索には対応するクエリタスクが使用されます。v5 は Jina の API スキーマ に記載されているとおり、retrieval、text-matching、classification、clustering タスクに対応しています。HTTP 422 のような恒久的な埋め込み API エラーは、詳細とともに即座に失敗します。一時的な失敗はリトライが維持されます。タスクやリクエストオプションを変更した後は、以前のポリシーで生成されたベクトルを置き換えるために再インデックスしてください。

任意のリランキングはクエリ時にセマンティック検索の結果を絞り込み、埋め込みとは異なるプロバイダーを使用できます。Jina の場合、これを .env に記述します:

CODEGRAPH_RERANK_PROVIDER=jina
JINA_API_KEY=...
# JINA_RERANKING_MODEL=jina-reranker-v3  # default; no model setting required
# JINA_RERANKING_TOP_N=10

または、プロバイダーを .codegraph.toml で選択します。そのネストされた設定は任意です:

[rerank]
provider = "jina"  # jina | ollama | none
top_n = 10

# [rerank.jina]
# model = "jina-reranker-v3"
# api_key_env = "JINA_API_KEY"
# api_base = "https://api.jina.ai/v1"

Ollama の場合は、CODEGRAPH_RERANK_PROVIDER=ollama を使用し、必要に応じて CODEGRAPH_OLLAMA_RERANK_MODEL と CODEGRAPH_OLLAMA_URL を設定します。Jina の JINA_API_BASE もそのリランキングエンドポイントを上書きします。環境設定は TOML より優先されます。CODEGRAPH_RERANK_PROVIDER は従来の JINA_ENABLE_RERANKING トグルを上書きし、CODEGRAPH_ENABLE_RERANKING=false はすべてのリランキングを無効にします。従来の CODEGRAPH_RERANKING_CANDIDATES は top_n を上書きし、これはリランキング後に保持される結果を制御します。解決されたプロバイダー/モデルは codegraph config show --json で確認してください。先頭のドットがないファイルには --config codegraph.toml または CODEGRAPH_CONFIG_PATH=codegraph.toml を使用してください。リランカーへの変更は CLI またはサーバーを再起動した後に有効になり、再インデックスは不要です。

3. データベース

起動するものはありません。SurrealDB は codegraph 内で組み込みで動作し、各プロジェクトには <project>/.codegraph/db に専用の SurrealKV ストアが作成されます。初回のインデックス作成時に、同梱のスキーマ（schema/codegraph_v2.surql）を使って作成されます。このディレクトリには .gitignore が書き込まれるため、バージョン管理の対象になりません。

ストアはプロジェクトごとに分かれているため、あるプロジェクトのデータが別のプロジェクトのデータと混ざることはありません。プロジェクトのインデックスを削除するには、rm -rf <project>/.codegraph/db を実行します。

プロジェクトのストアを同時に開けるプロセスは 1 つだけです。MCP サーバーは最初のツール呼び出し時にストアを開き、終了するまで開いたままにするため、同じプロジェクトで codegraph index を実行する前に、実行中の codegraph start を停止してください。また、プロジェクトごとに接続するクライアントは 1 つにしてください。

1 つのデータベースをチームで共有したい場合は、共有 SurrealDB サーバー（セルフホストまたは Surreal Cloud）も引き続き利用できます。CODEGRAPH_SURREALDB_URL を設定し、スキーマを自分で適用してください。SurrealDB のセットアップを参照してください。

4. プロジェクトを初期化してインデックスを作成する

codegraph init /path/to/project

Init では最初に、プロジェクト単位のフックとして Claude Code、Codex、両方、またはなし を選択できます。既存の設定は保持され、CodeGraph のフックがすでに設定されている場合はプロンプトを省略します。次に、他の指示を保持したまま AGENTS.md と CLAUDE.md の両方に管理対象の # codegraph セクションを追加し、その後、プロジェクトを再帰的にインデックス化します。このガイダンスでは、エージェントに CodeGraph のコンテキスト、影響範囲、アーキテクチャ、品質に関する CLI ツールを使って調査を開始し、現在のソースコードと照らし合わせて結果を検証するよう指示します。

スクリプトから実行する場合は、フックの選択を明示的に指定してください。インデックスを作成せずにセットアップすることもできます。

codegraph init /path/to/project --hooks both --index-tier balanced
codegraph init /path/to/project --hooks none --no-index
# Existing index-only workflow, with explicit language filters:
codegraph index /path/to/project -r -l rust,typescript,python

--hooks none を指定すると、既存のフックをそのままにして、両方の指示ファイルを更新します。セットアップによってユーザーレベルのハーネス設定が変更されることはありません。codegraph がハーネスの PATH に含まれていることを確認し、セットアップ後にプロジェクトのフックを再読み込みして確認してください。詳細はinit とフックの詳細を参照してください。

インデックス作成後、python3 test_cli_agentic.py を実行すると、test_http_mcp.py と同じ 8 つの質問で 4 つすべての CLI エージェントツールをテストし、完全な回答を表示して、応答と所要時間を test_output_cli/ に保存します。新しい問い合わせを行わずに保存済みの回答を再生するには、python3 test_cli_agentic.py --replay test_output_cli を実行します。CLI のテストオプションを参照してください。

🔒 セキュリティに関する注意： インデックス作成では .gitignore が自動的に適用され、一般的なシークレットのパターン（.env、credentials.json、*.pem、API キーなど）が除外されます。シークレットが埋め込まれたり、エージェントに公開されたりすることはありません。

5. Claude Code に接続する

MCP 設定に追加します：

{
  "mcpServers": {
    "codegraph": {
      "command": "/full/path/to/codegraph",
      "args": ["start", "stdio", "--watch"]
    }
  }
}

これで完了です。 AI がコードベースを理解できるようになります。

---

インデックス作成ティアごとのエージェント CLI の精度

CLI 評価では、agentic_test_cases.py で定義されている HTTP MCP テストと同じ 8 つの質問を使用します。質問は、4 つすべてのエージェントツールについて、設定の読み込み、プロンプトの選択、キャッシュ、依存関係、呼び出しチェーン、アーキテクチャ、公開 API、複雑さを網羅しています。test_cli_agentic.py は、ソースコードと手動で比較できるよう、完全な応答を保存します。

以下の高速エントリーは、現在のモデル対応トークナイザー／コンテキスト／チャンクポリシーより前のものです。今後ティアを比較する際は、現在の入力ポリシーとモデル設定を統一して使用してください。過去のエントリーは、その実行の記録として残されています。

インデックスの階層	LLM / リクエストモデル	評価日	CLI レスポンスチェック	手動による精度の所見
fast	gpt-6-luna (プロジェクトオーナーにより確認済み。ランナーでは取得されていない)	2026-10-06	8/8 OK	混在: 有用な所見もあるが、回答は不完全で、少なくとも2件はソースで確認された誤答。総合的な精度スコアは未割り当て
balanced (オリジナル)	gpt-6-luna (明示的なリクエストモデル)	2026-10-06	8/8 OK	設定/キャッシュ/呼び出しチェーンに関する有用な回答と公開メソッド一覧。直接呼び出し元の分類が誤り、ハブの結果が不完全、メトリクスの注意点あり。総合的な精度スコアは未割り当て
balanced (リフレッシュ版)	gpt-6-luna (明示的なリクエストモデル)	2026-10-06	8/8 OK	ハブのランキング、比率の計算、ラッパーの説明は修正済み。プロンプト/キャッシュ/呼び出しチェーンのカバレッジは不完全、API メソッドが1つ欠落。API ケースは587.5秒かかる。総合的な精度スコアは未割り当て
full (オリジナル)	gpt-6-luna (明示的なリクエストモデル)	2026-10-06	7/8 OK、1 TIMEOUT	ソースと整合した設定、キャッシュ、呼び出しチェーン、公開 API の回答で、位置も検証済み。欠落シンボルの代替としては弱い。ハブのランキングは利用不可で、不安定性の値は信頼できない。階層対応のプロンプトケースは2回タイムアウト。総合的な精度スコアは未割り当て
full (リフレッシュ版)	gpt-6-luna (明示的なリクエストモデル)	2026-10-06	8/8 OK	プロンプトの回答、ハブのランキング、不安定性の計算は現在動作。キャッシュの詳細は不完全、API メソッドが2つ欠落、古い LATS コメントが繰り返されている。アーキテクチャケースは546.4秒かかる。総合的な精度スコアは未割り当て

OK はコマンド/レスポンスの成功を測るものであり、事実の正確さを測るものではありません。 これは、コマンドが報告されたタイムアウトや部分結果のマーカーなしに有効な JSON 回答を返したことを意味します。内部のグラフツールがすべて成功することを要求するものではありません。8件の fast 階層のレスポンスは、事実の誤りがあったにもかかわらず、すべてこのチェックに合格しました。レスポンスフィールドの tier: Massive は、インデックスの階層とは独立に、エージェントのコンテキストウィンドウの予算を表します。

fast 階層の回答に対するソースレビューで判明した点:

• 呼び出しチェーン (ケース5): 有効な実装が誤っている。 回答は execute_agentic_workflow に対して #[cfg(not(feature = "ai-enhanced"))] のエラースタブを選び、ワークフローがグラフツールに到達しなかったと結論づけました。 AI 有効化された実装 は GraphToolExecutor を作成し、Rig エージェントエグゼキューターを呼び出します。回答は2つの条件付き実装を区別していませんでした。
• 公開 API (ケース7): API が不完全で、使用法の結論が誤っている。 回答は GraphToolExecutor には直接的な使用がないと述べ、変更は分離されており低リスクであると示唆しました。その公開メソッド にはコンストラクター、execute、キャッシュ制御、ツールメタデータアクセサーが含まれており、サーバーワークフロー と Rig ツールファクトリー の両方で使用されています。
• LRU キャッシュ (ケース3): 有用だが不完全。 回答は、関数とパラメーターによるツール結果のキャッシュを正しく特定しましたが、質問で求められたキャッシュヒット、ミス、エビクション、クリアの動作を説明していませんでした。
• 欠落シンボル (ケース4): 適切に不確実としている。 回答は PromptSelector の依存関係をでっち上げるのではなく、見つからなかったと報告しました。レビューしたソースには、その名前を持つ Rust の定義は存在しません。この質問は、結果を解釈する際にその注意点を必要とします。 バランス実行 20261006_041913_884481 では、CODEGRAPH_LLM_MODEL を通じて gpt-6-luna を明示的に選択しました。8つのコマンドはすべて 462.8秒 で回答を返しました。保存されたインデックスには、250個のファイル、22,496個のノード、48,224本のエッジ、22,496個のチャンクが報告されており、埋め込みとセマンティックの各ステージは準備完了でした。Ollama の qwen3-embedding:0.6b を使用し、ベクトルの次元数は1,024、解決されたサービングコンテキストは32,768トークンでした。 完全なバランス回答、実行の詳細、ソースレビューは、README の概要とは別に保存されています。

明示的なモデルを指定した元のバランス回答をソースレビューした結果、次の点がわかりました。

• 設定、プロンプト、キャッシュ（ケース1～3）：ソースに沿った有用な説明です。 複数の設定システム、dotenv/TOML の優先順位、アクティブな Rig プロンプトビルダー、キャッシュのヒット／ミス、成功結果の挿入、削除、クリア、TTL がないことを回答で説明しています。また、プロンプトに関する回答では、サーバーと Rig の階層解決パスが別々であることも指摘しています。8ラウンドの「ハードキャップ」という主張には補足が必要です。公開ビルダーのオーバーライドでは、別の値も受け付けています。
• 存在しないシンボルと呼び出しチェーン（ケース4～5）：適切な留保を含み、アクティブなフローを説明しています。 回答は PromptSelector を捏造せず、別の対象を示し、AI が有効な場合のワークフローと機能が無効な場合のスタブを区別しました。アクティブなパスを、Rig ツール、CountingExecutor、GraphToolExecutor、GraphFunctions を経て SurrealDB に至るまで追跡しています。
• 公開 API（ケース7）：メソッド名はすべて正しいものの、呼び出し元の分類が誤っています。 回答は公開されている10個の固有メソッドをすべて列挙し、実際の利用者も認識していました。しかし、8つの Rig ツールアダプターを GraphToolExecutor::execute の直接の呼び出し元としています。これらのアダプターが呼び出すのは CountingExecutor::execute であり、そこから GraphToolExecutor に処理が委譲されるため、アダプターは間接的な呼び出し元です。
• アーキテクチャ／メトリクス（ケース6～7）：OK という結果にもかかわらず、根拠が不十分です。 これらのケースでは、SurrealDB の array::concat() が1,048,576バイトの上限に達し、ハブのクエリが5回失敗しました。アーキテクチャに関する回答では、ハブのランキングが取得できなかったことを明かし、結合度の値に一貫性がないことや、構造体レベルのカウントが誤解を招くゼロ値になっていることを指摘しています。たとえば、Ca=19／Ce=66で不安定度が0.0という報告は、想定される Ce/(Ca+Ce) の比率と一致しません。これらのメトリクスから信頼できる安定性の結論を導くことはできません。
• 複雑度（ケース8）：測定上の限界を踏まえた、有用な報告ランキングです。 回答では reconcile_project が複雑度108／リスク1,404で第1位とされました。クエリは、複雑度の高い候補を事前に選んだうえで、複雑度 ×（入次数の依存エッジ数 + 1）としてリスクを計算します。これはヒューリスティックであり、調整済みの障害確率でも、全体を通じて保証されたリスクランキングでもありません。また、入次数のエッジ数が、重複を除いた呼び出し元の数と一致するとは限りません。

更新後のバランス実行 20261006_151920_418410 でも、gpt-6-luna を明示的に要求しました。8つのケースはすべて 1,053.3秒 で OK を返し、131回のツール呼び出しと合計177箇所が報告されました。新たに取り込んだインデックス（238個のファイル、21,832個のノード、43,266本のエッジ、23,387個のチャンク）、Jina の jina-embeddings-v5-text-small（1,024次元）、512トークンの AST チャンクポリシー、現在の600秒の期限を使用しました。 更新後のレビューと8件すべての新しい回答は、元の実行結果とともに保存されています。

• 検証済みの改善点: アーキテクチャのケースは、以前の array::concat の失敗なしでハブのランキングを返します。表示された 7 件の不安定度比率はすべて、丸め後に Ce/(Ca+Ce) と一致します。API の回答は、Rig アダプターが CountingExecutor を介した間接的なコンシューマーであることを正しく説明しています。8 つのコマンドで graph-tool の失敗や Jina 422 エラーは記録されていません。
• 残存する精度/カバレッジのギャップ: プロンプトの回答は、デフォルトのラウンド予算とプロンプトビルダーの詳細を省略しています。キャッシュの回答は、挿入/切り詰めの成功を立証できず、エビクション/クリアを省略しています。呼び出しチェーンは、ツールディスパッチの前の RigExecutor::new で停止します。これらの詳細は、元のバランスの取れた回答ではカバーされていました。API リストは graph_functions を省略しており、存在しないシンボルの回答には 1 行の誤ったインポート行があります。ホットスポットの算術は検証済みですが、回答は候補スコープと入力エッジ行の条件を省略しています。
• 残存するレイテンシ: API コマンドは 587.5 秒かかります。最初に完了した検索の後、次のツール呼び出しまでの間に、エージェント/モデルのターン中に 510.6 秒の記録されたギャップが発生します。プロバイダー側の原因は立証されていません。8 件の成功した応答は、レイテンシが解消されたことを立証するものではありません。
• 比較の限界: 今回の実行では、埋め込み、チャンクポリシー、バイナリ、インデックス内容、結果制限、および期限が変更されています。これらの同じ質問への回答を含む以前の評価ドキュメントが、ケース 1〜4 で取得されました。これはソースレビューを伴う運用スモークテストであり、ホールドアウトされた精度ベンチマークや、ティア効果の制御された測定ではありません。

元のフル実行 20261006_060847_378162 も gpt-6-luna を明示的に選択しました。7 つのコマンドが回答を返し、ケース 2(ティア対応プロンプト)は 300 秒の期限に達しました。この実行はそのタイムアウトを含めて 648.4 秒かかりました。保存されたインデックスは 238 ファイル、34,494 ノード、104,224 エッジ、34,494 チャンクを報告し、埋め込みおよびセマンティックステージが準備完了として完全とマークされており、データフロー、LSP、モジュール、ドキュメントアナライザーの出力を含んでいます。埋め込み設定は元のバランスの取れた実行と一致しています。完全な回答、実行の詳細、ソースレビューは別途保持されています。

この評価の後、デフォルトのエージェント全体の CLI 期限と、共有の CLI/HTTP テストケースの期限が 300 秒から 600 秒に増加しました。--timeout-secs は引き続き CLI 予算を上書きします。元のフルティアのテーブルエントリはその 300 秒の期限を保持しており、更新された完全な実行はどちらも 600 秒を使用しています。記録された元のストールは、グラフ呼び出しが返った後にモデル応答を待機している間に発生しました。

元のフルティアの回答のソースレビューにより、以下が判明しました:

• 設定、キャッシュ、呼び出しチェーン、パブリック API (ケース 1、3、5、7): ソースと整合しており、チェックしたすべての箇所が一致しています。 設定に関する回答は、メインローダー、dotenv の初期化、エージェントの [llm] オーバーレイ、MCP コアおよび高度な設定のローダー、JSON パイプラインローダー、および環境変数の直接読み取りを網羅しています。メインローダーの呼び出し元のリストは不完全です。キャッシュに関する回答は、ヒット、ミス、切り詰め後の挿入、エビクション、クリアを網羅していますが、1 つの行範囲が関数 1 つ分ずれています。呼び出しチェーンに関する回答は、機能が無効化されたスタブではなく、AI が有効なワークフローを追跡しています。API に関する回答は、10 個のパブリックメソッドをすべて列挙しており、元のバランス実行の回答とは異なり、Rig アダプターを CountingExecutor を介した間接的な呼び出し元として正しく説明しています。
• 階層対応プロンプト (ケース 2): 回答なし。 このコマンドは実行時および単一ケースの再実行時にタイムアウトしました。どちらも、エージェントは 1 分以内にツール呼び出しを完了し、残りの時間はモデルの応答を待つことに費やされました。原因は特定されていません。バランス実行では、このケースに 72 秒で回答しました。
• 存在しないシンボル (ケース 4): 不在について正直だが、代替が弱い。 回答は PromptSelector が存在しないと述べたうえで、 prompt_selection、 つまり codegraph init のフック選択プロンプトを分析していますが、これは階層プロンプトとは無関係です。その関数に関する記述は正しいです。
• アーキテクチャ (ケース 6): 構造は正確だが、ハブのランキングなし。 両方のハブクエリが、バランス実行と同じ array::concat() の 1,048,576 バイト制限で失敗し、このインデックス上で 関数 を直接呼び出しても同じ失敗が再現します。回答はこのギャップを開示し、発信依存関係を持つノードでは不安定性が 0.0 として報告される点を指摘しています。サンプリングした 5 つのノードに対する直接呼び出しはすべて 0.0 を返しました。この式 (現在は 修正済み) は 2 つの整数カウントを除算しており、整数除算では比率が切り捨てられます。 結合カウントは影響を受けませんが、安定性に関する結論は導けません。
• 複雑度 (ケース 8): 一貫した計算、異なるランキング。 20 個のリスクスコアはすべて複雑度 × (受信依存エッジ数 + 1) と一致します。パーサーの walk 関数が首位になり (Rust walker: 複雑度 31 と受信エッジ 100 からリスク 3,131)、reconcile_project は 8 位に下がりました。これは、完全なインデックスのエッジ数が 2 倍以上あり、クエリが呼び出し元の重複を除いた数ではなくエッジ行をカウントするためです。

ケース 2 のタイムアウト、ハブの失敗、0.0 の不安定性値は、現在は修正済みの欠陥に起因していました。ツール結果が無制限であり (1 回の検索で 228 KB を返すことがあり、実行に総量制限がありませんでした)、ハブクエリが array::concat のサイズ制限を超えており、不安定性比率が整数を除算していました。修正を適用して同じインデックス上でケース 2 と 6 を再実行したところ、79 秒と 106 秒で OK を返し、ハブのランキングと非ゼロの不安定性が得られました。その他のケースは再実行していません。詳しくは フォローアップセクションをご覧ください。

更新された完全実行 20261006_162918_871171 は明示的に gpt-6-luna を要求しました。 8 つのケースすべてが 901.8 秒で OK を返し、99 回のツール呼び出しと 合計 172 箇所でした。カタログには 239 ファイル、34,998 ノード、100,107 エッジ、36,600 チャンクが記録されており、LSP 定義とデータフロー出力を含みます。更新されたバランス実行と同じインストール済みバイナリ、Jina v5 の埋め込み/チャンクポリシー、エージェント設定を使用しています。更新された完全レビューと 8 つの回答すべては、元の完全実行と並んで残っています。

• 検証済みの改善点: プロンプトケースは82.9秒で返り、プロンプト構成、ビルダーの配線、および3/5/6/8のデフォルトラウンドバジェットをカバーするようになりました。ハブのランキングは成功し、表示される8件のアーキテクチャ不安定比はすべて Ce/(Ca+Ce) と一致します。グラフツールの失敗や Jina 422 エラーは記録されていません。存在しないシンボルに対する回答は、無関係なフックプロンプトで代用することを明示的に拒否しています。
• 残存する精度/カバレッジのギャップ: キャッシュの挿入/削除と切り詰め後のストレージは依然として未確立です。API リストには graph_functions と clear_cache が欠落しています。コールチェーンはグラフディスパッチに到達しますが、LATS はツールを使用できないとする古い enum コメントを繰り返しています。現在の実装では使用できます。そのコメント、環境例、インストールガイドは実行後に修正されましたが、保存された回答は変わっておらず、インデックスには依然として古いテキストが含まれています。
• 指標の但し書き: 結合度は隣接するグラフノードを重複排除しますが、ハブ次数とホットスポットリスクは依存エッジ行をカウントします。どちらも呼び出しだけでなくデータフロー関係を含みます。表示される20件のリスク計算と宣言開始位置はすべて検証済みですが、リスクは高複雑度の候補集合に対するヒューリスティックであり、保証されたグローバルリスクランキングや個別呼び出し元数のカウントではありません。
• 残存するレイテンシ: アーキテクチャは546.4秒かかり、その中にはエージェント/モデルのターン中に検索完了から次のツール呼び出しまでの479.6秒のギャップが含まれます。プロバイダー側の原因は未確立です。API ケースは69.4秒で返ります。レイテンシはケース間で移動しており、一般的に解決されたわけではありません。
• 比較の限界: チェックアウト、グラフの内容、ファイル数は依然として異なり、モデルの推論やキャッシュのウォーム状態も制御されていません。以前の評価ドキュメントがケース1〜3で取得されているため、これはホールドアウトされた精度ベンチマークではありません。この ReAct 実行は LATS 修正前のバイナリを使用しており、LATS をライブ検証していません。

完了した元のフルティアの7ケースすべてと、元のバランス型の8ケースすべてで、型付き回答のパース警告が記録されました。代わりにサーバーがツールトレースから構造化された証拠を合成しました。ランナーは結果の JSON レスポンスを受け入れました。リフレッシュされたバランス型およびフル実行でも、散文回答には合成ハイライトを使用しています。フォールバックは DEBUG でログに記録されるようになりました。これらのフォールバックも内部ツールのエラーも、事実精度のスコアではありません。最初のバランス型診断実行 20261006_041408_086869 は、意図したリクエストモデルを明示的に選択しなかったため、別途保持されています。

高速ベースラインはローカル実行 20261006_013512_392882 です。そのインデックスのティアはテストセッションから、gpt-6-luna というモデルラベルはプロジェクトオーナーから得たもので、ランナーはどちらの設定も自動的には取得しません。バランス型評価中に、ソースレビューで、Rig アダプターがモデルを CODEGRAPH_LLM_MODEL、次に CODEGRAPH_AGENT_MODEL から選択していることが判明しました。当時、コア設定の CODEGRAPH_MODEL は読み取っていなかったため、後者のみを設定した場合、OpenAI Rig パスはデフォルトで gpt-4o を要求していました。(その後アダプターは CODEGRAPH_MODEL、次に [llm] model にフォールバックするよう変更されました。)高速実行の保存されたレスポンスにはリクエストモデルが記録されていないため、そのラベルはオーナーの確認に基づいています。再現可能なエージェント比較のために、CODEGRAPH_LLM_MODEL を明示的に設定してください。これらのラベルは構成済み/リクエスト済みのモデルを識別するものであり、ランナーはプロバイダー側のルーティングを証明するものではありません。

これらの観察結果は、インデックスのティアの影響をモデルの推論から分離するものでも、数値的な精度率を確立するものでもありません。実行はチェックアウト、インストールされたバイナリ、ファイル数、埋め込み/入力ポリシー、結果の上限、およびデッドラインも異なります。以降の比較では、質問、モデル、エージェントのコンテキストバジェット、推論設定を一貫させてください。ソースリビジョンとインデックス構成を記録し、実行間の変更を開示してください。精度スコアを割り当てる前に、ソースの位置、アクティブな条件付きコード、完全性、および裏付けのない結論を確認してください。

---

アーキテクチャ

インタラクティブなアーキテクチャ図を見る - クリック可能なコンポーネントとレイヤーのフィルタリングを使って、ワークスペース全体の構造を確認できます。

┌─────────────────────────────────────────────────────────────────┐
│                         Claude Code / MCP Client                │
└─────────────────────────────────┬───────────────────────────────┘
                                  │ MCP Protocol
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP Server                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    Agentic Tools Layer                    │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐  │  │
│  │  │  ReAct  │ │  LATS   │ │Reflexion│ │ Tool Execution  │  │  │
│  │  │  (Rig)  │ │  (Rig)  │ │  (Rig)  │ │    Pipeline     │  │  │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────────┬────────┘  │  │
│  └───────┼───────────┼───────────┼───────────────┼───────────┘  │
│          └───────────┴───────────┴───────────────┘              │
│                              │                                  │
│  ┌───────────────────────────┼───────────────────────────────┐  │
│  │                  Inner Graph Tools                        │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐   │  │
│  │  │ Transitive   │ │    Call      │ │     Coupling     │   │  │
│  │  │ Dependencies │ │   Chains     │ │     Metrics      │   │  │
│  │  └──────────────┘ └──────────────┘ └──────────────────┘   │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐   │  │
│  │  │   Reverse    │ │    Cycle     │ │       Hub        │   │  │
│  │  │    Deps      │ │  Detection   │ │      Nodes       │   │  │
│  │  └──────────────┘ └──────────────┘ └──────────────────┘   │  │
│  └───────────────────────────┬───────────────────────────────┘  │
└──────────────────────────────┼──────────────────────────────────┘
                               │
┌──────────────────────────────┼──────────────────────────────────┐
│                         SurrealDB                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Nodes     │  │    Edges    │  │   Chunks + Embeddings   │  │
│  │  (AST +     │  │  (calls,    │  │   (HNSW vector index)   │  │
│  │   FastML)   │  │   imports)  │  │                         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│                                                                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │              SurrealQL Graph Functions                     │ │
│  │   fn::semantic_search_nodes_via_chunks                     │ │
│  │   fn::semantic_search_chunks_with_context                  │ │
│  │   fn::get_transitive_dependencies                          │ │
│  │   fn::trace_call_chain                                     │ │
│  │   fn::calculate_coupling_metrics                           │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

重要なポイント： エージェント型ツールは、単に1つの関数を呼び出すだけではありません。実行するグラフ操作を推論し、それらを連鎖させて、結果を統合します。1回の agentic_impact 呼び出しで、次の処理を行うことがあります。

1. 対象コンポーネントを意味的に検索する
2. 直接の依存関係を取得する
3. 推移的な依存関係をたどる
4. 循環依存がないか確認する
5. 結合メトリクスを計算する
6. 影響を受ける可能性のあるハブノードを特定する
7. すべての調査結果を実行可能な回答にまとめる

---

対応言語

CodeGraph は初期解析に tree-sitter を使用し、FastML アルゴリズムで結果を強化します。対応言語は次のとおりです。

Rust • Python • TypeScript • JavaScript • Go • Java • C++ • C • Swift • Kotlin • C# • Ruby • PHP • Dart

---

プロバイダーの柔軟性

埋め込み

次元数が 384～4096 の任意のモデルを使用できます。

• ローカル： Ollama、LM Studio、ONNX Runtime
• クラウド： OpenAI、Jina AI

LLM（エージェント型推論用）

• ローカル： Ollama、LM Studio
• クラウド： Anthropic Claude、OpenAI、xAI Grok、OpenAI Compliant

データベース

• SurrealDB 3.x embedded（SurrealKV、プロジェクトごとに1つのストア、実行するサーバーは不要）と HNSW ベクトルインデックス
• オプション：共有 SurrealDB サーバーまたは CODEGRAPH_SURREALDB_URL を使用した Surreal Cloud

---

設定

ビルドには Rust 1.95 以降が必要で、エディション 2024 を使用します。レジストリから直接取得する依存関係は、現在の安定版リリースを対象とし、解決された依存関係グラフは Cargo.lock に記録されます。Bincode は最後の機能リリースである 2.0.1 を使用します。3.0.0 は意図的にコンパイルに失敗します。ONNX Runtime バインディングは、安定版の 2.0 リリースが存在しないため、最新のリリース候補である 2.0.0-rc.13 を使用します。

CLI はワーカースレッドの起動前に、プロジェクトまたはユーザーの dotenv 設定を読み込みます。ライブラリを呼び出す場合は、プロセス起動時に環境を初期化してください。ConfigManager::load() は設定を読み取るだけで、プロセス環境は変更しません。

codegraph init は選択したプロジェクトを設定し、インデックス作成前にその環境を読み込みます。codegraph config init はグローバルなアプリケーション設定を作成するための別コマンドです。プロジェクトの初期化ではモデルプロバイダーは設定されません。

設定ファイルは ./.codegraph.toml（プロジェクト）を読み込み、続いて ~/.codegraph/config.toml（ユーザー）を読み込みます。作業ディレクトリ内の .env と CODEGRAPH_* 環境変数は、これらの設定を上書きします。

[embedding]
provider = "ollama"
model = "qwen3-embedding:0.6b"
dimension = 1024

[llm]
provider = "anthropic"
model = "claude-sonnet-4"
context_window = 200000

[indexing]
tier = "fast"

組み込みエージェントは、LLM の各設定を3段階で解決します。まず環境変数（プロジェクトの .env も含みます）、次に設定ファイルの [llm] セクション内のキー、最後にデフォルト値を使用します。[llm] の enabled = false を設定すると、エージェントはこのセクションを無視します。また、API キーは環境からのみ読み込まれます。codegraph config agent-status を実行すると、有効なプロバイダー、モデル、ティアを確認できます。すべての変数とキーについては AI_PROVIDERS.md を参照してください。

ストレージの設定は不要です。CODEGRAPH_SURREALDB_URL（およびその他の CODEGRAPH_SURREALDB_* 変数）でサーバーを指定しない限り、プロジェクトごとの組み込みストアが使用されます。CODEGRAPH_SCHEMA=v1 を設定すると、新しいストアで元の schema/codegraph.surql が選択されます。

設定オプションの詳細については、INSTALLATION_GUIDE.md を参照してください。

実験的なグラフスキーマ（任意）

CodeGraph は、既存の CodeGraph ツールおよびインデックス作成パイプラインと相互運用可能な、実験的な SurrealDB のグラフ DB スタイルのスキーマ（schema/codegraph_graph_experimental.surql）で実行できます。

デフォルトのスキーマ（schema/codegraph_v2.surql）と比べて、実験的なスキーマは大規模なコードベースでのグラフクエリ操作（トラバーサル、近傍の展開、ツール主導のグラフ分析）をより高速かつ効率的に行えるように設計されています。

組み込みストアで使用するには、プロジェクトのストアが初めて作成される前にフラグを設定します （または <project>/.codegraph/db を削除して、再度インデックスを作成します）。

CODEGRAPH_USE_GRAPH_SCHEMA=true

SurrealDB サーバーで使用する場合は、専用データベースに一度スキーマを読み込み、CodeGraph の接続先をそのデータベースに設定します。

surreal sql --conn ws://localhost:3004 --ns ouroboros --db codegraph_experimental < schema/codegraph_graph_experimental.surql
CODEGRAPH_USE_GRAPH_SCHEMA=true
CODEGRAPH_GRAPH_DB_DATABASE=codegraph_experimental

注意事項：

• スキーマファイルでは、複数の埋め込み次元（384～4096）に対する HNSW インデックスを定義しているため、DB を再構築せずに埋め込みモデルを切り替えられます。
• 既存のストアでは、作成時のスキーマが維持されます。スキーマを切り替えるには、新しいストアが必要です。
• CODEGRAPH_GRAPH_DB_DATABASE はサーバーモードでのみ適用されます。

---

デーモンモード

インデックスを自動的に最新の状態に保ちます。

# With MCP server (recommended)
codegraph start stdio --watch

# Standalone daemon
codegraph daemon start /path/to/project --languages rust,typescript

変更を検出してデバウンスし、バックグラウンドで再度インデックスを作成します。

プロジェクトごとの組み込みストアで使用する場合は、--watch を指定します。ウォッチャーは MCP サーバーのプロセス内で実行されます。スタンドアロンのデーモンは別のプロセスであり、実行中のサーバーとプロジェクトのストアを共有できないため、そのプロジェクトでサーバーが実行されていない場合、または SurrealDB サーバーを使用する場合にのみ使用してください。

---

次のステップ

• 対応言語の拡充
• リポジトリをまたいだ分析
• カスタムグラフスキーマ
• カスタムアナライザー用のプラグインシステム

---

開発理念

CodeGraph は、AI コーディングアシスタントは置き換えるのではなく、能力を拡張すべきだと考えているために存在します。AI が、取り組んでいる内容を深く理解しているときに、AI と人間の協働は最もうまく機能します。

IDE や型チェッカー、テストに取って代わろうとしているわけではありません。AI が実際に役立つために必要なコンテキストを提供します。

コードベースはグラフです。AI にもそのように見せましょう。

---

ライセンス

MIT

---

リンク

• インストールガイド
• SurrealDB Cloud（無料プラン）
• Jina AI（無料の API トークン）
• Ollama（ローカルモデル）

---