Octocode

Octocode：エージェント型リサーチプラットフォーム

AI エージェントと開発者のための、エビデンスを重視したコードリサーチです。

Octocode は、ローカルコードと外部コードの両方（GitHub リポジトリ、PR、npm）を、ripgrep + AST 検索、ツリー、正確な読み取り、LSP という一連のツールで調査します。CLI または MCP サーバーとして利用でき、Rust エンジンにより、単一ファイルから巨大なリポジトリまで、高速かつトークン効率の高い結果を提供します。

目次

• クイックスタート
• Octocode を選ぶ理由
• リサーチ向けに構築（ベンチマーク）
• ツール
• MCP
• CLI
• 設定
• 認証方法
• セキュリティ
• 言語サポート
• スキル
• アーキテクチャ
• ドキュメント
• トラブルシューティング
• エージェントのワークフロー

クイックスタート

前提条件： Node.js 20.12+

1. npx で Octocode CLI を実行します

npx octocode --help

2. GitHub で認証します - 省略可能ですが、プライベートリポジトリを利用でき、API レート制限も緩和されます：

npx octocode auth login
npx octocode status       # verify the active token source

3. インターフェースを選択します。 どちらも同じツールと Rust エンジンを使用します。（CLI ではクローンがデフォルトで有効ですが、MCP ではオプトインです。）

🖥️ CLI - ターミナルから直接リサーチできます：

npx octocode

🤖 MCP - ワンクリックでインストールできます：

claude mcp add-json octocode --scope user '{"command":"npx","type":"stdio","args":["octocode-mcp@latest"]}'

その他のクライアント： npx octocode install

MCP サーバーとして使う

MCP クライアントの設定に追加します（または上記のワンクリックインストールを使用します）：

{
  "octocode": {
    "command": "npx",
    "type": "stdio",
    "args": ["octocode-mcp@latest"]
  }
}

GitHub トークンとオプションは env の下に設定します（設定を参照）。

エージェント向けの CLI として使う

npx octocode を実行すれば、エージェントが必要な操作を判断します。引数なしのコマンドを実行すると、組み込みの使用方法とツールの全カタログが表示されるため、MCP クライアントや追加の設定がなくても、どのコーディングエージェントでもすぐに使い方を把握できます。

npx octocode                                         # self-describing usage for agents
npx octocode tools                                   # list every tool
npx octocode tools localSearchCode --scheme          # inspect a tool's schema

すべての MCP ツールは通常のコマンドとしても利用できます。入力は JSON、出力はトークン効率の高い YAML です。ローカルパスはローカルツールに、owner/repo[/path] は GitHub に振り分けられます。

npx octocode tools localSearchCode \
  --queries '{"path":".","searchText":"authenticate","maxFiles":20}'

results:
  - id: localSearchCode-1
    data:
      files:
        - path: src/auth.ts
          matches:
            - line: 12
              value: "export async function authenticate(req: Request) {"

詳しくは octocode.ai をご覧ください。

Octocode を選ぶ理由

エージェントは推測よりも根拠に基づいてコードを書くほうが優れています。Octocode は、ローカルコードと GitHub や npm 上の外部コードという2つの世界を1つのフローで調査し、エージェントがコードを変更、レビュー、説明する前に、簡潔で引用可能なコンテキストを提供します。コードは真実であり、コンテキストは地図です。

多くのツールは一部の作業（ウェブ検索やリポジトリの grep など）だけを行い、固定されたデータを返します。Octocode は一連の作業全体をカバーし、次に必要なデータをエージェント自身が判断できるようにします。

• エージェント主導の効率的なフロー。 一度きりの大量出力ではなく、Octocode は低コストの手順をつないで最適化された調査フローを構築します。コードを広く検索し、一致した正確な行や範囲だけを取得します。スマートなページネーションとすぐに使える軽量化機能により、モデルが必要以上のデータを取得することはありません。すべての結果には、最も低コストで実行できる次の手順のヒントが付いています。
• モノレポにも対応。 あるリポジトリでパターンを見つけ、それを導入した PR をたどり、チャットを離れずに他のリポジトリや自分のファイルでも追跡できます。任意のリポジトリをクローンして、ローカルで調査できます。
• スマートな GitHub フロー。 コード、PR、コミット、Issue、リポジトリに対する並列一括クエリを、検索は広く、読み取りは絞り、意味に基づいて追跡するという一貫した方針で実行できます。
• GitHub がなくても動作。 任意のリポジトリをクローンし、ローカルツール（検索、AST、LSP、コンテンツ）の対象に設定すれば、同じく根拠を優先するフローを利用できます。
• ノイズではなく構造を読み取ります。 70 以上の言語をその場で軽量化・骨格化します。100 KB のファイルを数百トークンにまとめ、定型コードの壁を避けられます。
• 高速で自己完結。 検索、解析、ナビゲーション、秘匿化を、ビルド済みのRust エンジン1つで実行します。ノート PC でも巨大なリポジトリでも高速に動作し、追加のインストールは不要です。
• デフォルトで安全。 モデルに渡すすべてのバイトをスキャンし、まずシークレットを秘匿化します（セキュリティを参照）。

できること（次の手順で推測ではなく、確かなコンテキストが必要なとき）：

調査向けに構築（ベンチマーク）

単純な検索ではなく、調査向けのフロー（複数ステップの追跡、依存関係／呼び出しグラフの連鎖、コミット範囲、影響範囲、複数リポジトリにまたがる PR レビュー）を対象にした、ブラインド形式の直接比較テストです。

仕組み： GitHub に関する質問 30 件 × 3 回の実行。Octocode と、同一の質問を使った gh、gh+Headroom、gh+RTK を比較します（異なるのは CLI のみです）。ブラインド判定者（gpt-5.5）が正確性を評価します。指標はモデルに渡された文字数で、計測ログからカウントします（トークンではなく文字数）。結果： 正確性がほぼ同等の場合、ローカルビルドの主要な実行結果では、Octocode の回答に必要な文字数は、素の gh の 約 2.0 分の 1、gh+Headroom の約 2.6 分の 1、gh+RTK の約 3.2 分の 1です。

▶ インタラクティブレポートを開く · 実行方法／手法 · 質問 · すべてのレポート

ツール

カタログ全体で 17 個のツールを用意しています。 登録される数は、利用する環境と設定するフラグによって異なります。

ghListReleases と ghSearchDiscussions を MCP で有効にするには、設定が 1 つではなく 2 つ必要です。 ENABLE_RELEASES=1 または ENABLE_DISCUSSIONS=1 を設定するとツールがカタログに追加され、 ENABLE_TOOLS="ghListReleases,ghSearchDiscussions" を設定すると登録されます。どちらか一方だけでは ツールは登録されません。どちらも isDefault: false であり、MCP の登録フィルターではデフォルトのツールか、 明示的に許可リストに指定されたツールのみが登録されるためです。 CLI では ENABLE_RELEASES と ENABLE_DISCUSSIONS のフラグだけが必要です。ENABLE_LOCAL と ENABLE_CLONE は true または 1 を受け付けます。ENABLE_RELEASES と ENABLE_DISCUSSIONS は yes と on も受け付けます。 フラグ：設定。

トークン設定。 concise:true はパスとタイトルのみのリストを返します。minify はファイル読み取り時の密度を設定します。symbols は行番号付きの骨組み、standard はコメントと空行を除去した内容（デフォルト）、none は正確なバイト列です。

GitHub ツール

ローカルツール

パッケージ検索

LSP

すべてのツールの完全なスキーマ、フィールド、使用例はdocs/OCTOCODE_TOOLS.md（ドキュメントにリンクされています）に記載されています。

MCP

MCP サーバーは、Octocode のツールカタログを stdio 経由で AI アシスタントに直接公開します。

https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071

手動設定

octocode-mcp を使って、MCP クライアントの設定に追加します。

{
  "octocode": {
    "command": "npx",
    "type": "stdio",
    "args": [
      "octocode-mcp@latest"
    ]
  }
}

GitHub トークンとオプションを env に追加してください。認証と設定を参照してください。

CLI

同じリサーチエンジンを利用でき、MCP クライアントは不要です。ローカルパスはローカルツールに、owner/repo[/path] は GitHub にルーティングされます。npx octocode auth login で一度認証してください（認証を参照）。使用方法の詳細は npx octocode --help を実行してください。

コマンド

ツールコマンド

その他のコマンド

• キャッシュとクローン — npx octocode clone、npx octocode cache fetch|status|clear
• スキル — バンドルされた Octocode スキル用の npx octocode skill list|install|check|info|remove
• 言語サーバー — npx octocode lsp-server list|install|status|uninstall|clean
• セットアップと情報確認 — npx octocode install、npx octocode auth、npx octocode status、npx octocode context

完全な構文、フラグ、終了コードについては、Octocode CLI ガイドをご覧ください。

設定

すべての設定は任意です。Octocode は適切なデフォルト設定で動作します。設定は、優先順位の高い順に次の 3 つのソースから解決されます。

environment variables  >  <octocode-home>/.octocoderc  >  built-in defaults

1. MCP／環境変数（最優先）：クライアントごと、またはプロジェクトごとに、MCP 設定の env またはシェルで設定します。
2. グローバル設定：<octocode-home>/.octocoderc。マシン全体のデフォルト値で、CLI と MCP サーバーの両方が読み込みます。
3. 組み込みのデフォルト値：どちらも設定されていない場合に使用されます。

Octocode ホーム（<octocode-home>）には、グローバル設定、暗号化された認証情報、セッション、統計情報、一時的なマテリアライズ用キャッシュが保存されます。すべてのプラットフォームで、OS のホームディレクトリ内にある .octocode です。macOS と Linux では ~/.octocode、Windows では %USERPROFILE%\.octocode です。OCTOCODE_HOME で変更できます。

値は MCP の env エントリ（クライアントごとに設定され、.octocoderc より優先されます）または <octocode-home>/.octocoderc（コメント付き JSON）でグローバルに設定します。トークンを .octocoderc に保存しないでください — env または npx octocode auth login を使用してください。

よく使う設定

最もよく使われる設定です（注記がない限り、CLI と MCP の両方に適用されます）。

OCTOCODE_HOME、GitHub Enterprise（GITHUB_API_URL）、MCP ツールの許可リスト（TOOLS_TO_RUN／ENABLE_TOOLS／DISABLE_TOOLS）、ネットワークのタイムアウトと再試行については、設定リファレンスをご覧ください。

設定例

~/.octocode/.octocoderc:

{
  "github": {
    "apiUrl": "https://api.github.com"
  },
  "local": {
    "enabled": true,
    "enableClone": true
  },
  "output": {
    "format": "yaml"
  }
}

プロジェクトごとの上書き設定とカスタム LSP サーバーは、ワークスペースの .octocode/ フォルダーに保存します。.octocoderc の完全なスキーマ、コピーして使える設定例、クローンキャッシュの調整、GitHub Enterprise のセットアップ、優先順位の詳細については、設定リファレンスをご覧ください。

認証方法

GitHub を利用するツールには認証が必要です。いずれか 1 つの方法で認証できます。詳細については、認証のセットアップをご覧ください。

方法 1：Octocode CLI（推奨）

npx octocode auth login
npx octocode status       # verify the active token source

対話形式のログインでは、Octocode のブラウザー OAuth または gh auth login を選択できます。Octocode OAuth の認証情報は、暗号化されてディスクに保存されます。

方法 2：GitHub CLI（こちらもサポート）

gh auth login

Octocode は gh トークンを自動的に読み取るため、追加の設定は不要です。

オプション 3：パーソナルアクセストークン（こちらもサポートされています）

シェルで OCTOCODE_TOKEN、GH_TOKEN、または GITHUB_TOKEN を設定します。必要なスコープ：repo、read:user、read:org。

トークンは github.com/settings/tokens で作成してください。

注： トークンをバージョン管理にコミットしないでください。環境変数または安全なシークレット管理を使用してください。

セキュリティ

モデルに渡されるすべてのバイトは、まずスキャンされ、秘匿化されます。 すべてのコンテンツは、入力時も 出力時 も Rust エンジンのシークレットスキャナーを通過するため、シークレットがモデルに届くことはありません。対象には、ローカルファイル、GitHub と npm のレスポンス、エラー、ツールの出力が含まれます。MCP と CLI のどちらでも動作は同じです。

• 入力時と出力時のシークレット秘匿化。 300 種類以上のプロバイダー認証情報パターン（AWS、Azure、GCP、GitHub、OpenAI、Anthropic、Stripe、Slack、1Password など）に加え、汎用 JWT、PEM／秘密鍵、ベアラートークン、データベース接続文字列、高エントロピー文字列に対応しています。マスクされた値には秘匿化の警告が表示されるため、エージェントが把握できます。
• ソースでコンテンツをサニタイズ。 ローカルの読み取り（localGetFileContent、ripgrep、構造検索、バイナリ、ファイル検出、構造）と外部からの取得（GitHub のコード／ファイル、npm）は、境界でのみではなく、読み取り時にスキャンされます。
• パスの安全性。 相対パスの入力は WORKSPACE_ROOT ／設定／cwd を基準に解決され、その後、ローカルの読み取りはエンジンで許可されたルート（デフォルトではホームに加え、ALLOWED_PATHS と Octocode に登録されたルート）に制限されます。シンボリックリンクは解決され、実際のターゲットが再検証されるため、リンクがブロックされた場所へ抜け出すことはありません。
• 機密ファイルはデフォルトでブロック。 既知のシークレットを含むファイルやフォルダーの読み取りでは、内容ではなく秘匿化されたエラーが返されます。対象は、鍵／証明書、.env*、.npmrc／.netrc、クラウド／インフラの認証情報（.aws/、.kube/、*.tfstate）、.git/、ブラウザーのログイン情報、OS のキーチェーン、ウォレットです。全リストは SECURITY.md をご覧ください。
• コマンドの安全性。 通常のローカル検索は octocode-engine 内でプロセス内実行されます。外部ヘルパーはレーンごとに固定され、コマンド／引数が許可リストで制限されており、引数配列を使って spawn 経由で実行されます。シェル文字列もインジェクションもありません。
• スキーマ検証はツールの実行前に行われ、信頼できない入力のサイズと形式は制限されます。
• 認証情報。 GitHub 認証には、環境変数のトークン、AES-256-GCM で暗号化されてディスクに保存される OAuth、または gh CLI を使用します。トークンがログに記録されることはありません。

セキュリティモデル、パイプライン、脅威への対応範囲の詳細： SECURITY.md。 関連項目： 設定と認証 · 認証情報

言語サポート

4 つのコードインテリジェンス軸があり、そのうち 3 つは Rust エンジンにネイティブで備わっており、外部ツールは不要です。

📋 完全なサポートマトリックス： 各拡張子の AST、シグネチャ、LSP、最小化の対応状況については、**完全な形式サポートマトリックス**をご覧ください。

スキル

エージェントスキルは、AI エージェントの機能を拡張するための軽量なオープン形式です。 skills.sh/bgauryy/octocode-mcpで閲覧・インストールできます。

octocode パッケージには、skills/に13 個のスキルが含まれています。それぞれ必要なときにのみリファレンスを読み込む軽量な SKILL.md で構成されているため、組み合わせて使用できます。まずは、証拠を重視したコード作業に役立つ ⭐ Researchから始めましょう。

npx octocode skill list
npx octocode skill install octocode-research --platform pi
npx octocode skill check --json
npx octocode skill help

中核となる調査と抽出

計画とアーキテクチャ

評価とレビュー

エージェントのオーケストレーション

ウェブ自動化ワークフロー： octocode-scraping はまず安全な静的パス（取得／クロール／抽出 → ローカルコーパス → graph v2）を実行します。グラフによって動的アクションが明らかになった場合、または静的出力がブロックされている／不十分な場合は、octocode-chrome-devtools で実際の操作可否、Cookie／ストレージ、ネットワーク／HAR の本文、スクリーンショット、認証が必要な状態を検証します。発見した URL／データ／成果物をスクレイピングコーパスに戻し、継続的な検証に利用できます。

アーキテクチャ

yarn workspaces のモノレポです。MCP サーバーとCLIは、共通の TypeScript ツールコアを利用する薄いフロントエンドであり、ツールコアは CPU 負荷の高いすべての処理を単一のRust エンジンに委譲します（napi-rs を介してコンパイルし、事前ビルド済みの .node バイナリを生成します）。ツールカタログも、セキュリティレイヤーも、レスポンス整形器も 1 つで、2 つの方法からアクセスできます。

graph LR
    CLI["octocode<br/>CLI"]
    MCP["octocode-mcp<br/>MCP server, stdio"]
    VSC["VS Code extension<br/>OAuth + install"]
    CORE["octocode-tools-core<br/>tools, GitHub client, auth, pagination, security bridge"]
    ENGINE["octocode-engine (Rust)<br/>secrets, minify, AST, signatures, ripgrep/diff/YAML, LSP"]
    EXT["GitHub API, local FS + ripgrep, language servers"]

    CLI --> CORE
    MCP --> CORE
    VSC -. starts .-> MCP
    CORE --> ENGINE
    CORE --> EXT
    ENGINE --> EXT

    style ENGINE fill:#1a1a2e,stroke:#e75d2a,color:#fff

リクエストフローは、MCP と CLI のどちらから呼び出しても同じです。

client → sanitize inputs (Rust) → run tool (GitHub / FS / LSP) → sanitize + YAML-serialize + paginate (Rust) → result + next-step hints

単一の Rust エンジンが、シークレット検出、サニタイズ、パスとコマンドの検証、ミニファイ（70 以上の言語）、シグネチャ抽出、構造的 AST 検索、ripgrep の解析、差分のフィルタリング、YAML シリアライズ、LSP を担います。そのため、Node のイベントループがブロックされず、ネイティブローダーが重複することもありません。エンジンは darwin（arm64/x64）、linux（arm64/x64、gnu と musl）、win32-x64 向けに事前ビルド済みで提供されるため、実行時に Rust のツールチェーンは不要です。

パッケージ

packages/octocode-benchmark（非公開、未公開）には、ベンチマークの方法論、評価、実行アーティファクトが含まれています。ドキュメントを参照してください。

ドキュメント

ウェブサイト：octocode.ai · 製品ドキュメント：github.com/bgauryy/octocode/tree/main/docs。このセクションが正式なドキュメント一覧です。ベンチマークの方法論、評価、実行アーティファクトは packages/octocode-benchmark にあります。

トラブルシューティング

Node.js または環境に関する問題ですか？ 組み込みの doctor コマンドを実行して、環境を確認してください。

npx node-doctor

よくある問題：

• GitHub 認証エラー： Personal Access Token（PAT）に repo および read:user スコープがあることを確認してください。CLI を使用している場合は、npx octocode auth login を実行して認証を更新してください。
• MCP 接続の問題： AI アシスタント（Cursor や Windsurf など）が接続できない場合は、まずターミナルで npx octocode auth login を実行したことを確認するか、MCP の env 設定で OCTOCODE_TOKEN を明示的に渡してください。
• ネイティブエンジンのエラー： Octocode はビルド済みの Rust エンジンを使用します。Linux で読み込みに失敗する場合は、システムが glibc または musl と互換性があることを確認してください。macOS／Windows では、サポート対象のアーキテクチャ（x64 または arm64）を使用していることを確認してください。

エージェントのワークフロー

推奨の開発モード：Pi + Octocode

Pi は、哲学として 「MCP よりも README のある CLI ツール（スキル）」 を掲げる、高速でローカルファーストなコーディングエージェントです。Pi と Octocode を組み合わせると、無駄がなく、証拠に基づいた開発ループを実現できます。Pi が編集し、Octocode が調査します。必要な範囲に応じて、次の 2 つの方法から選べます。

• スキル方式 — 推奨。最もシンプルです。 octocode-research スキルを Pi のグローバルスキルディレクトリに配置します。このスキルは Octocode の CLI を直接操作するため、MCP のトランスポートは不要で、トークンのオーバーヘッドも最小限です。Pi が自動的に検出します。

  npx octocode skill install octocode-research --platform pi
  

• アダプター方式 — ツールをすべて利用できます。 pi-mcp-adapter をインストールすると、Octocode の MCP ツールを単一の約 200 トークンのプロキシツール経由で利用できます。ツールが呼び出されるまで、サーバーは切断された状態を保ちます。ENABLE_CLONE=true を設定すると、クローンツールを有効にできます。

調査に基づくループ

エージェントの失敗の多くは、編集前に起きます。誰がその動作を担当しているのかを推測したり、ソースを読まずにスニペットを信用したり、影響範囲を確認する前に編集したりすることが原因です。代わりに、より低コストなループを実行しましょう。ツリーで全体像を把握し、検索し、正確な証拠を読み、識別が重要な場合は AST／LSP を使い、その後パッチを適用して検証します。編集はホストが行い、Octocode は地図となり、スキルがその習慣を定着させます。

マニフェスト

「コードは真実ですが、コンテキストは地図です。」 Octocode の哲学を理解するには、調査主導型開発のための Octocode マニフェストをお読みください。