oxcode

oxcode

oxcode はソースコードをグラフにインデックス化し、コーディングエージェントに提供します。oxgraph を基盤として構築されています。oxgraph は、ストレージに依存せず、ゼロコピーに適した、Rust 用のグラフ／ハイパーグラフのトポロジー基盤です。インデックスは .oxcode/index.oxgdb/ 内のネイティブ oxgraph データベースに保存されます。

CLI では生の OxQL も引き続き利用できますが、エージェントによるナビゲーションでは通常、context、symbols、files、および呼び出しグラフの各コマンドから始めることをおすすめします。これらのコマンドはグラフ ID を関数名、定義範囲、シグネチャ、ドックストリング、ソースのプレビュー、呼び出し箇所のソースコンテキストに展開します。

はじめに

1. インストール

ビルド済みバイナリ（推奨 — Rust ツールチェーンは不要で、文法ファイルが静的にリンクされているためオフラインで実行できます）：

# macOS / Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/oxgraph/oxcode/releases/latest/download/oxcode-cli-installer.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://github.com/oxgraph/oxcode/releases/latest/download/oxcode-cli-installer.ps1 | iex"

または、リリースページからアーカイブをダウンロードします。代わりにCargo を使用する場合：

cargo binstall oxcode-cli   # prebuilt, no compile
cargo install --force oxcode-cli   # build from source

これにより、CLI と MCP サーバー（oxcode mcp）を含む oxcode バイナリが 1 つインストールされます。（crates.io では oxcode という名前がすでに使われているため、クレート名は oxcode-cli ですが、コマンド名は引き続き oxcode です。）既存のインストールを置き換えるには、インストーラーを再実行するか（または cargo install --force oxcode-cli を実行してください）。v0.1.2 以降を使用している場合、oxcode mcp も起動時に自動更新されます。

2. プロジェクトをインデックス化する

cd your-project
oxcode index
oxcode context "How does authentication work?"

3. エージェントを接続する（MCP）

エージェントにサーバーを追加します。Claude Code の場合（~/.claude.json）：

{
  "mcpServers": {
    "oxcode": { "type": "stdio", "command": "oxcode", "args": ["mcp"] }
  }
}

接続したら、エージェントに oxcode_watch を一度呼び出させます。これによりインデックスが構築され、ファイルの変更に応じて最新の状態に保たれます。path を省略すると、プロジェクトのルートは MCP プロセスの cwd ではなく、OXCODE_ROOT、CLAUDE_PROJECT_DIR、または WORKSPACE_FOLDER_PATHS から取得されます（ホストはサーバーを $HOME で起動することがよくあります）。1 つのリポジトリで複数のエージェントを動かす場合、ファイルロックによって書き込みを行うプロセス（監視／再インデックス化を行うプロセス）が 1 つ選ばれ、残りは読み取りを提供します。そのため、必要な数だけ実行できます。その後、oxcode_explore を使って質問してください。

必要に応じて、~/.claude/settings.json でツールを自動許可できます（クエリツールは読み取り専用で、oxcode_watch はローカルインデックスの構築／保守のみを行います）： mcp__oxcode__oxcode_watch、_explore、_search、_callers、_callees、_symbol、_files、_status。

Claude Code プラグイン（ワンコマンドインストール）

上記の設定を手動で編集する代わりに、oxgraph マーケットプレイスからバンドル済みプラグインをインストールできます。プラグインが MCP サーバーを自動で接続します。

/plugin marketplace add oxgraph/oxgraph
/plugin install oxcode@oxgraph

プラグインを使う場合も、PATH 上に oxcode バイナリがあり、プロジェクトがインデックス化されている必要があります（手順 1～2）。詳しくは claude-plugin/README.md を参照してください。

その他の MCP クライアント（レジストリ／npm）

oxcode は公式の MCP レジストリに io.github.snowmead/oxcode として登録されているため、レジストリに対応したクライアントから検索できます。npx 起動コマンドを使うクライアント向けに、npm パッケージも用意されています。

{
  "mcpServers": {
    "oxcode": { "command": "npx", "args": ["-y", "@snowmead/oxcode-mcp"] }
  }
}

@snowmead/oxcode-mcp は oxcode mcp を実行する薄いラッパーのため、PATH 上に oxcode バイナリが必要です（手順 1）。すでにインストール済みであれば、上記の command: "oxcode" を使う方が簡潔です。

インデックス作成の仕組み

1. 抽出 — tree-sitter が各ソースファイルを構文木に解析します。言語ごとの抽出器が構文木をたどる（手書き）か、tree-sitter クエリを実行（汎用）して、シンボルの ノード（ファイル、モジュール、クラス、構造体、トレイト、インターフェース、関数、メソッド、フィールドなど）と エッジ（contains、calls、imports、references、implements）を出力します。修飾名は、その言語固有の区切り文字にかかわらず、:: で連結した内部形式に正規化されるため、リゾルバーとグラフは言語に依存しません。
2. 解決 — 参照は、以下の優先順位でファイルをまたいで定義に解決されます。 完全修飾名 → 包含するモジュールのスコープ → スコープ内のインポート → レシーバー型 → 裸の名前。一致候補が曖昧な場合は、破棄せずに保持して、その旨を記録します。
3. 保存 — 解決済みグラフは、安定したシンボル ID を用いて oxgraph データベースに調整しながら保存されるため、再インデックス作成の計算量は O(repo) ではなく O(change) です。グラフに対する Personalized PageRank により、context コマンドの範囲が制限され、関連度順に並んだ出力が実現します。

言語

oxcode languages を実行すると、登録済みの抽出器が一覧表示されます。対応状況は次の段階に分かれています。

言語	拡張子	段階
Rust	.rs	高精度
Go	.go	高精度
TypeScript	.ts .tsx .mts .cts	高精度
JavaScript	.js .jsx .mjs .cjs	高精度
Python	.py .pyi	汎用
Java	.java	汎用
C	.c .h	汎用
C++	.cpp .cc .cxx .hpp .hh .hxx	汎用
C#	.cs	汎用
PHP	.php	汎用
Ruby	.rb	汎用
Swift	.swift	汎用
Kotlin	.kt .kts	汎用
Scala	.scala .sc	汎用
Dart	.dart	汎用
Lua	.lua	汎用
Luau	.luau	汎用
Objective-C	.m .mm	汎用
Pascal/Delphi	.pas .dpr .dpk .lpr	汎用
Svelte	.svelte	埋め込みスクリプト
Vue	.vue	埋め込みスクリプト
Liquid	.liquid	認識済み

• 高精度 — レシーバー型付きメソッド呼び出し（self／this／Go のレシーバー）、正確な修飾名、インポート（TypeScript のパスベースの ESM インポートを含む）を解決する手書きの抽出器です。
• 汎用 — これらすべての言語で共有される、クエリ駆動の単一抽出器です。それぞれの言語には、tree-sitter クエリとプロファイルエントリー（crates/oxcode-core/src/extract/profiles.rs）があります。包含関係はバイト範囲のネストから得られます。シンボルと、スコープ／単純な優先順位で解決されるおおよその呼び出しエッジが出力されます（レシーバー型は扱わないため、一部のエッジは曖昧として記録されます）。
• 埋め込みスクリプト — Svelte／Vue の <script> ブロックは、元のコンポーネントファイル内の正確なオフセットを保ったまま TypeScript として抽出されます。
• 認識済み — ファイル形式は認識されますが、まだインデックス作成の対象ではありません。このようなファイルは、暗黙に除外されず、スキップされたファイルとして報告されます。

言語を追加するには、tree-sitter クエリとプロファイルエントリーを追加します。高精度にするには、共有の extract/walker.rs の足場を再利用する手書きの抽出器を実装します。

クイックスタート

oxcode index --path path/to/rust/project
oxcode status --path path/to/rust/project
oxcode context "How does entry reach helper?" --path path/to/rust/project --limit 8 --json
oxcode symbols "entry helper" --path path/to/rust/project --limit 20 --json
oxcode symbols "entry helper" --path path/to/rust/project --kind function --kind method
oxcode files "runtime scheduler" --path path/to/rust/project --limit 20 --json
oxcode symbol crate::entry --path path/to/rust/project --json
oxcode calls crate::entry --depth 2 --path path/to/rust/project
oxcode callers crate::helper --depth 2 --path path/to/rust/project
oxcode query "MATCH ELEMENTS WHERE qualified_name = 'crate::entry'" --path path/to/rust/project
oxcode query "MATCH RELATIONS TYPE calls" --format expand --path path/to/rust/project
oxcode query "GRAPH calls WALK FROM 12 DEPTH 2 DIRECTION both LIMIT 100" --path path/to/rust/project

生成される .oxcode/ ディレクトリには専用の .gitignore が書き込まれるため、インデックスが誤ってコミットされることはありません。

ナビゲーションコマンドで使える便利なセレクター：

• element:<id>：具体的な OxGraph 要素 ID
• my_crate::auth::tenant_middleware のような、クレート名で修飾された完全一致の名前 （修飾名はクレートを基点とするため、最初のセグメントはパッケージ名であり、- は _ に正規化されます）
• name:<name>：単純な関数名
• file:<path>:<line>：ソース行をカバーする最も内側のシンボル

symbols は、繰り返し指定できる --kind <kind> フィルターを受け付けます。有効な種類は次のとおりです。

• file、module、namespace、package、class、struct、enum、 trait、interface、impl_block、function、method、field、 variable、constant、type_alias、macro

context は決定論的で、グラフから導出されます。タスクのテキストに関連するエントリーポイントのシンボルをランク付けし、その後、近傍の calls、contains、references、implements の関係を展開します。

query と explain は生の OxQL/Cypher を実行します。キーワードを検索する場合は symbols を使い、通常の英語のフレーズを query に渡さないでください。

受け付ける OxQL プロファイル：

• CATALOG
• MATCH ELEMENTS
• MATCH ELEMENTS HAS LABEL <label>
• MATCH ELEMENTS WHERE <property> = '<value>'
• MATCH RELATIONS TYPE <type>
• GRAPH calls WALK FROM <element-id> DEPTH <n> [DIRECTION outgoing|incoming|both] [LIMIT n]

ベンチマーク

Tokio コードベースを使ったエージェントタスクのベンチマークです。エージェントが 「tokio はどのように async タスクをスケジュールし、実行するのか？」 に、各ツールの使用時と未使用時で回答し、効率とブラインド評価による回答品質を測定します。oxcode と codegraph は異なるエージェントハーネスで測定されているため、比較可能な指標は絶対値ではなく、各ツール自身のツール未使用時のベースラインに対する改善幅です。

条件	回答品質	トークン数	コスト	ツール呼び出し回数	実時間
ベースライン（ツールなし）	0.98	—	—	—	—
oxcode — codex/gpt-5.5、CLI、n=6	0.96（同率）	+15%	+4%	−4%	+14%
oxcode — codex/gpt-5.5、MCP、n=6	0.93	−74%	−57%	−84%	−60%
codegraph — Opus 4.8、MCP、公表値	未測定	−38%	同水準	−57%	−18%

パーセンテージは、各ツール自身のツール未使用時のベースラインに対する変化です（負の値は削減を表し、優れています。品質はブラインド評価による LLM 判定スコアで、範囲は 0～1 です）。oxcode の全行は、Tokio で実施した単一のリリーステスト（n=6）の結果です。絶対値の中央値：トークン数 395k（ベースライン）→ 455k（CLI）→ 104k（MCP）、コスト $0.17 → $0.18 → $0.07、ツール呼び出し回数 28 → 27 → 5、実時間 97s → 111s → 39s。

主役は MCP サーバーです。 エージェントが組み立てる CLI の代わりに、同じ範囲に限定された PageRank 選定済みのコンテキストを、1 回の呼び出しで使える oxcode_explore MCP ツールを通じて提供すると、ツールなしのベースラインと比べて、ツール呼び出し回数を 84%、トークン数を 74%、コストを 57%、実時間を 60%削減でき、公表されている codegraph の削減幅を上回ります（ツール呼び出し回数 −57%／トークン数 −38%）。CLI 条件はベースラインと統計的に同等です。エージェントはシェルのバイナリを、自身の grep/read の代替ではなく補助として扱います。つまり、差を生んでいたのは常にインデックスの品質ではなく、ツールの提供方法でした。品質評価のゲートで明らかになるコスト（codegraph のような品質を見ないベンチマークでは見えない点）は、MCP の回答品質が 0.98 から 0.93 に下がることです。探索を効率化したことによる、網羅性とのトレードオフです。codegraph の数値は同プロジェクトの README から取得し、2026-06-02 に再検証しました。

方法論、信頼区間、再現手順の全文： docs/agent-eval-results.md および docs/agent-eval-methodology.md。

アーキテクチャ

ワークスペースでは、ハイブリッドな Rust アーキテクチャを採用しています。

• oxcode-model：ワークスペース全体で共有される、ストレージに依存しない語彙集です。コードグラフの種別、識別子の newtype、グラフスキーマカタログ、セレクター文法、抽出／解決 IR、エージェント向けレポート DTO が含まれます
• oxcode-core：インデックス作成、抽出、参照解決、OxGraph ストレージ、ナビゲーション、フォーマット処理、および公開 ProjectIndex ファサードを担います
• oxcode-cli：oxcode バイナリです。CLI コマンドに加え、コーディングエージェントに読み取り専用クエリを公開する MCP サーバー（stdio）である oxcode mcp サブコマンド（1 回の呼び出しで使える oxcode_explore ツール、および oxcode_search、oxcode_callers／oxcode_callees、oxcode_symbol、oxcode_files、oxcode_status）と、インデックスを構築してファイルの変更に応じて最新の状態に保つ oxcode_watch を備えています。プロセス間のファイルロックによって、リポジトリごとに 1 つの書き込みプロセスが選出され、他のインスタンスは読み取りを処理します

oxcode-core は、役割別の内部モジュールに分かれています。scan、extract（言語ごとのエクストラクターと共通の CST／cargo ヘルパーを含みます）、resolve、store::oxgraph（write パスを含みます）、format、paths、error です。モデルクレートの型付きスキーマは、ストレージ層がプロパティ登録、読み取りキーのキャッシュ、インデックスを導出する際の唯一の信頼できる情報源です。読み取りは ProjectIndex を介して実行され、データベースを一度だけ開いてプロパティキーのスキーマを解決します。ProjectIndex::with_session は、複数の読み取りを単一の共有スナップショットに対して実行するため、複数ステップのナビゲーションでも内部整合性が保たれます。

extract モジュールには、手書きのエクストラクター（Rust、Go、TypeScript／JavaScript）、言語ごとの .scm クエリとプロファイルを備えた汎用のクエリ駆動型エクストラクター、Svelte／Vue の埋め込みスクリプトを処理するホスト、および静的リンクされた grammar レジストリがあります。上記の「言語」テーブルを参照してください。