Claude Octopus
A local plugin for Claude Code or Codex that assigns optional model providers to research, design, implementation, and review roles, then surfaces disagreement and consensus without dispatching external providers by default.
Project overview
Claude Octopus is a multi-model orchestration plugin for local coding agents. It turns research, definition, implementation, review, and delivery into explicit workflows, can assign configured providers such as Codex, Copilot, Qwen, Ollama, Perplexity, and OpenRouter to distinct seats, and lets the host model synthesize the result. Personas, skills, and single-host methods still work without external providers, and plain prompts do not dispatch paid providers by default. Independent opinions and visible failure states can be valuable, but they also expand the data boundary, tool authority, latency, and cost. First adoption should therefore pin a release in a test repository, inspect hooks, and restrict the provider roster.

Core capabilities
Multi-provider research and consensus
Research, debate, and council workflows can assign independent seats, report contributions and failures, and apply a 75% consensus gate where documented.
Four-phase engineering workflow
Discover, Define, Develop, and Deliver cover exploration, requirement convergence, implementation, and delivery review, while embrace chains the phases.
Role-based engineering methods
Thirty-one personas and 63 skills cover architecture, TDD, debugging, security, documentation, design, research, and delivery, with sensitive roles kept explicit.
Provider and cost controls
Health checks, model routing, context budgets, circuit breakers, session disables, projections, and usage reports constrain seats without proving entitlement or final billing.
Installation diagnostics and offline audit
Doctor, capabilities, cache-check, repair dry-run, and security-audit inspect installation and static readiness; applying a repair remains a separate write action.
Installation and usage
Choose the native Claude Code or Codex plugin path in a test repository, pin v11.9.4, and inspect the manifest and hooks. Run the read-only Doctor first, configure only one provider, then validate routing, outbound context, and cost prompts with low-risk research or read-only review. Keep automatic invoke routing disabled until policy is settled.
Let an AI Agent install it
Send this prompt to Codex, Claude Code, or another AI agent that can work with your local environment.
Help me install and minimally verify Claude Octopus in an isolated test repository. Project: https://github.com/nyldn/claude-octopus. First read README.md, docs/PLUGIN-COMPATIBILITY.md, docs/INSTALLATION-HEALTH.md, docs/PRIVACY.md, SECURITY.md, and the v11.9.4 release. Show the version, commit, manifest, hooks, and intended user/project writes before installation. Use the official Marketplace command for my current Claude Code or Codex host, restart it, and run the read-only Doctor first. Configure only the single provider I name and verify one read-only research or review task on public text. Do not enable OCTOPUS_AUTO_ROUTER_MODE=invoke, change production code, create a PR, widen credentials, or auto-repair. Report providers, outbound context, cost prompts, generated files, uninstall and retained-data locations, and unverified capabilities.- Linux, macOS, or WSL
- Claude Code v2.1.14+ or a Codex CLI with Plugin Marketplace support
- Node.js 18+ and a stdio MCP client for the MCP path
- At least one provider CLI, login session, or API key for multi-model features
- Permission to write state, logs, and configuration in the user and test-project directories
claude plugin marketplace add https://github.com/nyldn/plugins.git
claude plugin install octo@nyldn-plugins
# 重启 Claude Code 后运行:/octo:setup- 1Pin the release and inspect authority
Confirm v11.9.4 at commit 9cc6bcc, then review the host manifest, hooks, privacy policy, security policy, and write locations.
- 2Install into one test host
Use the README Marketplace command for Claude Code or Codex, restart the host, and avoid configuring multiple paths at once.
- 3Run read-only health checks
Use Doctor, capabilities, and cache-check to distinguish discovery, installation, authentication, entitlement, and quota.
- 4Verify one read-only workflow
Configure one provider, run research or review on public text, and inspect activation, contributions, cost prompts, and local results.
- 5Set the automation boundary
Choose provider allowlists and cost ceilings from observed data and failure behavior; keep plain-prompt routing on suggest or off until then.
After restarting the host, run octopus doctor installation or explicitly invoke skill-doctor and confirm the plugin-root and cache checks. Then run read-only research or review on public text with one provider, inspecting activation markers, participants, cost prompts, result files, and agent-summary. Do not enable invoke routing, edit production code, create a PR, or use production credentials on the first run.
- Discovery proves installation, not provider login, model entitlement, quota, or billing mode.
- Codex careful mode denies matching commands instead of interactively asking as Claude Code does.
- Uninstall does not remove retained results and state under ~/.claude-octopus/ or project .octo/.
- Cursor uses MCP tools and does not receive /octo:* commands, Claude Code hooks, or HUD.
- Set provider allowlists and OCTOPUS_MAX_COST_USD before enabling invoke routing.
Use cases
Architecture debate
Ask separate providers to analyze choices such as monolith versus microservices and use council output to expose disagreement and risk.
Cross-model code review
Assign a seat outside the implementation model to look for edge cases, security concerns, and missing tests.
Attributed technical research
Parallelize research seats and preserve sources, contribution status, and uncertainty in synthesis.
Phased complex delivery
Use Discover, Define, Develop, and Deliver to segment a long task and place human or consensus gates between phases.
Assessment
Claude Octopus puts model disagreement, engineering phases, provider state, and cost controls into explicit workflows instead of adding another chat entry point. That can expose blind spots in valuable research, architecture decisions, and independent review. The tradeoff is a broad shell-and-hook code surface, more recipients for code and prompts, and more cost and failure combinations. It fits teams willing to govern versions, authority, providers, and evidence; it should not be treated as an unsupervised quality guarantee.
Why it may be useful
- Native manifests and clear installation paths for Claude Code and Codex
- Optional providers and no paid dispatch from ordinary prompts by default
- Broad research, debate, council, review, and four-phase delivery workflows
- Detailed public privacy, security, compatibility, diagnostics, and provider documentation
- Doctor, projections, contribution ledgers, and degradation status improve visibility
- v11.9.4 shipped on 2026-09-28 and the repository remains active
What to know first
- Consensus can still share training bias or converge on an incorrect result
- Different CLIs have distinct authentication, sandbox, model, and billing semantics
- Lifecycle hooks and shell orchestration enlarge the pre-install review surface
- External providers may receive code, prompts, and workflow context under separate retention policies
- MCP, Cursor, Codex, and Claude Code do not have feature parity
- Installation and live multi-model workflows were not tested in this review
README
Claude Octopus
Overview
A local plugin for Claude Code or Codex that assigns optional model providers to research, design, implementation, and review roles, then surfaces disagreement and consensus without dispatching external providers by default. Run multiple AI models against the same research, design, or coding task. Surface disagreements before you ship.
Getting started
- Choose the native Claude Code or Codex plugin path in a test repository, pin v11.9.4, and inspect the manifest and hooks. Run the read-only Doctor first, configure only one provider, then validate routing, outbound context, and cost prompts with low-risk research or read-only review. Keep automatic invoke routing disabled until policy is settled.
- Claude Octopus exposes explicit research, debate, council, review, security, TDD, debugging, and end-to-end build workflows.
- Its main engineering path follows Discover, Define, Develop, and Deliver, with embrace chaining all four phases.
- After restarting the host, run octopus doctor installation or explicitly invoke skill-doctor and confirm the plugin-root and cache checks. Then run read-only research or review on public text with one provider, inspecting activation markers, participants, cost prompts, result files, and agent-summary. Do not enable invoke routing, edit production code, create a PR, or use production credentials on the first run.
Configuration
claude plugin marketplace add https://github.com/nyldn/plugins.git
claude plugin install octo@nyldn-plugins
# 重启 Claude Code 后运行:/octo:setupRead the complete README on GitHub →