Claude Octopus

Claude Octopus

一个大脑，多只触手。

一个封装 Claude Agent SDK 的 MCP 服务，让你可以从任意 MCP 客户端运行多个专精的 Claude Code Agent——每个 Agent 都有自己的模型、工具、系统提示词和个性。

为什么使用

Claude Code 功能强大，但单个实例做所有事情的方式都一样。有时，你需要一个严格的代码审查员，只读取文件；一个默认采用 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 会话

安装

有三种方式，选择最适合你的 MCP 客户端的方式。

npm（最直接）

npm install claude-octopus

npx（无需安装）

完全跳过安装步骤——在 .mcp.json 中引用 claude-octopus@latest，客户端会按需获取（见下文的快速开始）。

MCP Registry

此服务已发布到 MCP Registry，名称为 io.github.xiaolai/claude-octopus。支持 Registry 的 MCP 客户端可以按此名称解析并安装，无需直接使用 npm。

快速开始

最快的入门方式：

npx claude-octopus init

这个交互式向导可让你选择模板、检测 MCP 客户端，并为你写入配置。

也可以手动添加到 .mcp.json：

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

这将提供六个工具：

工具	用途
claude_code	发送任务并获取结果
claude_code_reply	继续对话
claude_code_timeline	查询工作流时间线
claude_code_transcript	阅读完整会话记录
claude_code_sessions	列出 Claude Code 会话历史（当前项目或全部项目）
claude_code_report	生成 HTML 报告

就这样——你现在可以将 Claude Code 作为工具使用，并内置完整的工作流可观测性。

多个 Agent

真正强大的地方在于运行多个采用不同配置的实例：

{
  "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 客户端会看到每个 Agent 对应的独立工具——code_reviewer、test_writer、quick_qa——每个都针对特定用途打造。

多 Agent 编排

Agent 可以通过协调器模式进行协作：一个 Agent 通过 CLAUDE_MCP_SERVERS 将其他 Agent 作为内部 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\"}}}"
      }
    }
  }
}

协调器 Agent 会自主调用 researcher、architect 等 MCP 工具——完全自主运行，直到任务完成前都无需人工介入。每次调用都会记录在共享时间线中。

Agent 工厂

不想手动编写配置？添加一个工厂实例：

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

这会提供一个 create_claude_code_mcp 工具——一个交互式向导。告诉它你想要什么（“一个只读取文件的严格代码审查员”），它就会为你生成 .mcp.json 条目，并列出所有可自定义的选项。

在仅工厂模式下，不会注册查询工具——只有向导。这样可以让路由保持清晰：工厂创建 Agent，Agent 执行工作。

初始化向导

不想手动编辑 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

模板

五种内置模板，经过实战检验，可直接使用：

模板	Agent	用途
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)	单个 Agent，快速设置
factory	agent-factory	按需生成配置

每个 Agent 都预先配置了合适的模型、工具、工作强度和系统提示词。

控制面板

实时监控你的 Agent：

npx claude-octopus dashboard

打开位于 http://localhost:3456 的本地网页控制面板，其中包含：

• 实时统计 — 运行次数、调用次数、成本、SDK 轮次、响应和错误的总计
• 近期活动 — 最近一次运行的 Agent 卡片
• 运行列表 — 所有运行及其成本、时长和状态
• 自动刷新 — SSE 连接会在 Agent 运行时推送更新

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

控制面板读取 _timeline 和 _report 工具使用的同一时间线索引。无需额外配置。

工具

每个非 factory 实例都会公开以下工具：

工具	用途
<name>	向 Agent 发送任务并获取响应、session_id 和 run_id
<name>_reply	通过 session_id 继续之前的对话
<name>_timeline	查询跨 Agent 工作流时间线
<name>_transcript	从 Claude Code 的存储中检索完整会话记录
<name>_sessions	列出 Claude Code 会话历史记录 — 默认列出此项目的记录，或使用 all_projects: true 列出所有项目的记录
<name>_report	为一次运行或所有运行生成独立的 HTML 报告

查询和回复参数

参数	描述
prompt	任务或问题（必填）
run_id	工作流运行 ID — 将相关 Agent 调用归为同一条时间线。若未提供，则自动生成；每个响应都会返回该 ID，以便传递给后续调用。
cwd	覆盖工作目录
model	覆盖模型（sonnet、opus、haiku 或完整 ID）
tools	限制可用工具（与服务端限制取交集）
disallowedTools	禁止使用其他工具（与服务端黑名单取并集）
additionalDirs	Agent 可访问的其他目录
plugins	要加载的其他插件路径
effort	思考强度（low、medium、high、max）
permissionMode	权限模式（只能收紧，不能放宽）
maxTurns	Agent 循环往返的最大次数（参见读取工作强度计数器）
maxBudgetUsd	最高支出（美元）
systemPrompt	追加的提示词（附加到服务端默认提示词之后）

时间线

每次 Agent 调用都会记录在 ~/.claude-octopus/timelines/timeline.jsonl 中的轻量级 JSONL 索引里。这解决了多 Agent 关联问题：当多个 Agent 参与同一工作流时，时间线会记录哪些会话属于同一次运行、它们的执行顺序，以及各自承担的角色。

完整的会话记录仍保存在 Claude Code 自身的存储中（~/.claude/projects/）。时间线只是目录，每条记录约 200 字节，通过 session_id 交叉引用会话。

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 都会向时间线追加一行
2. 如果传入 run_id，所有共享该 run_id 的 Agent 都会归为同一次运行
3. 如果省略 run_id，系统会自动生成一个并在响应中返回 — 将其传给后续 Agent，即可将它们归为同一组

查询时间线

# 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" })

多 Agent 工作流示例

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 报告，包含 Agent 顺序可视化、成本明细和可折叠的会话记录。采用深色主题，无外部依赖 — 仅一个文件，可在任意浏览器中打开。

通过 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

报告内容

• 运行摘要 — Agent 数量、总成本、耗时、SDK 轮次、响应数、工具调用数
• 时间线条 — 每个 Agent 对应一个编号圆点（绿色 = 成功，红色 = 出错）
• Agent 卡片 — 耗时、成本、工作量计数、会话 ID、提示词摘录
• 可折叠的记录 — 每个 Agent 的完整工具调用、推理过程和结果

解读工作量计数

三个数字描述一次调用所耗费的工作量。它们不能互换，其中第一个最容易让人感到意外：

指标	统计内容
num_turns（显示为 SDK 轮次）	Agent SDK 返回的原始值。根据运行时的统计方式，它记录 tool_use 块加上最终响应，而非 API 往返次数。
response_groups（响应数）	主 Agent 循环中的不同助手响应——每次 API 往返对应一个，无论该响应并行调用了多少个工具。
tool_calls（工具调用数）	主 Agent 循环中发出的 tool_use 块数量。

当 Agent 并行调用多个工具时，num_turns 的增长速度会快于可见响应数。一次运行中，3 个助手响应发起了 4 次工具调用，报告值为 num_turns: 5、response_groups: 3、tool_calls: 4。与此同时，maxTurns 按往返次数限制：同一次运行在 maxTurns: 3 时可以完成，在 maxTurns: 2 时则会中止。因此，设置 maxTurns 时应依据响应数，而不是 SDK 轮次。

这两个新计数器仅涵盖主 Agent 循环——子 Agent（Task）中的工作属于其自身循环，不计入其中。旧版本写入的时间线条目不包含这两个计数器，显示为 —，而不是误报为零。

配置

所有配置均通过 .mcp.json 中的环境变量完成。所有环境变量都是可选的。

身份

环境变量	描述	默认值
CLAUDE_TOOL_NAME	工具名称前缀（生成 <name>、<name>_reply、<name>_timeline、<name>_transcript、<name>_report）	claude_code
CLAUDE_DESCRIPTION	向宿主 AI 显示的工具描述	通用
CLAUDE_SERVER_NAME	协议握手中的 MCP 服务名称	claude-octopus
CLAUDE_FACTORY_ONLY	仅公开工厂向导工具	false

Agent

环境变量	描述	默认值
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	每次调用允许的 Agent 循环往返次数上限	不限
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	内部 Agent 使用的 MCP 服务（JSON）
CLAUDE_PERSIST_SESSION	true/false — 启用会话恢复（默认值：true）
CLAUDE_SETTING_SOURCES	要加载的设置：user、project、local
CLAUDE_SETTINGS	设置 JSON 文件路径或内联 JSON
CLAUDE_BETAS	Beta 功能（以逗号分隔）

时间线

环境变量	描述	默认值
CLAUDE_TIMELINE_DIR	跨 Agent 时间线索引的目录	~/.claude-octopus/timelines

身份验证

环境变量	描述	默认值
ANTHROPIC_API_KEY	此 Agent 的 Anthropic API 密钥	从父进程继承
CLAUDE_CODE_OAUTH_TOKEN	此 Agent 的 Claude Code OAuth 令牌	从父进程继承

两者都留空即可从父进程继承身份验证信息。为每个 Agent 设置其中一个变量，即可使用不同的账户或计费来源。

值中包含逗号时，列表可接受 JSON 数组：["path,with,comma", "/normal"]

安全性

• 权限模式默认为 default——除非显式设置 bypassPermissions，否则工具执行会提示请求批准。
• cwd 覆盖会保留 Agent 知识——当宿主覆盖 cwd 时，系统会自动将 Agent 配置的基目录添加到 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 个模板）
工厂向导	否	否	是
会话连续性	否	否	是
跨 Agent 时间线	否	否	是
Web 仪表板	否	否	是（实时、SSE）
HTML 报告	否	否	是

开发

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

许可证

ISC - Xiaolai Li