Claude Octopus

Claude Octopus

1つの頭脳、多数の腕。

Claude Agent SDKをラップした MCP サーバーです。任意の MCP クライアントから、それぞれ独自のモデル、ツール、システムプロンプト、個性を持つ複数の特化型 Claude Code エージェントを実行できます。

理由

Claude Code は強力です。しかし、1つのインスタンスですべてを同じ方法で処理します。ファイルを読むだけの厳格なコードレビュー担当が欲しいときもあります。TDD を基本とするテスト作成担当、Haiku を使う安価で手早いヘルパー、Opus を使う深く考えるエージェントが欲しいときもあります。

Claude Octopus を使えば、必要な数だけこのようなインスタンスを起動できます。同じバイナリで、設定はそれぞれ異なります。それぞれが MCP クライアントに独立したツールとして表示されます。

前提条件

• Node.js >= 18
• Claude Code — Claude Agent SDKは依存関係として同梱されていますが、内部で Claude Code を起動するため、正常に動作する claude CLI のインストールが必要です
• Anthropic API キー（ANTHROPIC_API_KEY 環境変数）または有効な Claude Code OAuth セッション

インストール

3つの方法から、お使いの MCP クライアントに合ったものを選んでください。

npm（最も直接的）

npm install claude-octopus

npx（インストール不要）

インストールを完全に省略できます。.mcp.jsonでclaude-octopus@latestを参照すれば、クライアントが必要に応じて取得します（以下のクイックスタートを参照）。

MCP Registry

このサーバーは、MCP Registryに**io.github.xiaolai/claude-octopus**という名前で公開されています。MCP Registry に対応した MCP クライアントは、npm に直接触れることなく、その名前で検索してインストールできます。

クイックスタート

最も手早く始める方法です。

npx claude-octopus init

この対話型ウィザードでは、テンプレートを選択し、お使いの MCP クライアントを検出して、設定を書き込みます。

または、.mcp.jsonに手動で追加します。

{
  "mcpServers": {
    "claude": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_PERMISSION_MODE": "bypassPermissions"
      }
    }
  }
}

これにより、次の6つのツールが利用できるようになります。

ツール	用途
claude_code	タスクを送り、結果を取得します
claude_code_reply	会話を続けます
claude_code_timeline	ワークフローのタイムラインを照会します
claude_code_transcript	セッションのトランスクリプト全文を読み取ります
claude_code_sessions	Claude Code のセッション履歴（このプロジェクト、またはすべて）を一覧表示します
claude_code_report	HTML レポートを生成します

これで完了です。ワークフローの可観測性を完全に組み込んだ Claude Code を、ツールとして利用できます。

複数のエージェント

真価を発揮するのは、設定の異なる複数のインスタンスを実行するときです。

{
  "mcpServers": {
    "code-reviewer": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "code_reviewer",
        "CLAUDE_SERVER_NAME": "code-reviewer",
        "CLAUDE_DESCRIPTION": "Strict code reviewer. Finds bugs and security issues. Read-only.",
        "CLAUDE_MODEL": "opus",
        "CLAUDE_ALLOWED_TOOLS": "Read,Grep,Glob",
        "CLAUDE_APPEND_PROMPT": "You are a strict code reviewer. Report real bugs, not style preferences.",
        "CLAUDE_EFFORT": "high"
      }
    },
    "test-writer": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "test_writer",
        "CLAUDE_SERVER_NAME": "test-writer",
        "CLAUDE_DESCRIPTION": "Writes thorough tests with edge case coverage.",
        "CLAUDE_MODEL": "sonnet",
        "CLAUDE_APPEND_PROMPT": "Write tests first. Cover edge cases. TDD."
      }
    },
    "quick-qa": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "quick_qa",
        "CLAUDE_SERVER_NAME": "quick-qa",
        "CLAUDE_DESCRIPTION": "Fast answers to quick coding questions.",
        "CLAUDE_MODEL": "haiku",
        "CLAUDE_MAX_BUDGET_USD": "0.02",
        "CLAUDE_EFFORT": "low"
      }
    }
  }
}

MCP クライアントには、各エージェント専用の個別のツール（code_reviewer、test_writer、quick_qa）が表示されます。

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

エージェントはコーディネーターパターンで連携できます。1つのエージェントがCLAUDE_MCP_SERVERSを介して他のエージェントを内部 MCP ツールとして持ち、そのシステムプロンプトがパイプラインを制御します。

{
  "mcpServers": {
    "publishing-house": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_TOOL_NAME": "publishing_house",
        "CLAUDE_SERVER_NAME": "publishing-house",
        "CLAUDE_MODEL": "opus",
        "CLAUDE_PERMISSION_MODE": "bypassPermissions",
        "CLAUDE_APPEND_PROMPT": "You are a publishing house coordinator. Dispatch tasks to your specialist agents and drive the pipeline to completion.",
        "CLAUDE_MCP_SERVERS": "{\"researcher\":{\"command\":\"npx\",\"args\":[\"claude-octopus@latest\"],\"env\":{\"CLAUDE_TOOL_NAME\":\"researcher\",\"CLAUDE_SERVER_NAME\":\"researcher\",\"CLAUDE_MODEL\":\"sonnet\",\"CLAUDE_PERMISSION_MODE\":\"bypassPermissions\"}},\"architect\":{\"command\":\"npx\",\"args\":[\"claude-octopus@latest\"],\"env\":{\"CLAUDE_TOOL_NAME\":\"architect\",\"CLAUDE_SERVER_NAME\":\"architect\",\"CLAUDE_MODEL\":\"opus\",\"CLAUDE_PERMISSION_MODE\":\"bypassPermissions\"}}}"
      }
    }
  }
}

コーディネーターエージェントは、researcher、architectなどを MCP ツールとして自律的に呼び出します。完全に自律的に動作し、完了するまで人間が介入する必要はありません。すべての呼び出しは共有タイムラインに記録されます。

エージェントファクトリー

設定を手作業で書きたくない場合は、ファクトリーインスタンスを追加します。

{
  "mcpServers": {
    "agent-factory": {
      "command": "npx",
      "args": ["claude-octopus@latest"],
      "env": {
        "CLAUDE_FACTORY_ONLY": "true",
        "CLAUDE_SERVER_NAME": "agent-factory"
      }
    }
  }
}

これにより、対話型ウィザードであるcreate_claude_code_mcpツールが1つだけ公開されます。「ファイルだけを読む厳格なコードレビュー担当」のように希望を伝えると、カスタマイズ可能なすべてのオプションを一覧表示したうえで、.mcp.jsonのエントリーを生成します。

ファクトリー専用モードでは、クエリツールは登録されず、ウィザードだけが登録されます。これによりルーティングがすっきりします。ファクトリーがエージェントを作成し、エージェントが作業を行います。

初期化ウィザード

JSON を手作業で編集したくない場合、初期化ウィザードを使えば、何もない状態から30秒で動作する状態にできます。

npx claude-octopus init

  Claude Octopus — init wizard

  One brain, many arms. Let's set up your agents.

Pick a template (or build your own):

  1. Code Review Team — Reviewer + test writer + security auditor
  2. Publishing House — Researcher + architect + editor + proofreader
  3. Tiered Models — Haiku for quick Q&A, Sonnet for coding, Opus for hard problems
  4. Solo Agent — Single Claude Code agent with sensible defaults
  5. Agent Factory — Interactive wizard that generates agent configs on demand
  6. Custom — describe your own agent(s)

Choice [1-6]:

インストール済みの MCP クライアント（Claude Desktop、Claude Code、Cursor、Windsurf）を自動検出し、既存の設定にマージして、上書き前に警告します。

メニューをスキップする

npx claude-octopus init --template code-review-team
npx claude-octopus init --template tiered-models
npx claude-octopus init --template publishing-house

テンプレート

組み込みテンプレートを5つ用意しています。実戦で十分に検証済みで、すぐに使えます。

テンプレート	エージェント	目的
code-review-team	code-reviewer (opus), test-writer (sonnet), security-auditor (opus)	徹底したコードレビューパイプライン
publishing-house	researcher (sonnet), architect (opus), editor (sonnet), proofreader (haiku)	複数段階のコンテンツ／コードパイプライン
tiered-models	quick-qa (haiku), coder (sonnet), deep-thinker (opus)	タスクに適したモデル
solo-agent	claude (default)	単一エージェントのクイックセットアップ
factory	agent-factory	必要に応じて設定を生成

各エージェントには、適切なモデル、ツール、エフォートレベル、システムプロンプトがあらかじめ調整されています。

ダッシュボード

エージェントをリアルタイムで監視できます。

npx claude-octopus dashboard

http://localhost:3456 にローカル Web ダッシュボードが開き、以下を確認できます。

• ライブ統計 — 実行数、呼び出し数、コスト、SDK ターン数、応答数、エラー数の合計
• 最近のアクティビティ — 最新の実行に関するエージェントカード
• 実行テーブル — すべての実行のコスト、所要時間、ステータス
• 自動更新 — SSE 接続により、エージェントの実行に合わせて更新をプッシュ

# Custom port
npx claude-octopus dashboard --port 8080

ダッシュボードは、_timeline ツールと _report ツールで使用されているものと同じタイムラインインデックスを読み込みます。追加の設定は必要ありません。

ツール

factory 以外の各インスタンスは、以下のツールを公開します。

ツール	目的
<name>	エージェントにタスクを送信し、応答と session_id、run_id を取得します
<name>_reply	session_id を使って、以前の会話を続けます
<name>_timeline	エージェント間ワークフローのタイムラインを照会します
<name>_transcript	Claude Code のストレージからセッションの完全なトランスクリプトを取得します
<name>_sessions	Claude Code のセッション履歴を一覧表示します。デフォルトではこのプロジェクトのみを対象とし、all_projects: true を指定するとすべてのプロジェクトが対象になります
<name>_report	実行単位またはすべての実行を対象に、自己完結型 HTML レポートを生成します

クエリと返信のパラメーター

パラメーター	説明
prompt	タスクまたは質問（必須）
run_id	ワークフロー実行 ID。関連するエージェント呼び出しを1つのタイムラインにまとめます。省略すると自動生成され、すべての応答で返されるため、引き継ぎに使用できます。
cwd	作業ディレクトリの上書き
model	モデルの上書き（sonnet、opus、haiku、または完全な ID）
tools	使用可能なツールを制限します（サーバー側の制限と共通するものが適用されます）
disallowedTools	追加のツールをブロックします（サーバーのブラックリストに追加されます）
additionalDirs	エージェントがアクセスできる追加ディレクトリ
plugins	読み込む追加のプラグインパス
effort	思考エフォート（low、medium、high、max）
permissionMode	権限モード（制限を強めることのみ可能で、緩めることはできません）
maxTurns	エージェントループの最大往復回数（エフォートカウンターを参照）
maxBudgetUsd	米ドルでの最大支出額
systemPrompt	追加のプロンプト（サーバーのデフォルトに追加されます）

タイムライン

すべてのエージェント呼び出しは、~/.claude-octopus/timelines/timeline.jsonl にある軽量な JSONL インデックスに記録されます。これにより、複数エージェントの相関付けの問題を解決します。複数のエージェントがワークフローに参加する場合、タイムラインは、どのセッションが同じ実行に属するか、どの順番で実行されたか、それぞれがどのような役割を果たしたかを追跡します。

セッションの完全なトランスクリプトは、Claude Code 自身のストレージ（~/.claude/projects/）に保存されます。タイムラインは目次にすぎず、session_id を介して相互参照するエントリごとのサイズは約200バイトです。

graph TB
    subgraph "Timeline Index (~200 bytes/entry)"
        TL["~/.claude-octopus/timelines/timeline.jsonl"]
    end

    subgraph "Claude Code Session Storage (full transcripts)"
        S1["~/.claude/projects/.../ses-aaa.jsonl"]
        S2["~/.claude/projects/.../ses-bbb.jsonl"]
        S3["~/.claude/projects/.../ses-ccc.jsonl"]
    end

    TL -->|"session_id cross-ref"| S1
    TL -->|"session_id cross-ref"| S2
    TL -->|"session_id cross-ref"| S3

仕組み

1. <name> と <name>_reply の呼び出しごとに、タイムラインに1行が追加されます
2. run_id を渡すと、同じ run_id を共有するすべてのエージェントが1つの実行にまとめられます
3. run_id を省略すると、自動生成されて応答で返されます。後続のエージェントに渡すことで、同じ実行にまとめられます

タイムラインの照会

# List all runs
<name>_timeline({})

# Show one run's agent sequence
<name>_timeline({ run_id: "abc-123" })

# Look up a specific session
<name>_timeline({ session_id: "ses-xyz" })

# Retrieve full transcript (separate tool)
<name>_transcript({ session_id: "ses-xyz" })

複数エージェントのワークフロー例

Host:  researcher({ prompt: "Research X", run_id: "pub-001" })
       → { run_id: "pub-001", session_id: "ses-aaa", result: "..." }

Host:  architect({ prompt: "Structure based on...", run_id: "pub-001" })
       → { run_id: "pub-001", session_id: "ses-bbb", result: "..." }

Host:  verifier({ prompt: "Check this plan", run_id: "pub-001" })
       → { run_id: "pub-001", session_id: "ses-ccc", result: "..." }

Later: researcher_timeline({ run_id: "pub-001" })
       → [
           { agent: "researcher", session_id: "ses-aaa", cost: 0.05, turns: 4, tool_calls: 3, response_groups: 2 },
           { agent: "architect",  session_id: "ses-bbb", cost: 0.08, turns: 6, tool_calls: 5, response_groups: 3 },
           { agent: "verifier",   session_id: "ses-ccc", cost: 0.03, turns: 3, tool_calls: 2, response_groups: 2 },
         ]

Later: researcher_transcript({ session_id: "ses-aaa" })
       → full conversation transcript from Claude Code's storage

HTML レポート

エージェントの実行順序の可視化、コストの内訳、折りたたみ可能なトランスクリプトを含む、自己完結型 HTML レポートを生成します。ダークテーマで外部依存関係はなく、1つのファイルで、どのブラウザーでも開けます。

MCP ツールから

<name>_report({})                        # index of all runs
<name>_report({ run_id: "pub-001" })     # detailed report for one run

CLI 経由

# Index of all runs
npx claude-octopus report --out index.html

# Detailed report for one run
npx claude-octopus report pub-001 --out report.html
open report.html

# Without transcripts (faster, smaller file)
npx claude-octopus report pub-001 --no-transcripts --out report.html

# To stdout (pipe-friendly)
npx claude-octopus report pub-001 > report.html

レポートの内容

• 実行の概要 — エージェント数、合計コスト、所要時間、SDK ターン数、応答数、ツール呼び出し数
• タイムラインバー — 各エージェントを示す番号付きのドット（緑＝成功、赤＝エラー）
• エージェントカード — 実行時間、コスト、作業量カウンター、セッション ID、プロンプトの抜粋
• 折りたたみ可能なトランスクリプト — エージェントごとのすべてのツール呼び出し、推論、結果

作業量カウンターの読み方

3つの数値で、呼び出しにかかった作業量を表します。これらは 互換性がなく、最初の数値は意外に感じるかもしれません。

指標	カウント対象
num_turns（SDK ターン数として表示）	Agent SDK からの生の値です。ランタイムに対して計測され、tool_use ブロックと最終応答を追跡します。API の往復回数ではありません。
response_groups（応答数）	メインエージェントループ内の個別のアシスタント応答です。1回の API 往復につき1つで、その応答が並列で呼び出したツールの数には関係しません。
tool_calls（ツール呼び出し数）	メインエージェントループ全体で発行された tool_use ブロックです。

エージェントが複数のツールを並列で呼び出すと、num_turns は表示される応答数よりも速く増加します。アシスタントの応答が3回で、4回のツール呼び出しを行った実行では、num_turns: 5、response_groups: 3、tool_calls: 4 と報告されます。一方、maxTurns は往復回数に基づいて適用されます。同じ実行は maxTurns: 3 では完了し、maxTurns: 2 では中断されます。そのため、maxTurns は SDK ターン数ではなく、応答数を基準に設定してください。

どちらの新しいカウンターもメインエージェントループのみを対象とします。サブエージェント（Task）内の作業は独自のループに属するため、含まれません。古いバージョンで書き込まれたタイムラインエントリーにはどちらもなく、誤ってゼロと表示されるのではなく — と表示されます。

設定

すべての設定は .mcp.json 内の環境変数で行います。環境変数はすべて省略可能です。

識別情報

環境変数	説明	デフォルト
CLAUDE_TOOL_NAME	ツール名のプレフィックス（<name>、<name>_reply、<name>_timeline、<name>_transcript、<name>_report を生成）	claude_code
CLAUDE_DESCRIPTION	ホスト AI に表示されるツールの説明	generic
CLAUDE_SERVER_NAME	プロトコルのハンドシェイクで使われる MCP サーバー名	claude-octopus
CLAUDE_FACTORY_ONLY	ファクトリーウィザードツールのみを公開	false

エージェント

環境変数	説明	デフォルト
CLAUDE_MODEL	モデル（sonnet、opus、haiku、または完全な ID）	SDK のデフォルト
CLAUDE_CWD	作業ディレクトリ	process.cwd()
CLAUDE_PERMISSION_MODE	default、acceptEdits、bypassPermissions、plan	default
CLAUDE_ALLOWED_TOOLS	許可するツールのカンマ区切りリスト（利用可能なツール）	すべて
CLAUDE_DISALLOWED_TOOLS	禁止するツールのカンマ区切りリスト	なし
CLAUDE_MAX_TURNS	呼び出しごとのエージェントループの最大往復回数	無制限
CLAUDE_MAX_BUDGET_USD	呼び出しごとの最大支出額	無制限
CLAUDE_EFFORT	low、medium、high、max	SDK のデフォルト

プロンプト

環境変数	説明
CLAUDE_SYSTEM_PROMPT	デフォルトの Claude Code システムプロンプトを置き換えます
CLAUDE_APPEND_PROMPT	デフォルトのプロンプトに追加します（通常はこちらを使います）

詳細設定

環境変数	説明
CLAUDE_ADDITIONAL_DIRS	アクセスを許可する追加ディレクトリ（カンマ区切り）
CLAUDE_PLUGINS	ローカルプラグインのパス（カンマ区切り）
CLAUDE_MCP_SERVERS	内部エージェント向けの MCP サーバー（JSON）
CLAUDE_PERSIST_SESSION	true/false — セッション再開を有効にします（デフォルト：true）
CLAUDE_SETTING_SOURCES	読み込む設定：user、project、local
CLAUDE_SETTINGS	設定 JSON のパスまたはインライン JSON
CLAUDE_BETAS	ベータ機能（カンマ区切り）

タイムライン

環境変数	説明	デフォルト
CLAUDE_TIMELINE_DIR	エージェント間のタイムラインインデックスを保存するディレクトリ	~/.claude-octopus/timelines

認証

環境変数	説明	デフォルト
ANTHROPIC_API_KEY	このエージェント用の Anthropic API キー	親から継承
CLAUDE_CODE_OAUTH_TOKEN	このエージェント用の Claude Code OAuth トークン	親から継承

両方とも未設定のままにすると、親プロセスから認証情報が継承されます。別のアカウントや請求元を使用する場合は、エージェントごとにどちらか一方を設定してください。

値にカンマが含まれる場合、リストには JSON 配列を使用します：["path,with,comma", "/normal"]

セキュリティ

• 権限モードのデフォルトは default です — 明示的に bypassPermissions を設定しない限り、ツールの実行には承認が必要です。
• cwd の上書き時もエージェントの知識は保持されます — ホストが cwd を上書きすると、エージェントが自身のコンテキストに引き続きアクセスできるよう、設定済みのベースディレクトリが自動的に additionalDirectories に追加されます。
• ツールの制限は狭めることのみ可能で、広げることはできません — 呼び出しごとの tools はサーバーの制限と交差し、ツールを追加することはできず、削除のみ可能です。disallowedTools は統合され、追加のツールのみブロックできます。
• _reply と _transcript ツールは永続化設定に従います — CLAUDE_PERSIST_SESSION=false の場合は登録されません。
• タイムラインへの書き込みはベストエフォートです — タイムラインへの追加に失敗しても、主要なクエリがブロックされたり失敗したりすることはありません。

アーキテクチャ

graph TB
    subgraph "MCP Client (Claude Desktop, Cursor, etc.)"
        C["Sees: code_reviewer, test_writer, quick_qa"]
    end

    C -->|"JSON-RPC / stdio"| O1
    C -->|"JSON-RPC / stdio"| O2
    C -->|"JSON-RPC / stdio"| O3

    subgraph "Claude Octopus Instances"
        O1["code-reviewer<br/>model=opus, tools=Read,Grep,Glob"]
        O2["test-writer<br/>model=sonnet"]
        O3["quick-qa<br/>model=haiku, budget=$0.02"]
    end

    O1 -->|"Agent SDK query()"| SDK["Claude Agent SDK"]
    O2 -->|"Agent SDK query()"| SDK
    O3 -->|"Agent SDK query()"| SDK

    O1 -->|"append"| TL["Timeline Index<br/>~/.claude-octopus/timelines/"]
    O2 -->|"append"| TL
    O3 -->|"append"| TL

    SDK -->|"persist"| SS["Session Storage<br/>~/.claude/projects/"]
    TL -.->|"cross-ref"| SS

比較

機能	組み込みの claude	claude-code-mcp	Claude Octopus
アプローチ	組み込み	CLI ラッピング	Agent SDK
インスタンスごとのツール	16 個の生のツール	1 つのプロンプトツール	5 つ（プロンプト、返信、タイムライン、トランスクリプト、レポート）
複数インスタンス	いいえ	いいえ	はい
インスタンスごとの設定	いいえ	いいえ	はい（環境変数 20 個）
初期化ウィザード	いいえ	いいえ	はい（init ＋ 5 つのテンプレート）
ファクトリーウィザード	いいえ	いいえ	はい
セッションの継続性	いいえ	いいえ	はい
エージェント間のタイムライン	いいえ	いいえ	はい
Web ダッシュボード	いいえ	いいえ	はい（ライブ、SSE）
HTML レポート	いいえ	いいえ	はい

開発

pnpm install
pnpm build       # compile TypeScript
pnpm test        # run tests (vitest)
pnpm test:coverage  # coverage report

ライセンス

ISC - Xiaolai Li