Octocode

AI エージェントのための構造的コードインテリジェンス — MCP サーバー + ナレッジグラフ + セマンティック検索

AI アシスタントに、コードベースを理解する力を与えましょう。 Octocode はプロジェクトをナビゲート可能なナレッジグラフに変換します。Claude、Cursor、その他の AI エージェントが検索、理解、ナビゲートできます。

🚀 クイックスタート • 🤖 MCP 統合 • 📖 ドキュメント • 🌐 ウェブサイト

🤖 AI エージェントのために構築

問題： AI アシスタントはコードベースを把握できません。ファイルを検索したり、依存関係を理解したり、セッションをまたいでコンテキストを記憶したりできません。

解決策： Octocode の MCP サーバーは、AI エージェントに次の機能を提供します。

• 🔍 セマンティック検索 — キーワードではなく、意味からコードを検索
• 🕸️ ナレッジグラフ — インポート、呼び出し、依存関係をたどる
• 📝 コードシグネチャ — ファイル全体を読むことなく構造を確認
• 🧭 LSP による高精度な検索 — 言語サーバーを通じた定義への移動、参照の検索、ホバードキュメント

対応環境： Claude Desktop • Cursor • Windsurf • MCP 対応の AI

AI アシスタントは次のことができるようになります。

You: "Where is authentication handled?"
AI: *searches your codebase* "Authentication is in src/middleware/auth.rs,
    which imports jwt.rs for token validation and calls user_store.rs for lookup."

You: "What files depend on the payment module?"
AI: *queries knowledge graph* "src/api/handlers/payment.rs imports payment/mod.rs,
    which is also used by src/workers/refund.rs and src/cron/billing.rs"

You: "Find every call site of this function"
AI: *uses LSP find-references* "process_payment() is called from 4 places:
    checkout.rs:87, refund.rs:134, billing.rs:56, and tests/payment_test.rs:23"

🤔 なぜ Octocode なのか？

一般的な RAG は、コードを平坦なテキストチャンクとして扱います。 似た表現のスニペットは見つけられても、auth_middleware.rs が jwt.rs をインポートし、user_store.rs を呼び出し、router.rs に組み込まれていることは把握できません。Octocode は 構造 を理解します。

# Semantic search finds the right code
octocode search "authentication middleware"
→ src/middleware/auth.rs — Similarity: 0.9234

# The GraphRAG CLI queries the optional persisted graph
octocode config --graphrag-enabled true
octocode index
octocode graphrag get-relationships --node-id src/middleware/auth.rs
Outgoing:
  imports → jwt (src/auth/jwt.rs): token validation logic
  calls   → user_store (src/db/user_store.rs): user lookup by token
Incoming:
  imports ← router (src/router.rs): wires auth into the request pipeline

Octocode は tree-sitter AST 解析を使用し、ファイル、シンボル、インポート、呼び出し、継承、実装のライブグラフを構築します。MCP の graphrag ツールは、インデックス、埋め込み、LLM を使わず、現在のソースツリーからオンデマンドでこのグラフを構築します。オプションのインデックス型 GraphRAG を追加すると、セマンティックなファイル検出、説明、より広範なアーキテクチャ上の関係を利用できます。

🔬 仕組み

Current Source → Tree-sitter AST → Live Symbol Graph ──────────────→ MCP `graphrag`
                                           ↑                              ↑
Indexed Code → Embeddings + Optional LLM → Persisted File Enrichment ─────┘

1. ライブ AST グラフ — tree-sitter が現在のソースから直接、ファイルとシンボルのノードに加え、決定論的な contains、imports、calls、extends、implements の関係を抽出します
2. 常時利用可能なグラフナビゲーション — MCP のグラフ検索、関係のたどり、パス検索、概要表示は、[graphrag].enabled = false の場合でも機能します
3. オプションの拡張 — インデックス型 GraphRAG を有効にすると、セマンティックなファイル照合、LLM による説明、より広範なファイルレベルのアーキテクチャ関係が追加されます。シンボルが埋め込みや LLM 生成の対象になることはありません
4. ハイブリッド検索 — セマンティック類似度 + BM25 全文検索 + 再ランキングにより、意味に基づくコード検索を別途処理します
5. MCP サーバー — semantic_search、view_signatures、graphrag、structural_search を、あらゆる MCP 対応クライアントに提供します

✨ 他との違い

ドキュメントツールは、AI に使用するライブラリのマニュアルを提供します。Octocode は、それらをどのように組み合わせたかを示す設計図を AI に提供します。

パフォーマンスを重視して Rust で構築。プライバシーを重視した ローカルファースト。透明性を重視した オープンソース（Apache 2.0）。

📊 検索品質

Octocode には、再現可能な検索ベンチマーク（benchmark/）が付属しています。行範囲の正解データを含む、厳選された 127 件のコード検索クエリを octocode 自身のソースに対して実行します（注釈がずれないよう、b1771ba に固定しています）。以下の数値は、fastembed 経由の jina-embeddings-v2-base-code を使用し、リランキングなしの 完全ローカルで API キー不要の構成によるものです。そのため、これらは上限ではなく下限の値です。

BM25／キーワードのシグナルに向けて RRF 融合の重みを調整すると、コードの正確な識別子を大きく捉えるこのシグナルの効果により、追加コストなしで Hit@5 が +22%、Recall@10 が +20% 向上します。

このベンチマークでは、ここで効果がないものも明らかにしています（6 種類すべての結果は benchmark/RESULTS.md を参照）。汎用のローカルクロスエンコーダーリランカー（bge-reranker-base）は、実際には結果を悪化させました（Hit@5 が 0.732 → 0.598）。コード検索には、市販の汎用モデルではなく、voyage:rerank-2.5 などの コードを考慮した リランカーが必要です。

git clone https://github.com/Muvon/octocode && cd octocode
git worktree add /tmp/corpus b1771ba   # pin the corpus to the ground-truth commit
CORPUS=/tmp/corpus python3 benchmark/run_matrix.py   # set OCTO_BIN to use a custom binary

手法と指標の定義については、benchmark/README.md を参照してください。

🚀 クイックスタート

1. インストール

# Universal installer (Linux, macOS, Windows)
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# macOS with Homebrew
brew install muvon/tap/octocode

# From crates.io
cargo install octocode

# Or from source (latest)
cargo install --git https://github.com/Muvon/octocode

# Download binary from releases
# https://github.com/Muvon/octocode/releases

2. API キーを設定

# Optional: embedding provider (defaults to local FastEmbed — no key needed)
export VOYAGE_API_KEY="your-voyage-api-key"

# Optional: LLM for commit messages, code review
export OPENROUTER_API_KEY="your-openrouter-api-key"

Voyage API キーの取得先： voyageai.com（無料枠あり）

# OpenAI
export OPENAI_API_KEY="your-key"
octocode config --code-embedding-model "openai:text-embedding-3-small"

# Jina AI
export JINA_API_KEY="your-key"
octocode config --code-embedding-model "jina:jina-embeddings-v3"

# Google
export GOOGLE_API_KEY="your-key"
octocode config --code-embedding-model "google:text-embedding-005"

3. コードベースにインデックスを作成

cd /your/project
octocode index
# → ✓ Indexing complete! 342 of 342 files processed (342 new, 0 unchanged)

4. コードを検索

# Natural language search
octocode search "authentication middleware"

# Multi-query for broader results
octocode search "auth" "middleware" "session"

# Filter by language
octocode search "database connection pool" --language rust

# Search commit history
octocode search "authentication refactor" --mode commits

5. AI アシスタントを接続

MCP クライアントの設定（Claude Desktop、Cursor、Windsurf）に追加します。

{
  "mcpServers": {
    "octocode": {
      "command": "octocode",
      "args": ["mcp", "--path", "/your/project"]
    }
  }
}

これで完了です。AI アシスタントがコードベースの構造を理解できるようになりました。

🔌 MCP サーバー連携

Octocode には、コードベースを AI アシスタント向けのツールとして公開する組み込み MCP サーバーが含まれています。これは Octocode の主な利用方法です。AI アシスタントにコードを検索してたどるための直接アクセスを提供できます。

利用可能なツール

言語サーバーを指定してサーバーを起動すると、LSP ツールが有効になります。

octocode mcp --path /your/project --with-lsp="rust-analyzer"

会話型 AI の使用例

接続すると、AI アシスタントがコードベースに関する質問に回答できます。

You: "Where is user authentication implemented?"
AI: *uses semantic_search* "Found in src/auth/login.rs. The authenticate() function
    validates credentials against the database, generates a JWT token, and stores
    the session in Redis."

You: "What files depend on the payment module?"
AI: *uses graphrag* "src/api/handlers/payment.rs imports payment/mod.rs, which is also
    used by src/workers/refund.rs and src/cron/billing.rs. The payment module exports
    process_payment() and validate_transaction() functions."

You: "Show me all error handling in the API layer"
AI: *uses structural_search* "Found 23 error handling patterns in src/api/:
    - 15 use Result<T, ApiError> with explicit error types
    - 8 use .unwrap() (potential panics in handlers/user.rs:42, handlers/auth.rs:87)
    - 3 use .expect() with custom messages"

クイックセットアップ

Octomind（推奨） — セットアップ不要。Octocode が事前設定されています：

curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash
octomind run developer:rust

Claude Code（CLI） — コマンドラインでのセットアップ：

claude mcp add octocode -- octocode mcp --path /path/to/your/project

Claude Desktop / Cursor / Windsurf — 設定に追加します：

{
  "mcpServers": {
    "octocode": {
      "command": "octocode",
      "args": ["mcp", "--path", "/path/to/your/project"]
    }
  }
}

設定ファイルの場所：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• Cursor：~/.cursor/mcp.json または「Settings → MCP Servers」
• Windsurf：「Settings → MCP」

📖 MCP クライアントの完全セットアップガイド — VS Code（Cline/Continue）、Zed、Replit など、15 以上のクライアントの詳細な手順を説明しています。

🌐 対応言語

tree-sitter による完全な AST 解析に対応した 17 言語：

📚 ドキュメント

• はじめに — 最初の手順と基本的なワークフロー
• インストールガイド — 詳細な方法とソースからのビルド
• MCP クライアントのセットアップ — Claude、Cursor、Windsurf など、15 以上のクライアントへの接続
• MCP 統合 — MCP サーバーの詳細と高度な設定
• コマンドリファレンス — CLI の完全なリファレンス
• 設定 — テンプレートとカスタマイズ
• API キー — プロバイダーのセットアップガイド
• アーキテクチャ — 内部の仕組み
• コントリビューション — 開発環境のセットアップ

🔒 プライバシーとセキュリティ

• 🏠 ローカル優先 — fastembed による完全ローカルの埋め込み（API キー不要）。クラウドプロバイダーも任意で利用できます
• 🔐 セキュア — API キーはローカルに保存され、環境変数にも対応しています
• 🚫 .gitignore を尊重 — 機密ファイルはインデックス化されません
• 🛡️ MCP セキュリティ — ローカル専用サーバーで、検索に外部ネットワークを使用しません
• 📤 クラウドでも安全 — クラウドプロバイダーに送信されるのは、埋め込み対象のコードチャンクのみです。完全にオフラインでインデックス化するにはローカルモデルを使用してください

🤝 コミュニティとサポート

• ⭐ GitHub でスターを付けてください — とても励みになります！
• 🐛 問題を報告
• 💬 ディスカッション
• 📧 [email protected]
• 🌐 muvon.io

⚖️ ライセンス

Apache License 2.0 — 詳細はLICENSEを参照してください。