{"id":48009078,"url":"https://github.com/xiaolai/claude-octopus","last_synced_at":"2026-04-08T17:00:28.841Z","repository":{"id":348584949,"uuid":"1198817536","full_name":"xiaolai/claude-octopus","owner":"xiaolai","description":"One brain, many arms — spawn multiple specialized Claude Code agents as MCP servers","archived":false,"fork":false,"pushed_at":"2026-04-07T06:43:55.000Z","size":136,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T16:32:42.289Z","etag":null,"topics":["agent-sdk","claude-agent-sdk","claude-code","mcp","mcp-server","model-context-protocol"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xiaolai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T19:38:18.000Z","updated_at":"2026-04-07T06:44:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xiaolai/claude-octopus","commit_stats":null,"previous_names":["xiaolai/claude-octopus"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/xiaolai/claude-octopus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaolai%2Fclaude-octopus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaolai%2Fclaude-octopus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaolai%2Fclaude-octopus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaolai%2Fclaude-octopus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xiaolai","download_url":"https://codeload.github.com/xiaolai/claude-octopus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaolai%2Fclaude-octopus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31564915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-sdk","claude-agent-sdk","claude-code","mcp","mcp-server","model-context-protocol"],"created_at":"2026-04-04T13:27:52.750Z","updated_at":"2026-04-08T17:00:28.817Z","avatar_url":"https://github.com/xiaolai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/xiaolai/claude-octopus/main/assets/claude-octopus-icon.svg\" alt=\"Claude Octopus\" width=\"200\" /\u003e\n\u003c/p\u003e\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** \u003e= 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\n```bash\nnpm install claude-octopus\n```\n\nOr skip the install entirely — use `npx` directly in your `.mcp.json` (see Quick Start below).\n\n## Quick Start\n\nAdd to your `.mcp.json`:\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 two tools: `claude_code` and `claude_code_reply`. That's it — you have Claude Code as a tool.\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 three distinct tools — `code_reviewer`, `test_writer`, `quick_qa` — each purpose-built.\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## Tools\n\nEach non-factory instance exposes:\n\n| Tool           | Purpose                                                 |\n| -------------- | ------------------------------------------------------- |\n| `\u003cname\u003e`       | Send a task to the agent, get a response + `session_id` |\n| `\u003cname\u003e_reply` | Continue a previous conversation by `session_id`        |\n\nPer-invocation parameters (override server defaults):\n\n| Parameter         | Description                                     |\n| ----------------- | ----------------------------------------------- |\n| `prompt`          | The task or question (required)                 |\n| `cwd`             | Working directory override                      |\n| `model`           | Model override                                  |\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 conversation turns                          |\n| `maxBudgetUsd`    | Max spend in USD                                |\n| `systemPrompt`    | Additional prompt (appended to server default)  |\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 (`\u003cname\u003e` and `\u003cname\u003e_reply`) | `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 conversation turns                                | 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### 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`**** tool respects persistence** — not registered when `CLAUDE_PERSIST_SESSION=false`.\n\n## Architecture\n\n```\n┌─────────────────────────────────┐\n│  MCP Client                     │\n│  (Claude Desktop, Cursor, etc.) │\n│                                 │\n│  Sees: code_reviewer,           │\n│        test_writer, quick_qa    │\n└──────────┬──────────────────────┘\n           │ JSON-RPC / stdio\n┌──────────▼──────────────────────┐\n│  Claude Octopus (per instance)  │\n│                                 │\n│  Env: CLAUDE_MODEL=opus         │\n│       CLAUDE_ALLOWED_TOOLS=...  │\n│       CLAUDE_APPEND_PROMPT=...  │\n│                                 │\n│  Calls: Agent SDK query()       │\n└──────────┬──────────────────────┘\n           │ in-process\n┌──────────▼──────────────────────┐\n│  Claude Agent SDK               │\n│  Runs autonomously: reads files,│\n│  writes code, runs commands     │\n│  Returns result + session_id    │\n└─────────────────────────────────┘\n```\n\n## How It Compares\n\n| Feature             | ``         | [claude-code-mcp](https://github.com/steipete/claude-code-mcp) | **Claude Octopus** |\n| ------------------- | ------------ | -------------------------------------------------------------- | ------------------ |\n| Approach            | Built-in     | CLI wrapping                                                   | Agent SDK          |\n| Exposes             | 16 raw tools | 1 prompt tool                                                  | 1 prompt + reply   |\n| Multi-instance      | No           | No                                                             | Yes                |\n| Per-instance config | No           | No                                                             | Yes (18 env vars)  |\n| Factory wizard      | No           | No                                                             | Yes                |\n| Session continuity  | 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaolai%2Fclaude-octopus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxiaolai%2Fclaude-octopus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaolai%2Fclaude-octopus/lists"}