{ "markdown": "

\n \"Claude\n

\n\n# Claude Octopus\n\nOne brain, many arms.\n\nAn MCP server that wraps the [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/sdk), letting you run multiple specialized Claude Code agents — each with its own model, tools, system prompt, and personality — from any MCP client.\n\n## Why\n\nClaude Code is powerful. But one instance does everything the same way. Sometimes you want a **strict code reviewer** that only reads files. A **test writer** that defaults to TDD. A **cheap quick helper** on Haiku. A **deep thinker** on Opus.\n\nClaude Octopus lets you spin up as many of these as you need. Same binary, different configurations. Each one shows up as a separate tool in your MCP client.\n\n## Prerequisites\n\n- **Node.js** >= 18\n- **Claude Code** — the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) is bundled as a dependency, but it spawns Claude Code under the hood, so you need a working `claude` CLI installation\n- **Anthropic API key** (`ANTHROPIC_API_KEY` env var) or an active Claude Code OAuth session\n\n## Install\n\nThree paths, pick whichever matches your MCP client.\n\n### npm (most direct)\n\n```bash\nnpm install claude-octopus\n```\n\n### npx (no install needed)\n\nSkip the install entirely — reference `claude-octopus@latest` in your `.mcp.json` and the client will fetch on demand (see Quick Start below).\n\n### MCP Registry\n\nThe server is published to the [MCP Registry](https://registry.modelcontextprotocol.io) under the name **`io.github.xiaolai/claude-octopus`**. Registry-aware MCP clients can resolve and install it by that name without touching npm directly.\n\n## Quick Start\n\nThe fastest way to get started:\n\n```bash\nnpx claude-octopus init\n```\n\nThis interactive wizard lets you pick a template, detects your MCP client, and writes the config for you.\n\nOr add to your `.mcp.json` manually:\n\n```json\n{\n \"mcpServers\": {\n \"claude\": {\n \"command\": \"npx\",\n \"args\": [\"claude-octopus@latest\"],\n \"env\": {\n \"CLAUDE_PERMISSION_MODE\": \"bypassPermissions\"\n }\n }\n }\n}\n```\n\nThis gives you six tools:\n\n| Tool | Purpose |\n|------|---------|\n| `claude_code` | Send a task, get a result |\n| `claude_code_reply` | Continue a conversation |\n| `claude_code_timeline` | Query the workflow timeline |\n| `claude_code_transcript` | Read full session transcripts |\n| `claude_code_sessions` | List Claude Code session history (this project, or all) |\n| `claude_code_report` | Generate HTML reports |\n\nThat's it — you have Claude Code as a tool, with full workflow observability built in.\n\n## Multiple Agents\n\nThe real power is running several instances with different configurations:\n\n```json\n{\n \"mcpServers\": {\n \"code-reviewer\": {\n \"command\": \"npx\",\n \"args\": [\"claude-octopus@latest\"],\n \"env\": {\n \"CLAUDE_TOOL_NAME\": \"code_reviewer\",\n \"CLAUDE_SERVER_NAME\": \"code-reviewer\",\n \"CLAUDE_DESCRIPTION\": \"Strict code reviewer. Finds bugs and security issues. Read-only.\",\n \"CLAUDE_MODEL\": \"opus\",\n \"CLAUDE_ALLOWED_TOOLS\": \"Read,Grep,Glob\",\n \"CLAUDE_APPEND_PROMPT\": \"You are a strict code reviewer. Report real bugs, not style preferences.\",\n \"CLAUDE_EFFORT\": \"high\"\n }\n },\n \"test-writer\": {\n \"command\": \"npx\",\n \"args\": [\"claude-octopus@latest\"],\n \"env\": {\n \"CLAUDE_TOOL_NAME\": \"test_writer\",\n \"CLAUDE_SERVER_NAME\": \"test-writer\",\n \"CLAUDE_DESCRIPTION\": \"Writes thorough tests with edge case coverage.\",\n \"CLAUDE_MODEL\": \"sonnet\",\n \"CLAUDE_APPEND_PROMPT\": \"Write tests first. Cover edge cases. TDD.\"\n }\n },\n \"quick-qa\": {\n \"command\": \"npx\",\n \"args\": [\"claude-octopus@latest\"],\n \"env\": {\n \"CLAUDE_TOOL_NAME\": \"quick_qa\",\n \"CLAUDE_SERVER_NAME\": \"quick-qa\",\n \"CLAUDE_DESCRIPTION\": \"Fast answers to quick coding questions.\",\n \"CLAUDE_MODEL\": \"haiku\",\n \"CLAUDE_MAX_BUDGET_USD\": \"0.02\",\n \"CLAUDE_EFFORT\": \"low\"\n }\n }\n }\n}\n```\n\nYour MCP client now sees distinct tools for each agent — `code_reviewer`, `test_writer`, `quick_qa` — each purpose-built.\n\n## Multi-Agent Orchestration\n\nAgents can coordinate through a **coordinator pattern**: one agent has the others as inner MCP tools via `CLAUDE_MCP_SERVERS`, and its system prompt drives the pipeline.\n\n```json\n{\n \"mcpServers\": {\n \"publishing-house\": {\n \"command\": \"npx\",\n \"args\": [\"claude-octopus@latest\"],\n \"env\": {\n \"CLAUDE_TOOL_NAME\": \"publishing_house\",\n \"CLAUDE_SERVER_NAME\": \"publishing-house\",\n \"CLAUDE_MODEL\": \"opus\",\n \"CLAUDE_PERMISSION_MODE\": \"bypassPermissions\",\n \"CLAUDE_APPEND_PROMPT\": \"You are a publishing house coordinator. Dispatch tasks to your specialist agents and drive the pipeline to completion.\",\n \"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\\\"}}}\"\n }\n }\n }\n}\n```\n\nThe coordinator agent autonomously calls `researcher`, `architect`, etc. as MCP tools — fully autonomous, no human in the loop until it finishes. Every invocation is tracked in the shared timeline.\n\n## Agent Factory\n\nDon't want to write configs by hand? Add a factory instance:\n\n```json\n{\n \"mcpServers\": {\n \"agent-factory\": {\n \"command\": \"npx\",\n \"args\": [\"claude-octopus@latest\"],\n \"env\": {\n \"CLAUDE_FACTORY_ONLY\": \"true\",\n \"CLAUDE_SERVER_NAME\": \"agent-factory\"\n }\n }\n }\n}\n```\n\nThis exposes a single `create_claude_code_mcp` tool — an interactive wizard. Tell it what you want (\"a strict code reviewer that only reads files\") and it generates the `.mcp.json` entry for you, listing all available options you can customize.\n\nIn factory-only mode, no query tools are registered — just the wizard. This keeps routing clean: the factory creates agents, the agents do work.\n\n## Init Wizard\n\nDon't want to edit JSON by hand? The init wizard gets you from zero to working in 30 seconds:\n\n```bash\nnpx claude-octopus init\n```\n\n```\n Claude Octopus — init wizard\n\n One brain, many arms. Let's set up your agents.\n\nPick a template (or build your own):\n\n 1. Code Review Team — Reviewer + test writer + security auditor\n 2. Publishing House — Researcher + architect + editor + proofreader\n 3. Tiered Models — Haiku for quick Q&A, Sonnet for coding, Opus for hard problems\n 4. Solo Agent — Single Claude Code agent with sensible defaults\n 5. Agent Factory — Interactive wizard that generates agent configs on demand\n 6. Custom — describe your own agent(s)\n\nChoice [1-6]:\n```\n\nIt auto-detects installed MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf), merges with existing config, and warns before overwriting.\n\n### Skip the menu\n\n```bash\nnpx claude-octopus init --template code-review-team\nnpx claude-octopus init --template tiered-models\nnpx claude-octopus init --template publishing-house\n```\n\n## Templates\n\nFive built-in templates, battle-tested and ready to use:\n\n| Template | Agents | Purpose |\n|----------|--------|---------|\n| `code-review-team` | code-reviewer (opus), test-writer (sonnet), security-auditor (opus) | Thorough code review pipeline |\n| `publishing-house` | researcher (sonnet), architect (opus), editor (sonnet), proofreader (haiku) | Multi-stage content/code pipeline |\n| `tiered-models` | quick-qa (haiku), coder (sonnet), deep-thinker (opus) | Right model for the job |\n| `solo-agent` | claude (default) | Single agent, quick setup |\n| `factory` | agent-factory | Generates configs on demand |\n\nEach agent comes pre-tuned with appropriate model, tools, effort level, and system prompt.\n\n## Dashboard\n\nMonitor your agents in real time:\n\n```bash\nnpx claude-octopus dashboard\n```\n\nOpens a local web dashboard at `http://localhost:3456` with:\n\n- **Live stats** — total runs, invocations, cost, SDK turns, responses, errors\n- **Recent activity** — agent cards for the latest run\n- **Run table** — all runs with cost, duration, and status\n- **Auto-refresh** — SSE connection pushes updates as agents run\n\n```bash\n# Custom port\nnpx claude-octopus dashboard --port 8080\n```\n\nThe dashboard reads the same timeline index used by the `_timeline` and `_report` tools. No additional configuration needed.\n\n## Tools\n\nEach non-factory instance exposes:\n\n| Tool | Purpose |\n|------|---------|\n| `` | Send a task to the agent, get a response + `session_id` + `run_id` |\n| `_reply` | Continue a previous conversation by `session_id` |\n| `_timeline` | Query the cross-agent workflow timeline |\n| `_transcript` | Retrieve full session transcript from Claude Code's storage |\n| `_sessions` | List Claude Code session history — this project by default, or all projects with `all_projects: true` |\n| `_report` | Generate a self-contained HTML report for a run or all runs |\n\n### Query and reply parameters\n\n| Parameter | Description |\n|-----------|-------------|\n| `prompt` | The task or question (required) |\n| `run_id` | Workflow run ID — groups related agent calls into one timeline. Auto-generated if omitted; returned in every response for propagation. |\n| `cwd` | Working directory override |\n| `model` | Model override (`sonnet`, `opus`, `haiku`, or full ID) |\n| `tools` | Restrict available tools (intersects with server restriction) |\n| `disallowedTools` | Block additional tools (unions with server blacklist) |\n| `additionalDirs` | Extra directories the agent can access |\n| `plugins` | Additional plugin paths to load |\n| `effort` | Thinking effort (`low`, `medium`, `high`, `max`) |\n| `permissionMode` | Permission mode (can only tighten, never loosen) |\n| `maxTurns` | Max agent-loop round trips (see [effort counters](#reading-the-effort-counters)) |\n| `maxBudgetUsd` | Max spend in USD |\n| `systemPrompt` | Additional prompt (appended to server default) |\n\n## Timeline\n\nEvery agent invocation is recorded in a lightweight JSONL index at `~/.claude-octopus/timelines/timeline.jsonl`. This solves the multi-agent correlation problem: when several agents participate in a workflow, the timeline tracks which sessions belong to the same run, in what order they executed, and what role each played.\n\nFull session transcripts stay in Claude Code's own storage (`~/.claude/projects/`). The timeline is just the table of contents — ~200 bytes per entry — that cross-references via `session_id`.\n\n```mermaid\ngraph TB\n subgraph \"Timeline Index (~200 bytes/entry)\"\n TL[\"~/.claude-octopus/timelines/timeline.jsonl\"]\n end\n\n subgraph \"Claude Code Session Storage (full transcripts)\"\n S1[\"~/.claude/projects/.../ses-aaa.jsonl\"]\n S2[\"~/.claude/projects/.../ses-bbb.jsonl\"]\n S3[\"~/.claude/projects/.../ses-ccc.jsonl\"]\n end\n\n TL -->|\"session_id cross-ref\"| S1\n TL -->|\"session_id cross-ref\"| S2\n TL -->|\"session_id cross-ref\"| S3\n```\n\n### How it works\n\n1. Every `` and `_reply` call appends one line to the timeline\n2. If you pass `run_id`, all agents sharing the same `run_id` are grouped into one run\n3. If you omit `run_id`, one is auto-generated and returned in the response — pass it to subsequent agents to keep them grouped\n\n### Querying the timeline\n\n```\n# List all runs\n_timeline({})\n\n# Show one run's agent sequence\n_timeline({ run_id: \"abc-123\" })\n\n# Look up a specific session\n_timeline({ session_id: \"ses-xyz\" })\n\n# Retrieve full transcript (separate tool)\n_transcript({ session_id: \"ses-xyz\" })\n```\n\n### Multi-agent workflow example\n\n```\nHost: researcher({ prompt: \"Research X\", run_id: \"pub-001\" })\n → { run_id: \"pub-001\", session_id: \"ses-aaa\", result: \"...\" }\n\nHost: architect({ prompt: \"Structure based on...\", run_id: \"pub-001\" })\n → { run_id: \"pub-001\", session_id: \"ses-bbb\", result: \"...\" }\n\nHost: verifier({ prompt: \"Check this plan\", run_id: \"pub-001\" })\n → { run_id: \"pub-001\", session_id: \"ses-ccc\", result: \"...\" }\n\nLater: researcher_timeline({ run_id: \"pub-001\" })\n → [\n { agent: \"researcher\", session_id: \"ses-aaa\", cost: 0.05, turns: 4, tool_calls: 3, response_groups: 2 },\n { agent: \"architect\", session_id: \"ses-bbb\", cost: 0.08, turns: 6, tool_calls: 5, response_groups: 3 },\n { agent: \"verifier\", session_id: \"ses-ccc\", cost: 0.03, turns: 3, tool_calls: 2, response_groups: 2 },\n ]\n\nLater: researcher_transcript({ session_id: \"ses-aaa\" })\n → full conversation transcript from Claude Code's storage\n```\n\n## HTML Reports\n\nGenerate self-contained HTML reports with agent sequence visualization, cost breakdown, and collapsible transcripts. Dark theme, no external dependencies — one file, open in any browser.\n\n### Via MCP tool\n\n```\n_report({}) # index of all runs\n_report({ run_id: \"pub-001\" }) # detailed report for one run\n```\n\n### Via CLI\n\n```bash\n# Index of all runs\nnpx claude-octopus report --out index.html\n\n# Detailed report for one run\nnpx claude-octopus report pub-001 --out report.html\nopen report.html\n\n# Without transcripts (faster, smaller file)\nnpx claude-octopus report pub-001 --no-transcripts --out report.html\n\n# To stdout (pipe-friendly)\nnpx claude-octopus report pub-001 > report.html\n```\n\n### What's in the report\n\n- **Run summary** — agent count, total cost, duration, SDK turns, responses, tool calls\n- **Timeline bar** — numbered dots for each agent (green = success, red = error)\n- **Agent cards** — timing, cost, effort counters, session ID, prompt excerpt\n- **Collapsible transcripts** — full tool calls, reasoning, and results per agent\n\n### Reading the effort counters\n\nThree numbers describe how much work an invocation took. They are not\ninterchangeable, and the first one is the one that surprises people:\n\n| Metric | What it counts |\n|---|---|\n| `num_turns` (shown as **SDK turns**) | Raw value from the Agent SDK. Measured against the runtime it tracks `tool_use` blocks plus the final response — **not** API round trips. |\n| `response_groups` (**responses**) | Distinct assistant responses in the main agent loop — one per API round trip, no matter how many tools that response called in parallel. |\n| `tool_calls` (**tool calls**) | `tool_use` blocks issued across the main agent loop. |\n\nWhen an agent calls several tools in parallel, `num_turns` climbs faster than\nthe number of visible responses. A run with 3 assistant responses issuing 4\ntool calls reports `num_turns: 5`, `response_groups: 3`, `tool_calls: 4`.\n`maxTurns`, meanwhile, is enforced against round trips: that same run\ncompletes under `maxTurns: 3` and aborts under `maxTurns: 2`. So size\n`maxTurns` against **responses**, not against SDK turns.\n\nBoth new counters cover the main agent loop only — work inside a sub-agent\n(`Task`) belongs to its own loop and is excluded. Timeline entries written by\nolder versions have neither, and render as `—` rather than as a false zero.\n\n## Configuration\n\nAll configuration is via environment variables in `.mcp.json`. Every env var is optional.\n\n### Identity\n\n| Env Var | Description | Default |\n|---------|-------------|---------|\n| `CLAUDE_TOOL_NAME` | Tool name prefix (generates ``, `_reply`, `_timeline`, `_transcript`, `_report`) | `claude_code` |\n| `CLAUDE_DESCRIPTION` | Tool description shown to the host AI | generic |\n| `CLAUDE_SERVER_NAME` | MCP server name in protocol handshake | `claude-octopus` |\n| `CLAUDE_FACTORY_ONLY` | Only expose the factory wizard tool | `false` |\n\n### Agent\n\n| Env Var | Description | Default |\n|---------|-------------|---------|\n| `CLAUDE_MODEL` | Model (`sonnet`, `opus`, `haiku`, or full ID) | SDK default |\n| `CLAUDE_CWD` | Working directory | `process.cwd()` |\n| `CLAUDE_PERMISSION_MODE` | `default`, `acceptEdits`, `bypassPermissions`, `plan` | `default` |\n| `CLAUDE_ALLOWED_TOOLS` | Comma-separated tool restriction (available tools) | all |\n| `CLAUDE_DISALLOWED_TOOLS` | Comma-separated tool blacklist | none |\n| `CLAUDE_MAX_TURNS` | Max agent-loop round trips per invocation | unlimited |\n| `CLAUDE_MAX_BUDGET_USD` | Max spend per invocation | unlimited |\n| `CLAUDE_EFFORT` | `low`, `medium`, `high`, `max` | SDK default |\n\n### Prompts\n\n| Env Var | Description |\n|---------|-------------|\n| `CLAUDE_SYSTEM_PROMPT` | Replaces the default Claude Code system prompt |\n| `CLAUDE_APPEND_PROMPT` | Appended to the default prompt (usually what you want) |\n\n### Advanced\n\n| Env Var | Description |\n|---------|-------------|\n| `CLAUDE_ADDITIONAL_DIRS` | Extra directories to grant access (comma-separated) |\n| `CLAUDE_PLUGINS` | Local plugin paths (comma-separated) |\n| `CLAUDE_MCP_SERVERS` | MCP servers for the inner agent (JSON) |\n| `CLAUDE_PERSIST_SESSION` | `true`/`false` — enable session resume (default: `true`) |\n| `CLAUDE_SETTING_SOURCES` | Settings to load: `user`, `project`, `local` |\n| `CLAUDE_SETTINGS` | Path to settings JSON or inline JSON |\n| `CLAUDE_BETAS` | Beta features (comma-separated) |\n\n### Timeline\n\n| Env Var | Description | Default |\n|---------|-------------|---------|\n| `CLAUDE_TIMELINE_DIR` | Directory for the cross-agent timeline index | `~/.claude-octopus/timelines` |\n\n### Authentication\n\n| Env Var | Description | Default |\n|---------|-------------|---------|\n| `ANTHROPIC_API_KEY` | Anthropic API key for this agent | inherited from parent |\n| `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code OAuth token for this agent | inherited from parent |\n\nLeave both unset to inherit auth from the parent process. Set one per agent to use a different account or billing source.\n\nLists accept JSON arrays when values contain commas: `[\"path,with,comma\", \"/normal\"]`\n\n## Security\n\n- **Permission mode defaults to `default`** — tool executions prompt for approval unless you explicitly set `bypassPermissions`.\n- **`cwd` overrides preserve agent knowledge** — when the host overrides `cwd`, the agent's configured base directory is automatically added to `additionalDirectories` so it retains access to its own context.\n- **Tool restrictions narrow, never widen** — per-invocation `tools` intersects with the server restriction (can only remove tools, not add). `disallowedTools` unions (can only block more).\n- **`_reply` and `_transcript` tools respect persistence** — not registered when `CLAUDE_PERSIST_SESSION=false`.\n- **Timeline writes are best-effort** — a failed timeline append never blocks or fails the primary query.\n\n## Architecture\n\n```mermaid\ngraph TB\n subgraph \"MCP Client (Claude Desktop, Cursor, etc.)\"\n C[\"Sees: code_reviewer, test_writer, quick_qa\"]\n end\n\n C -->|\"JSON-RPC / stdio\"| O1\n C -->|\"JSON-RPC / stdio\"| O2\n C -->|\"JSON-RPC / stdio\"| O3\n\n subgraph \"Claude Octopus Instances\"\n O1[\"code-reviewer
model=opus, tools=Read,Grep,Glob\"]\n O2[\"test-writer
model=sonnet\"]\n O3[\"quick-qa
model=haiku, budget=$0.02\"]\n end\n\n O1 -->|\"Agent SDK query()\"| SDK[\"Claude Agent SDK\"]\n O2 -->|\"Agent SDK query()\"| SDK\n O3 -->|\"Agent SDK query()\"| SDK\n\n O1 -->|\"append\"| TL[\"Timeline Index
~/.claude-octopus/timelines/\"]\n O2 -->|\"append\"| TL\n O3 -->|\"append\"| TL\n\n SDK -->|\"persist\"| SS[\"Session Storage
~/.claude/projects/\"]\n TL -.->|\"cross-ref\"| SS\n```\n\n## How It Compares\n\n| Feature | Built-in `claude` | [claude-code-mcp](https://github.com/steipete/claude-code-mcp) | **Claude Octopus** |\n|---------|-------------------|----------------------------------------------------------------|--------------------|\n| Approach | Built-in | CLI wrapping | Agent SDK |\n| Tools per instance | 16 raw tools | 1 prompt tool | 5 (prompt, reply, timeline, transcript, report) |\n| Multi-instance | No | No | Yes |\n| Per-instance config | No | No | Yes (20 env vars) |\n| Init wizard | No | No | Yes (`init` + 5 templates) |\n| Factory wizard | No | No | Yes |\n| Session continuity | No | No | Yes |\n| Cross-agent timeline | No | No | Yes |\n| Web dashboard | No | No | Yes (live, SSE) |\n| HTML reports | No | No | Yes |\n\n## Development\n\n```bash\npnpm install\npnpm build # compile TypeScript\npnpm test # run tests (vitest)\npnpm test:coverage # coverage report\n```\n\n## License\n\n[ISC](https://github.com/xiaolai/claude-octopus/blob/main/LICENSE) - Xiaolai Li\n", "bytes": 20670, "sha": "9faf4bceba74568e7ef42f04161d456a0fe791582b95014b7d966b1f3e321a66", "repo_slug": "xiaolai/claude-octopus", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_xiaolai_claude_octopus_ba5efe88/readme" }