Agent Plugins · Community project

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.

4.1k StarsMITShellUpdated today
01

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.

Claude Octopus terminal demo running debate and research workflows
The repository demo shows /octo:* commands launching multi-model debate and research workflows in a terminal.View repository image
02

Core capabilities

01

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.

02

Four-phase engineering workflow

Discover, Define, Develop, and Deliver cover exploration, requirement convergence, implementation, and delivery review, while embrace chains the phases.

03

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.

04

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.

05

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.

03

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.

AI AGENT INSTALL

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.
01Before you start
  • 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
02Copy the install command or configuration
claude plugin marketplace add https://github.com/nyldn/plugins.git
claude plugin install octo@nyldn-plugins
# 重启 Claude Code 后运行:/octo:setup
03Complete the setup steps
  1. 1
    Pin 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.

  2. 2
    Install into one test host

    Use the README Marketplace command for Claude Code or Codex, restart the host, and avoid configuring multiple paths at once.

  3. 3
    Run read-only health checks

    Use Doctor, capabilities, and cache-check to distinguish discovery, installation, authentication, entitlement, and quota.

  4. 4
    Verify one read-only workflow

    Configure one provider, run research or review on public text, and inspect activation, contributions, cost prompts, and local results.

  5. 5
    Set 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.

How to verify the setup

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.

Before using it
  • 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.
04

Use cases

SCENARIO 01

Architecture debate

Ask separate providers to analyze choices such as monolith versus microservices and use council output to expose disagreement and risk.

SCENARIO 02

Cross-model code review

Assign a seat outside the implementation model to look for edge cases, security concerns, and missing tests.

SCENARIO 03

Attributed technical research

Parallelize research seats and preserve sources, contribution status, and uncertainty in synthesis.

SCENARIO 04

Phased complex delivery

Use Discover, Define, Develop, and Deliver to segment a long task and place human or consensus gates between phases.

05

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
06

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:setup
Read the complete README on GitHub →