claude-octopus

Multi-LLM orchestration plugin for Claude Code — coordinates Codex, Gemini, Perplexity, OpenRouter, Copilot, Qwen, and Ollama with consensus gates. Eight tentacles, zero blind spots.

🐙 Research, build, review, and ship — with eight AI providers checking each other's work. Say what you need, and the right workflow runs. A 75% consensus gate catches disagreements before they reach production. No single model's blind spots slip through.

🧠 Remembers across sessions. Integrates with claude-mem for persistent memory — past decisions, research, and context survive session boundaries.

⚡ Spec in, software out. Dark Factory mode takes a spec and autonomously runs the full pipeline — research, define, develop, deliver. You review the output, not every step.

🔄 Four-phase methodology, not just tools. Every task moves through Discover → Define → Develop → Deliver, with quality gates between phases. Other orchestrators give you infrastructure. Octopus gives you the workflows.

🐙 32 specialized personas (role-specific AI agents like security-auditor, backend-architect), 47 commands (slash commands you type), 50 skills (reusable workflow modules). Say "audit my API" and the right expert activates. Don't know the command? The smart router figures it out.

🐙 Works with just Claude. Scales to eight. Zero providers needed to start. Add them one at a time — each activates automatically when detected.

💰 Five providers cost nothing extra. Codex and Gemini use OAuth (included with subscriptions). Qwen has 1,000-2,000 free requests/day. Copilot uses your GitHub subscription. Ollama runs locally for free.

---

What's New

Full changelog →

Star History

---

Quickstart

# Terminal (not inside a Claude Code session):
claude plugin marketplace add https://github.com/nyldn/claude-octopus.git
claude plugin install octo@nyldn-plugins

# Then inside Claude Code:
/octo:setup

That's it. Setup detects installed providers, shows what's missing, and walks you through configuration. You need zero external providers to start — Claude is built in.

From the Claude Code UI: Type /plugin in a session → Marketplace tab → install octo.

Factory AI (Droid):

droid plugin marketplace add https://github.com/nyldn/claude-octopus
droid plugin install octo@claude-octopus

# Update
claude plugin update octo

# Clean reinstall (if update fails)
claude plugin uninstall claude-octopus 2>/dev/null
claude plugin uninstall octo 2>/dev/null
rm -rf ~/.claude/plugins/cache/nyldn-plugins/claude-octopus
claude plugin marketplace add https://github.com/nyldn/claude-octopus.git
claude plugin install octo@nyldn-plugins

---

Top 8 Tentacles

🐙 Eight commands — one per arm. A real octopus has eight arms, each with its own neurons that can act independently. These eight tentacles work the same way: each orchestrates up to three AI providers, applies quality gates, and produces a deliverable.

/octo:embrace build stripe integration     # Full lifecycle: research → define → develop → deliver
/octo:factory "build a CLI that converts CSV to JSON"  # Autonomous pipeline — spec in, software out
/octo:debate monorepo vs microservices     # Structured four-way AI debate with consensus
/octo:research htmx vs react in 2026       # Multi-source synthesis from three AI providers
/octo:design mobile checkout redesign       # UI/UX design with BM25 style intelligence
/octo:tdd create user auth                 # Red-green-refactor with test discipline
/octo:security                              # OWASP vulnerability scan + remediation
/octo:prd mobile checkout redesign          # AI-optimized PRD with 100-point scoring

Plus 30 more: review, debug, extract, deck, docs, schedule, parallel, sentinel, brainstorm, claw, doctor, and the full set.

Don't remember the command name? Just describe what you need:

/octo:auto research microservices patterns    -> routes to discover phase
/octo:auto build user authentication          -> routes to develop phase
/octo:auto compare Redis vs DynamoDB          -> routes to debate

The smart router parses your intent and selects the right workflow.

---

Which Tentacle?

Not sure which command to use? Pick by goal:

Or skip the table — type /octo:auto <what you want> or just say octo <what you want>, and the smart router picks for you. 🔍

---

How It Works

Eight Tentacles, One Workflow

Claude Octopus coordinates up to eight AI providers — one per tentacle:

Providers run in parallel for research, sequentially for problem scoping, and adversarially for review. A 75% consensus quality gate prevents questionable work from shipping. Only Claude is required — all others are optional and auto-detected.

Double Diamond Phases

Four structured phases adapted from the UK Design Council's methodology:

Run phases individually or all four with /octo:embrace. Configure autonomy: supervised (approve each phase), semi-autonomous (intervene on failures), or autonomous (run all four).

32 Personas

Specialized agents that activate automatically based on your request. When you say "audit my API for vulnerabilities," security-auditor activates. When you say "design a dashboard," ui-ux-designer takes over.

Categories: Software Engineering (11), Specialized Development (6), Documentation & Communication (5), Research & Strategy (3), Business & Compliance (3), Creative & Design (4).

Full persona reference | All 50 skills

Reaction Engine

When agents create PRs, the reaction engine monitors what happens next — CI failures, review comments, stale agents — and responds automatically. No new commands to learn. It fires transparently inside workflows you already use:

What it auto-handles:

Override defaults per project by creating .octo/reactions.conf:

# EVENT|ACTION|MAX_RETRIES|ESCALATE_AFTER_MIN|ENABLED
ci_failed|forward_logs|5|45|true
changes_requested|forward_comments|3|90|true
stuck|escalate|0|10|true

Reactions track 13 agent lifecycle states: running → pr_open → ci_pending → ci_failed / review_pending → changes_requested / approved → mergeable → merged → done.

---

Providers and Cost

Authentication

OAuth users pay nothing beyond their existing subscriptions.

What Works Without External Providers

Everything except multi-AI features. You get all 32 personas, structured workflows, smart routing, context detection, and every skill. Multi-AI orchestration (parallel analysis, debate, consensus) activates when external providers are configured.

---

Trust and Safety

Namespace isolation — Only /octo:* commands and octo natural language prefix activate the plugin. Your existing Claude Code setup is untouched.

Data locations — Results in ~/.claude-octopus/results/, logs in ~/.claude-octopus/logs/, project state in .octo/. Nothing hidden.

No telemetry — No usage data collected. No phone-home. Fully open source.

Provider transparency — Every command shows a 🐙 activation indicator on launch. Colored dots (🔴 🟡 🟣 🔵) show exactly which providers are running and when external APIs are called. You always know what's happening.

Clean uninstall — Run claude plugin uninstall octo from your terminal. If you see a scope error, add --scope project. No residual config changes.

---

OpenClaw Compatibility

Claude Octopus ships with a compatibility layer for OpenClaw, the open-source AI assistant framework. This lets you expose Octopus workflows to messaging platforms (Telegram, Discord, Signal, WhatsApp) without modifying the Claude Code plugin.

Architecture

Claude Code Plugin (unchanged)
  └── .mcp.json ─── MCP Server ─── orchestrate.sh
                                        ↑
OpenClaw Extension ─────────────────────┘

Three components, zero changes to the core plugin:

MCP Server

The MCP server auto-starts when the plugin is enabled (via .mcp.json). It exposes:

• octopus_discover, octopus_define, octopus_develop, octopus_deliver — Individual phases
• octopus_embrace — Full Double Diamond workflow
• octopus_debate, octopus_review, octopus_security — Specialized workflows
• octopus_list_skills, octopus_status — Introspection

Any MCP-compatible client can connect to the server.

OpenClaw Extension

Install in an OpenClaw instance from git:

npm install github:nyldn/claude-octopus#main --prefix openclaw

Or clone and link locally:

cd openclaw && npm install && npm run build

The extension registers as an OpenClaw plugin with configurable workflows, autonomy modes, and Claude Code path resolution.

Build & Validate

./scripts/build-openclaw.sh          # Regenerate skill registry from frontmatter
./scripts/build-openclaw.sh --check  # CI mode — exits non-zero if out of sync
./tests/validate-openclaw.sh         # 13-check validation suite

---

FAQ

Do I need all three AI providers? No. One external provider plus Claude gives you multi-AI features. No external providers still gives you personas, workflows, and skills.

Will this break my existing Claude Code setup? No. Activates only with the octo prefix. Results stored separately. Uninstalls cleanly.

What happens if a provider times out? The workflow continues with available providers. You'll see the status in the visual indicators.

Why "octopus"? 🐙 Fun fact: a real octopus has three hearts, blue blood, and 500 million neurons — two-thirds of which live in its eight arms. Each arm can taste, touch, and act independently. Claude Octopus works the same way: each tentacle (command) operates autonomously with its own squeeze of logic, then ink flows back as the final deliverable. The crossfire review? That's the squeeze — adversarial pressure that untangles everything before it ships.

---

Documentation

• Documentation Guide — Start here
• Command Reference — Commands, triggers, and provider indicators
• Feature Gap Analysis — CC feature adoption tracker
• Architecture — Provider flow and execution model
• Plugin Architecture — Internal plugin structure
• Agents & Personas — All 32 personas
• CLI Reference — Direct CLI usage, debug mode, async, and tmux
• Changelog

---

Attribution

• wolverin0/claude-skills — AI Debate Hub. MIT License.
• obra/superpowers — Discipline skills patterns. MIT License.
• nextlevelbuilder/ui-ux-pro-max-skill — BM25 design intelligence databases. MIT License.
• UK Design Council — Double Diamond methodology.

---

Community

Join r/ClaudeOctopus for help, workflow tips, showcases, and updates.

Contributing

1. Report issues
2. Submit PRs following existing code style
3. git clone https://github.com/nyldn/claude-octopus.git && make test

See CONTRIBUTING.md for details.

---

License

MIT — see LICENSE