Muvon/octocode

Structural code intelligence for AI agents — semantic search, knowledge graphs, and a built-in MCP server in one Rust binary. Give Claude, Cursor, and any MCP client a deep understanding of your codebase.

概要

Octocodeは、Rustで書かれたコマンドラインツールで、あなたとあなたのAIコーディングアシスタントがコードベースを探索するのに役立ちます。これはコードの検索エンジンであると同時に、ファイルやシンボル（関数、クラスなど）がどのように相互接続しているかを示す関係マップでもあります。

これはMCP（Model Context Protocol）と呼ばれるプロトコルを話します。これは、Claude Code、Codex、Cursor、WindsurfなどのAIアシスタントが外部ツールにプラグインするための標準的な方法です。つまり、Octocodeを実行して、AIアシスタントにコードベースをクエリさせることができます。または、ターミナルから直接検索することもできます。

2つの動作方法

Octocodeには2つの補完的なメカニズムがあります。

ライブソース解析 — Tree-sitterと呼ばれるパーサーを使用して、現在のソースコードを直接読み取ります。インデックス、埋め込み、AIモデルは必要ありません。シンボルと関係（インポート、呼び出し、継承、実装）をその場で抽出します。これを使用する機能：構造検索（定義と使用箇所の検索）、関数シグネチャの表示、ライブ依存関係グラフ。
インデックス付きセマンティック検索 — まずoctocode indexを実行して検索インデックスを構築します。コードをベクトルとして埋め込み（FastEmbedと呼ばれるローカルモデルを使用）、キーワードもインデックス化します（BM25と呼ばれる手法を使用）。検索時には、両方のアプローチを組み合わせて結果を再ランク付けします。これにより、「意図」によってコードを見つけることができます。例えば、「認証ミドルウェア」と入力すると、正確な単語が含まれていなくても関連するコードが表示されます。

READMEでは次のように説明されています。

現在のソース → 言語パーサー → ライブファイルとシンボルグラフ → MCPツール
インデックス付きコード → 埋め込み + BM25 → ハイブリッド検索 + 再ランキング → CLI / MCP

主な機能

機能	説明	インデックスが必要か
`semantic_search`	コード、ドキュメント、インデックス付き履歴を意味で検索	はい
`structural_search`	現在のソース内の定義、使用箇所、コードパターンを検索	いいえ
`view_signatures`	ファイル全体を読み込まずに関数シグネチャとインポートを読む	いいえ
`graphrag`	ファイル/シンボル間のライブ関係と依存関係パスを探索	いいえ（ライブ版）
`lsp_*` ツール	定義、参照、ホバー情報、補完 — 言語サーバーが必要（例：`rust-analyzer`）	いいえ、ただしLSPサーバーが必要

インストールと基本的な使い方

次のいずれかでインストールします：

# Linux/macOS/Unixシェル（Windows）
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# macOS
brew install muvon/tap/octocode

# またはソースから
cargo install octocode  # Rust 1.95+ と protoc が必要

次に、Gitリポジトリ内で：

cd /path/to/your/project
octocode index
ocotcode search "authentication middleware"

他の便利なオプション：

octocode search "auth" "middleware" "session" — 関連するクエリを組み合わせる
octocode search "..." --language rust — 言語でフィルタリング
octocode search "..." --mode docs — コードではなくドキュメントを検索
octocode index --no-git — Gitリポジトリではないディレクトリ用
octocode watch — ファイルが変更されるたびにインデックスを更新（MCPサーバーとは別に実行）
octocode graphrag overview — インデックス付きGraphRAGを有効にした後（セマンティックファイル検出とオプションのLLM生成説明を備えたオプションの永続化レイヤー）

デフォルトではAPIキーは不要です。埋め込みモデルと再ランキングモデルは、初回使用時にローカルにダウンロードされます。リモートプロバイダー（埋め込み、再ランキング、LLM）はオプションで設定可能です。

AIアシスタントへの接続

Claude Codeの場合： claude mcp add --transport stdio octocode -- octocode mcp --path /path/to/your/project

Codex CLIの場合： codex mcp add octocode -- octocode mcp --path /path/to/your/project

Claude Desktop、Cursor、Windsurfの場合：クライアントのMCP設定にJSONエントリを追加し、command: "octocode"、args: ["mcp", "--path", "/path/to/your/project"] とします。

LSP（言語サーバー）ツールを有効にするには： octocode mcp --path /path/to/your/project --with-lsp rust-analyzer

デフォルトでは、MCPサーバーは再インデックスしません。コード変更後はoctocode indexを再実行するか、別のプロセスでoctocode watchを実行します。

OctoFS統合

OctoFSは、AIアシスタントにファイル読み取りとアトミック編集機能を提供するコンパニオンツールです。Octocodeはこれと連携します： structural_searchは、N:hh|content形式のソース行を返します。ここでN:hhは行ID（インデントを含む元の行のハッシュ）です。OctoFSのviewとbatch_editは同じIDを使用するため、エージェントは編集ターゲットを見つけるために行を再読み取りすることなく、検索してから編集できます。OctoFSは編集を適用する前にIDを検証し、コンテンツが変更された場合は古いターゲットにフラグを立てます。N:hh|プレフィックスはメタデータであり、コードの一部ではありません。OctoFSはオプションです。Octocodeは単独で動作します。

READMEにはOctomindについても言及されています。これはコンパニオンAIエージェントランタイムで、そのdeveloper:generalエージェントはOctocodeとOctoFSの機能をバンドルしています。

サポート言語

Rust、Python、TypeScript/JavaScript（.ts、.tsx、.js、.jsx）、Go、PHP、C/C++（多くの拡張子）、Ruby、Elixir、Java、Swift、Svelte、Lua、CSS/SCSS/Sass、JSON、Bash、Markdown。

プライバシーと設定のハイライト

デフォルトでローカルモデル — 埋め込みと再ランキングは、モデルダウンロード後にローカルで実行されます。APIキーは不要です。
ローカルストレージ — インデックスはリポジトリの外部にあるOctocodeのプロジェクトごとのデータディレクトリに保存されます。
ファイル除外 — .gitignoreと.noindexを尊重します。さらに除外を設定できます。
クライアントの注意点 — ローカルモデルでも、Octocodeを使用するAIアシスタントはツールから返されたソースコンテンツを受け取る場合があります。
リモートプロバイダーはオプション — 有効にすると、それらの機能に必要なクエリとソースコンテンツを受け取ります。APIキーは環境変数に入れます。

パフォーマンスベンチマーク

READMEには過去のベンチマーク結果（2026年6月21日付、Octocode 0.17.1を使用 — 現在のリリースではありません）が含まれています。127のコード検索クエリで、再ランキングを無効にした場合：

構成	Hit@5	Hit@10	MRR	NDCG@10	Recall@10
ベクトルのみ	0.598	0.717	0.485	0.528	0.671
ハイブリッド 0.7/0.3（ベクトル/キーワード）	0.598	0.717	0.485	0.528	0.671
ハイブリッド 0.3/0.7	0.732	0.835	0.572	0.620	0.807

要点：キーワード検索の重みを高くすると、その過去のテストでは結果が改善されました。READMEは、これらの数値が現在のリリースを測定していないことを明示的に警告しています。

結論

Octocodeは、AIアシスタントにコードベースの構造化された検索可能なビューを提供する開発者ツールです。セマンティック検索、正確な構造検索、ライブシンボル/依存関係グラフを組み合わせ、デフォルトでローカルに実行され、幅広い言語をサポートします。

ライセンスと貢献

Apache License 2.0、Muvonによって保守されています。貢献はGitHub Issues、Discussions、またはメール（opensource@muvon.io）で受け付けています。

上記のすべての事実は、プロジェクトのREADMEから直接引用されています。