Claude Octopus

Claude Octopus

One brain, many arms.

An MCP server that wraps the Claude Agent SDK, letting you run multiple specialized Claude Code agents — each with its own model, tools, system prompt, and personality — from any MCP client.

Why

Claude 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.

Claude 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.

Prerequisites

• Node.js >= 18
• Claude Code — the Claude Agent SDK is bundled as a dependency, but it spawns Claude Code under the hood, so you need a working claude CLI installation
• Anthropic API key (ANTHROPIC_API_KEY env var) or an active Claude Code OAuth session

Install

Three paths, pick whichever matches your MCP client.

npm (most direct)

npm install claude-octopus

npx (no install needed)

Skip the install entirely — reference claude-octopus@latest in your .mcp.json and the client will fetch on demand (see Quick Start below).

MCP Registry

The server is published to the MCP Registry under the name `io.github.xiaolai/claude-octopus`. Registry-aware MCP clients can resolve and install it by that name without touching npm directly.

Quick Start

The fastest way to get started:

npx claude-octopus init

This interactive wizard lets you pick a template, detects your MCP client, and writes the config for you.

Or add to your .mcp.json manually:

{

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

This gives you six tools:

That's it — you have Claude Code as a tool, with full workflow observability built in.

Multiple Agents

The real power is running several instances with different configurations:

{

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

Your MCP client now sees distinct tools for each agent — code_reviewer, test_writer, quick_qa — each purpose-built.

Multi-Agent Orchestration

Agents 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.

{

"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\"}}}" } } } }

The 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.

Agent Factory

Don't want to write configs by hand? Add a factory instance:

{

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

This 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.

In factory-only mode, no query tools are registered — just the wizard. This keeps routing clean: the factory creates agents, the agents do work.

Init Wizard

Don't want to edit JSON by hand? The init wizard gets you from zero to working in 30 seconds:

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]:

It auto-detects installed MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf), merges with existing config, and warns before overwriting.

Skip the menu

npx claude-octopus init --template code-review-team

npx claude-octopus init --template tiered-models npx claude-octopus init --template publishing-house

Templates

Five built-in templates, battle-tested and ready to use:

Each agent comes pre-tuned with appropriate model, tools, effort level, and system prompt.

Dashboard

Monitor your agents in real time:

npx claude-octopus dashboard

Opens a local web dashboard at http://localhost:3456 with:

• Live stats — total runs, invocations, cost, SDK turns, responses, errors
• Recent activity — agent cards for the latest run
• Run table — all runs with cost, duration, and status
• Auto-refresh — SSE connection pushes updates as agents run

# Custom port

npx claude-octopus dashboard --port 8080

The dashboard reads the same timeline index used by the _timeline and _report tools. No additional configuration needed.

Tools

Each non-factory instance exposes:

Query and reply parameters

Timeline

Every 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.

Full 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.

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

How it works

1. Every and _reply call appends one line to the timeline
2. If you pass run_id, all agents sharing the same run_id are grouped into one run
3. If you omit run_id, one is auto-generated and returned in the response — pass it to subsequent agents to keep them grouped

Querying the timeline

# List all runs

_timeline({})

Show one run's agent sequence

_timeline({ run_id: "abc-123" })

Look up a specific session

_timeline({ session_id: "ses-xyz" })

Retrieve full transcript (separate tool)

_transcript({ session_id: "ses-xyz" })

Multi-agent workflow example

Host:  r