{"id":39565145,"url":"https://github.com/nyldn/claude-octopus","last_synced_at":"2026-06-03T02:01:36.885Z","repository":{"id":332829876,"uuid":"1134819911","full_name":"nyldn/claude-octopus","owner":"nyldn","description":"Surface AI blindspots before you ship. Put up to 8 AI models on every research, design or coding task.","archived":false,"fork":false,"pushed_at":"2026-06-01T19:02:04.000Z","size":12079,"stargazers_count":3449,"open_issues_count":2,"forks_count":310,"subscribers_count":28,"default_branch":"main","last_synced_at":"2026-06-01T20:27:49.665Z","etag":null,"topics":["ai-agents","ai-orchestration","claude-code","claude-code-plugin","codex","copilot","developer-tools","double-diamond","gemini","multi-ai","multi-llm","ollama"],"latest_commit_sha":null,"homepage":"https://reddit.com/r/ClaudeOctopus/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nyldn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["nyldn"]}},"created_at":"2026-01-15T08:49:38.000Z","updated_at":"2026-06-01T19:31:05.000Z","dependencies_parsed_at":"2026-04-02T03:03:01.609Z","dependency_job_id":"a890e858-7b13-4ffe-871d-19a45aec3fbe","html_url":"https://github.com/nyldn/claude-octopus","commit_stats":null,"previous_names":["nyldn/claude-octopus"],"tags_count":258,"template":false,"template_full_name":null,"purl":"pkg:github/nyldn/claude-octopus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyldn%2Fclaude-octopus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyldn%2Fclaude-octopus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyldn%2Fclaude-octopus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyldn%2Fclaude-octopus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nyldn","download_url":"https://codeload.github.com/nyldn/claude-octopus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyldn%2Fclaude-octopus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33844687,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agents","ai-orchestration","claude-code","claude-code-plugin","codex","copilot","developer-tools","double-diamond","gemini","multi-ai","multi-llm","ollama"],"created_at":"2026-01-18T07:13:02.335Z","updated_at":"2026-06-03T02:01:36.873Z","avatar_url":"https://github.com/nyldn.png","language":"Shell","funding_links":["https://github.com/sponsors/nyldn"],"categories":["Multi-Agent Systems","Shell","Code \u0026 Developer Tools","🚀 AI Tools for Vim, Neovim, and Terminal"],"sub_categories":["Orchestration Platforms"],"readme":"# 🐙 Claude Octopus\n\nEvery AI model has blind spots. Claude Octopus puts up to eight of them on every task, so blind spots surface before you ship — not after. It orchestrates Codex, Gemini, Copilot, Qwen, Ollama, Perplexity, and OpenRouter alongside Claude Code, with consensus gates that flag any disagreements.\n\n**Claude-native first, Octopus for escalation.** Use Claude-native `/init`, `/review`, and `/security-review` when Claude is enough. Use Octopus when you want multiple model opinions, adversarial review, or stricter multi-LLM workflows.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/demo.gif\" alt=\"Claude Octopus Demo — debate and research with multiple AI providers\" width=\"720\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://claude.ai\"\u003e\u003cimg src=\"https://img.shields.io/badge/Claude-Built_with_AI-c96442?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTEyIDJhMTAgMTAgMCAxIDAgMCAyMCAxMCAxMCAwIDAgMCAwLTIwbTAgMS44YTEuMiAxLjIgMCAwIDEgLjg1LjM1bDEuNSA0LjVhLjYuNiAwIDAgMCAuMzUuMzVsNC41IDEuNWExLjIgMS4yIDAgMCAxIDAgMi4yN2wtNC41IDEuNWEuNi42IDAgMCAwLS4zNS4zNWwtMS41IDQuNWExLjIgMS4yIDAgMCAxLTIuMjcgMGwtMS41LTQuNWEuNi42IDAgMCAwLS4zNS0uMzVsLTQuNS0xLjVhMS4yIDEuMiAwIDAgMSAwLTIuMjdsNC41LTEuNWEuNi42IDAgMCAwIC4zNS0uMzVsMS41LTQuNUExLjIgMS4yIDAgMCAxIDEyIDMuOCIvPjwvc3ZnPg==\u0026labelColor=333\" alt=\"Built with Claude\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/nyldn/claude-octopus/actions/workflows/test.yml\"\u003e\u003cimg src=\"https://github.com/nyldn/claude-octopus/actions/workflows/test.yml/badge.svg\" alt=\"Tests\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tests-117_suites_passing-brightgreen\" alt=\"117 suites passing\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Version-9.42.3-blue\" alt=\"Version 9.42.3\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Claude_Code-v2.1.14+_required-blueviolet\" alt=\"Requires Claude Code v2.1.14+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green\" alt=\"MIT License\"\u003e\n\u003c/p\u003e\n\n🐙 **Research, build, review, and ship — with eight AI providers checking each other's work.** Say what you need, and the right workflow runs. Claude-native handles the ordinary path; Octopus handles the escalated path. A 75% consensus gate catches disagreements before they reach production. No single model's blind spots slip through.\n\n🧠 **Remembers across sessions.** Integrates with [claude-mem](https://github.com/thedotmack/claude-mem) for persistent memory — past decisions, research, and context survive session boundaries.\n\n⚡ **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.\n\n🔄 **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.\n\n🐙 **32 specialized personas** (role-specific AI agents like security-auditor, backend-architect), **50 commands** (slash commands you type), **54 skills** (reusable workflow modules). Say \"audit my API\" and the right expert activates. Don't know the command? The smart router figures it out.\n\n🐙 **Works with just Claude. Scales to eight.** Zero providers needed to start. Add them one at a time — each activates automatically when detected.\n\n💰 **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.\n\n---\n\n## What's New\n\n\u003e 🆕 **v9.41 — Multi-LLM Council.** `/octo:council` runs a structured 3/5/7-persona deliberation across Claude, Codex, Gemini, and OpenCode with goal modes (`advice`, `decision`, `plan`, `implement`, `review`), styles (`balanced`, `adversarial`, `red-team`, `executive`, `implementation`), benchmark-aware role routing, quorum + critical-veto gates, budget caps, and gated worktree handoff for approved plans. Use it when one model's opinion isn't enough.\n\u003e\n\u003e ```bash\n\u003e /octo:council --goal decision --style adversarial \"Should this service stay monolithic?\"\n\u003e /octo:council --goal implement --implement plan-only \"Refactor the auth flow\"\n\u003e ```\n\n| Version | Best Features |\n|---------|--------------|\n| **v9.41** (new) | **`/octo:council`** promoted to first-class workflow — structured multi-LLM deliberation with goal modes, adversarial/red-team styles, benchmark-aware persona routing, quorum and critical-veto gates, budget preflight, and gated worktree handoff for approved implementation plans. |\n| **v9** (current) | Up to 8 providers (Codex, Gemini, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OpenCode). Four-way AI debates and configurable multi-LLM councils. Smart router — just say what you need. Agent summary tables show which providers actually contributed. Provider-aware prompt preflight prevents silent oversize failures. Research breadth modes fan out light, standard, or exhaustive investigations. Setup aliases and fuzzy `/octo:*` corrections reduce command friction. Discipline mode with 8 auto-invoke gates. Two-stage review. Circuit breakers with automatic provider recovery. Cursor + OpenCode + Codex cross-compatibility. Token compression: `bin/octo-compress` pipe + auto PostToolUse hook save ~7,300 tokens/session. PostCompact context recovery. `bin/octopus` CLI. 175+ CC feature flags through v2.1.157, including Opus 4.8 and dynamic workflow awareness. |\n| **v8** | Multi-LLM code review with inline PR comments. Parallel workstreams in isolated git worktrees. Reaction engine — auto-responds to CI failures. 32 specialized personas. Dark Factory autonomous pipeline. |\n| **v7** | Double Diamond workflow. Multi-provider dispatch. Quality gates and consensus scoring. Configurable sandbox modes. |\n\n[Full changelog →](CHANGELOG.md)\n\n## Quickstart\n\n```bash\n# Terminal (not inside a Claude Code session):\nclaude plugin marketplace add https://github.com/nyldn/plugins.git\nclaude plugin install octo@nyldn-plugins\n\n# Then inside Claude Code:\n/octo:setup\n```\n\nThat'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.\n\nClaude Code **v2.1.14+** is the minimum supported runtime. Newer Claude Code releases unlock additional Octopus diagnostics and release checks automatically; the current plugin tracks feature flags through **Claude Code v2.1.157**.\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall for Codex CLI\u003c/summary\u003e\n\n```bash\ngit clone --depth 1 https://github.com/nyldn/claude-octopus.git ~/.codex/claude-octopus \u0026\u0026 mkdir -p ~/.agents/skills \u0026\u0026 ln -sf ~/.codex/claude-octopus/skills ~/.agents/skills/claude-octopus\n```\n\nRestart Codex. Skills appear automatically — invoke with `$skill-doctor`, `$skill-debug`, etc.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall for Cursor IDE\u003c/summary\u003e\n\nCursor uses Octopus as an **MCP server** (not a plugin — Cursor doesn't have Claude Code's plugin system). You get MCP tools like `octopus_discover`, `octopus_review`, etc. instead of `/octo:*` slash commands.\n\n\u003e **Important:** Just cloning the repo is not enough. You must complete all three steps below — install dependencies and configure the MCP server — for Cursor to pick up Octopus tools.\n\n```bash\n# 1. Clone the repo\ngit clone --depth 1 https://github.com/nyldn/claude-octopus.git ~/.cursor/claude-octopus\n\n# 2. Install MCP server dependencies\ncd ~/.cursor/claude-octopus/mcp-server \u0026\u0026 npm install\n\n# 3. Configure Cursor — add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-octopus\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"${userHome}/.cursor/claude-octopus/mcp-server/src/index.ts\"],\n      \"env\": {\n        \"OCTO_CLAW_ENABLED\": \"true\",\n        \"OPENAI_API_KEY\": \"${env:OPENAI_API_KEY}\",\n        \"GEMINI_API_KEY\": \"${env:GEMINI_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor. Tools appear in Cursor's AI chat — invoke by asking e.g. \"use octopus_discover to research X\".\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing Cursor on WSL?\u003c/summary\u003e\n\nIf you're running Cursor on Windows with WSL, clone the repo inside WSL and point the MCP config through `wsl.exe`:\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-octopus\": {\n      \"command\": \"wsl\",\n      \"args\": [\"npx\", \"tsx\", \"/home/\u003cuser\u003e/.cursor/claude-octopus/mcp-server/src/index.ts\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"${env:OPENAI_API_KEY}\",\n        \"GEMINI_API_KEY\": \"${env:GEMINI_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\nReplace `\u003cuser\u003e` with your WSL username. Make sure `node` and `npm` are installed inside WSL.\n\u003c/details\u003e\n\nSee [docs/IDE-INTEGRATION.md](docs/IDE-INTEGRATION.md) for the full guide including `ide-attach.sh` auto-setup.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall for OpenCode\u003c/summary\u003e\n\n```bash\ngit clone --depth 1 https://github.com/nyldn/claude-octopus.git ~/.opencode/claude-octopus\nmkdir -p ~/.agents/skills\nln -s ~/.opencode/claude-octopus/skills ~/.agents/skills/claude-octopus\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eOther install methods (Claude Code)\u003c/summary\u003e\n\n**From the Claude Code UI:** Type `/plugin` in a session → **Marketplace** tab → install **octo**.\n\n**Factory AI (Droid):**\n```bash\ndroid plugin marketplace add https://github.com/nyldn/claude-octopus.git\ndroid plugin install octo@nyldn-plugins\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eUpdate / Troubleshooting\u003c/summary\u003e\n\n```bash\n# Update\nclaude plugin marketplace update nyldn-plugins\nclaude plugin update octo@nyldn-plugins\n\n# Clean reinstall (if update fails)\nclaude plugin uninstall claude-octopus 2\u003e/dev/null\nclaude plugin uninstall octo 2\u003e/dev/null\nrm -rf ~/.claude/plugins/cache/nyldn-plugins/octo\nclaude plugin marketplace remove nyldn-plugins\nclaude plugin marketplace add https://github.com/nyldn/plugins.git\nclaude plugin install octo@nyldn-plugins\n```\n\nRun focused diagnostics after updating:\n\n```bash\n/octo:doctor config   # install path, version, manifest, Claude Code feature flags\n/octo:doctor skills   # skill loading, skillOverrides, plugin zip/URL capability notes\n```\n\nFor Anthropic-compatible gateways, Claude Code v2.1.129+ requires an explicit opt-in before `/model` discovers models from `/v1/models`:\n\n```bash\nexport ANTHROPIC_BASE_URL=https://your-gateway.example/v1\nexport CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1\n```\n\nClaude Code v2.1.129+ also supports `skillOverrides` in Claude settings. Use it to keep rarely used Octopus skills installable while reducing context load, for example by setting niche skills to `name-only` or `user-invocable-only`.\n\u003c/details\u003e\n\n---\n\n## Claude Code Web and Remote Sessions\n\nWhen Claude Code is running in a hosted, web, or remote-control environment, set `OCTOPUS_REMOTE_SESSION=true` in that environment. If Claude Code itself exports `CLAUDE_CODE_REMOTE=true` or `CLAUDE_CODE_WEB=true`, Octopus detects that automatically. Remote sessions are treated as unattended by default:\n\n- `CLAUDE_OCTOPUS_AUTONOMY=autonomous` / `OCTOPUS_AUTONOMY=autonomous` unless already set\n- provider smoke tests and Codex tier probes are skipped\n- the statusline uses a lightweight remote-safe display\n\nSet `OCTOPUS_REMOTE_STATUSLINE=full` to opt back into the full local HUD, or `OCTOPUS_REMOTE_STATUSLINE=off` to suppress statusline output entirely.\n\nCloud environment setup should install provider CLIs and expose only the credentials required for the workflow. Paste this into the cloud environment setup script:\n\n```bash\n#!/usr/bin/env bash\nset -e\n\nnpm install -g @openai/codex @google/gemini-cli @qwen-code/qwen-code 2\u003e/dev/null || true\n\necho \"Octopus cloud setup:\"\ncommand -v codex \u003e/dev/null 2\u003e\u00261 \u0026\u0026 echo \"  Codex CLI: installed\" || echo \"  Codex CLI: missing\"\ncommand -v gemini \u003e/dev/null 2\u003e\u00261 \u0026\u0026 echo \"  Gemini CLI: installed\" || echo \"  Gemini CLI: missing\"\ncommand -v qwen \u003e/dev/null 2\u003e\u00261 \u0026\u0026 echo \"  Qwen CLI: installed\" || echo \"  Qwen CLI: missing\"\ncommand -v gh \u003e/dev/null 2\u003e\u00261 \u0026\u0026 echo \"  GitHub CLI: installed\" || echo \"  GitHub CLI: optional, install if Sentinel needs GitHub\"\n```\n\nSet environment variables in the cloud environment, not in the script:\n\n```bash\nOPENAI_API_KEY=...\nGEMINI_API_KEY=...\nPERPLEXITY_API_KEY=...   # optional\nOPENROUTER_API_KEY=...   # optional\n```\n\nProvider API calls require internet access from the hosted environment.\n\nFor scheduled Claude Code tasks, run `/octo:sentinel` for triage and `/octo:security` for recurring audits. Keep jobs read-only by default and route fixes through `/octo:debug`, `/octo:review`, or `/octo:embrace` after triage.\n\nSet `OCTO_TIER=prototype|mvp|production` as a project hint. It does not hard-block behavior; it helps setup, doctor, and workflow prompts recommend the right amount of verification and provider spend.\n\n---\n\n## 9 Commands That Matter Most\n\nNine high-traffic commands cover the common Octopus workflows: lifecycle execution, councils, debate, research, design, quality, and specs.\n\n```bash\n/octo:embrace build stripe integration     # Full lifecycle: research → define → develop → deliver\n/octo:factory \"build a CLI that converts CSV to JSON\"  # Autonomous pipeline — spec in, software out\n/octo:council --goal decision \"Should we keep this service monolithic?\"  # Persona council with budget/veto gates\n/octo:debate monorepo vs microservices     # Structured four-way AI debate with consensus\n/octo:research --breadth=standard htmx vs react in 2026  # Attributed multi-provider research\n/octo:design mobile checkout redesign       # UI/UX design with BM25 style intelligence\n/octo:tdd create user auth                 # Red-green-refactor with test discipline\n/octo:security                              # OWASP vulnerability scan + remediation\n/octo:prd mobile checkout redesign          # AI-optimized PRD with 100-point scoring\n```\n\n`/octo:council` uses the real runner by default. Single-model simulation is only used when explicitly requested with `--simulate` or `--single-model`; `--research-first` writes a research artifact before fanout, and `--corpus-mode append|require` preserves synthesis and plans in project corpus workflows.\n\nPlus 40+ more: review, debug, extract, deck, docs, schedule, parallel, sentinel, optimize, brainstorm, claw, doctor, and [the full set](docs/COMMAND-REFERENCE.md).\n\nDon't remember the command name? Just describe what you need:\n\n```\n/octo:auto research microservices patterns    -\u003e routes to discover phase\n/octo:auto build user authentication          -\u003e routes to develop phase\n/octo:auto compare Redis vs DynamoDB          -\u003e routes to debate\n```\n\nThe smart router parses your intent and selects the right workflow.\n\nMulti-provider runs also write an agent status ledger. Use `octopus agent-summary` to see which providers contributed, which ran degraded, and which failed before synthesis.\n\n---\n\n## Pick a Command by Goal\n\nNot sure which command to use? Pick by goal:\n\n| I want to... | Use |\n|--------------|-----|\n| Research a topic thoroughly | `/octo:research` or `/octo:discover` |\n| Get a panel recommendation or gated implementation plan | `/octo:council` |\n| Debate two approaches | `/octo:debate` |\n| Build a feature end-to-end | `/octo:embrace` |\n| Design a UI or style system | `/octo:design` |\n| Review existing code | `/octo:review` |\n| Write tests first, then code | `/octo:tdd` |\n| Scan for vulnerabilities | `/octo:security` |\n| Write a product spec | `/octo:prd` |\n| Go from spec to shipping code | `/octo:factory` |\n| Debug a tricky issue | `/octo:debug` |\n| Reduce token usage | `/octo:doctor` (includes RTK install + token tips) |\n| Just run something quick | `/octo:quick` |\n\nOr skip the table — type `/octo:auto \u003cwhat you want\u003e` or just say `octo \u003cwhat you want\u003e`, and the smart router picks for you. 🔍\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow does this compare to Superpowers or plain Claude Code?\u003c/strong\u003e\u003c/summary\u003e\n\n| | Claude Code alone | [Superpowers](https://github.com/obra/superpowers) | Claude Octopus |\n|---|---|---|---|\n| **Core idea** | One model, your prompts | Structured methodology for one agent | Up to 8 providers cross-checking each other |\n| **Providers** | Claude only | Claude only | Codex, Gemini, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OpenCode |\n| **Workflow** | Ad-hoc | Spec → plan → subagent-driven dev | Discover → Define → Develop → Deliver (Double Diamond) |\n| **Strength** | Simple, no setup | Long autonomous runs with discipline | Multiple perspectives catching blind spots |\n| **Consensus gates** | No | No | Yes — 75% agreement threshold |\n| **Best for** | Quick tasks, simple features | Large builds with clear specs | Research, review, debates, multi-provider validation |\n| **Setup** | Nothing | Install plugin | Install plugin, optionally add providers |\n\n**tl;dr:** Superpowers makes one agent work really well for hours. Octopus makes multiple agents check each other's work. They solve different problems.\n\n\u003c/details\u003e\n\n---\n\n## How It Works\n\n### How 8 Providers Work Together\n\nClaude Octopus coordinates up to eight AI providers — one per tentacle:\n\n| Provider | Role |\n|----------|------|\n| 🔴 Codex (OpenAI, GPT-5.4) | Code review + implementation — edge-case hunting, terminal-heavy execution, patch/test loops |\n| 🟡 Gemini (Google) | Ecosystem breadth — alternatives, research synthesis |\n| 🟣 Perplexity | Live web search — CVE lookups, dependency research, current docs |\n| 🌐 OpenRouter | Alternative model routing — access 100+ models via single API |\n| 🟢 Copilot (GitHub) | Zero-cost research — uses existing GitHub Copilot subscription |\n| 🟤 Qwen (Alibaba) | Free-tier research — 1,000-2,000 requests/day via Qwen OAuth |\n| ⚫ Ollama (Local) | Zero-cost local LLM — offline, privacy-sensitive, fallback |\n| 🔵 Claude (Anthropic, Opus 4.8 + Sonnet 4.6) | Architecture, strategy, security review, orchestration, consensus, final synthesis |\n\nProviders 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.\n\n**Premium Claude routing** defaults `architect`, `strategist`, `security-reviewer`, and opt-in `implementer-heavy` to the current Opus family. On Claude Code v2.1.154+ that is Opus 4.8; older supported hosts fall back to Opus 4.7 and then 4.6. `code-reviewer` and `implementer` default to GPT-5.4 (Terminal-Bench and edge-case review). Opt out with `OCTOPUS_LEGACY_ROLES=1` to restore the v9.28 mapping. See [CHANGELOG](CHANGELOG.md) and [GPT-5.4 prompting guide](docs/GPT-5.4-PROMPTING.md).\n\n**Native dynamic workflows:** Claude Code v2.1.154+ can run native dynamic workflows for huge single-Claude migrations. Use that path when one Claude workflow is enough; use Octopus when you need multi-provider disagreement, councils, adversarial review, external model validation, or blind-spot coverage.\n\n### Four Phases: Discover, Define, Develop, Deliver\n\nFour structured phases adapted from the UK Design Council's methodology:\n\n| Phase | Command | What happens |\n|-------|---------|-------------|\n| Discover | `/octo:discover` | Multi-AI research and broad exploration |\n| Define | `/octo:define` | Requirements clarification with consensus |\n| Develop | `/octo:develop` | Implementation with quality gates |\n| Deliver | `/octo:deliver` | Adversarial review and go/no-go scoring |\n\nRun phases individually or all four with `/octo:embrace`. Configure autonomy: supervised (approve each phase), semi-autonomous (intervene on failures), or autonomous (run all four).\n\n### 32 Specialist Personas\n\nSpecialized 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.\n\nCategories: Software Engineering (11), Specialized Development (6), Documentation \u0026 Communication (5), Research \u0026 Strategy (3), Business \u0026 Compliance (3), Creative \u0026 Design (4).\n\n[Full persona reference](docs/AGENTS.md) | [All 54 skills](docs/COMMAND-REFERENCE.md)\n\n### Built-in Reaction Engine\n\nWhen 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:\n\n| Integration Point | When It Fires |\n|-------------------|---------------|\n| `/octo:parallel` | Between poll cycles while monitoring work packages |\n| `/octo:sentinel` | After triage scan completes |\n| `agent-registry.sh health --react` | On-demand health check |\n\n**What it auto-handles:**\n\n| Event | Reaction | Limits |\n|-------|----------|--------|\n| CI failure | Collects failure logs into agent inbox | 3 retries, escalates after 30m |\n| Changes requested | Collects review comments into agent inbox | 2 retries, escalates after 60m |\n| Agent stuck | Escalates to human | After 15m with no progress |\n| PR approved + CI green | Notifies you it's ready to merge | — |\n| PR merged | Marks agent complete | — |\n\n**Override defaults per project** by creating `.octo/reactions.conf`:\n\n```\n# EVENT|ACTION|MAX_RETRIES|ESCALATE_AFTER_MIN|ENABLED\nci_failed|forward_logs|5|45|true\nchanges_requested|forward_comments|3|90|true\nstuck|escalate|0|10|true\n```\n\nReactions track 13 agent lifecycle states: `running` → `pr_open` → `ci_pending` → `ci_failed` / `review_pending` → `changes_requested` / `approved` → `mergeable` → `merged` → `done`.\n\n---\n\n## Providers and What They Cost\n\n### Authentication\n\n| Method | Codex | Gemini | Claude |\n|--------|-------|--------|--------|\n| OAuth (recommended) | `codex login` — included in ChatGPT subscription | Google account — included in AI subscription | Built into Claude Code |\n| API key | `OPENAI_API_KEY` — per-token billing | `GEMINI_API_KEY` — per-token billing | Built into Claude Code |\n\nOAuth users pay nothing beyond their existing subscriptions.\n\n### What You Get With Just Claude\n\nEverything 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.\n\n---\n\n## Trust, Safety, and Limits\n\n**Command namespace** — Slash commands are namespaced under `/octo:*` and the `octo` natural-language prefix routes through the plugin's intent detection. Lifecycle hooks (session start/end, prompt submit, tool use, compaction, plan mode, worktrees, task lifecycle, idle, config change, permission events) also attach to Claude Code so multi-provider routing, freeze/discipline modes, and the work-queue watcher can function. See `.claude-plugin/hooks.json` for the full list. Uninstall removes every hook.\n\n**Data locations** — Results in `~/.claude-octopus/results/`, logs in `~/.claude-octopus/logs/`, project state in `.octo/`. Nothing hidden.\n\n**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.\n\n**Session provider controls** — Temporarily disable exhausted providers without uninstalling them. For example, `/octo:model-config disable codex --session` keeps Codex out of provider detection and multi-LLM fanout for the current session; `/octo:model-config clear-allowlist --session` restores the default.\n\n**Clean uninstall** — Run `claude plugin uninstall octo` from your terminal. If you see a scope error, add `--scope project`. No residual config changes.\n\n---\n\n## Works With OpenClaw\n\nClaude Octopus ships with a compatibility layer for [OpenClaw](https://github.com/openclaw/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.\n\n### Architecture\n\n```\nClaude Code Plugin (unchanged)\n  └── .mcp.json ─── MCP Server ─── orchestrate.sh\n                                        ↑\nOpenClaw Extension ─────────────────────┘\n```\n\nThree components, zero changes to the core plugin:\n\n| Component | Location | Purpose |\n|-----------|----------|---------|\n| MCP Server | `mcp-server/` | Exposes 10 Octopus tools via Model Context Protocol |\n| OpenClaw Extension | `openclaw/` | Wraps workflows for OpenClaw's extension API |\n| Skill Schema | `mcp-server/src/schema/skill-schema.json` | Universal skill metadata format |\n\n### MCP Server\n\nThe MCP server is **opt-in** — it does not start automatically. This prevents a permanent `✘ failed` status in Claude Code's `/mcp` panel for users who don't need it.\n\nTo enable it, add the server to your project's `.mcp.json` or global Claude Code settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"octo-claw\": {\n      \"command\": \"node\",\n      \"args\": [\"--require\", \"./mcp-server/check-node-version.js\", \"./mcp-server/dist/index.js\"],\n      \"cwd\": \"\u003cpath-to-claude-octopus\u003e\",\n      \"env\": {\n        \"OCTO_CLAW_ENABLED\": \"true\"\n      }\n    }\n  }\n}\n```\n\nOnce enabled, it exposes:\n\n- `octopus_discover`, `octopus_define`, `octopus_develop`, `octopus_deliver` — Individual phases\n- `octopus_embrace` — Full Double Diamond workflow\n- `octopus_debate`, `octopus_council`, `octopus_review`, `octopus_security` — Specialized workflows\n- `octopus_list_skills`, `octopus_status` — Introspection\n\nAny MCP-compatible client can connect to the server.\n\n### OpenClaw Extension\n\nInstall in an OpenClaw instance from git:\n\n```bash\nnpm install github:nyldn/claude-octopus#main --prefix openclaw\n```\n\nOr clone and link locally:\n\n```bash\ncd openclaw \u0026\u0026 npm install \u0026\u0026 npm run build\n```\n\nThe extension registers as an OpenClaw plugin with configurable workflows, autonomy modes, and Claude Code path resolution.\n\n### Build \u0026 Validate\n\n```bash\n./scripts/build-openclaw.sh          # Regenerate skill registry from frontmatter\n./scripts/build-openclaw.sh --check  # CI mode — exits non-zero if out of sync\n./tests/validate-openclaw.sh         # 13-check validation suite\n```\n\n---\n\n## FAQ\n\n**Do I need all three AI providers?**\nNo. One external provider plus Claude gives you multi-AI features. No external providers still gives you personas, workflows, and skills.\n\n**Will this break my existing Claude Code setup?**\nNo. Activates only with the `octo` prefix. Results stored separately. Uninstalls cleanly.\n\n**What happens if a provider times out?**\nThe workflow continues with available providers. You'll see the status in the visual indicators.\n\n**Why \"octopus\"?**\n🐙 *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.\n\n**How do I debug when something goes wrong?**\nRun commands with the `--verbose` flag to get detailed debugging output. Logs are stored in `~/.claude-octopus/logs/` for inspection. You can also use `/octo:doctor` to run diagnostics and identify potential issues.\n\n---\n\n## Community\n\nJoin [r/ClaudeOctopus](https://www.reddit.com/r/ClaudeOctopus/) for help, workflow tips, showcases, and updates.\n\n[![Star History Chart](https://api.star-history.com/image?repos=nyldn/claude-octopus\u0026type=date\u0026legend=top-left)](https://www.star-history.com/?repos=nyldn%2Fclaude-octopus\u0026type=date\u0026legend=top-left)\n\n### Contributing\n\n1. [Report issues](https://github.com/nyldn/claude-octopus/issues)\n2. Submit PRs following existing code style\n3. `git clone https://github.com/nyldn/claude-octopus.git \u0026\u0026 make test`\n\nSee [CONTRIBUTING.md](docs/CONTRIBUTING.md) for details.\n\n---\n\n## Documentation\n\n- [Documentation Guide](docs/README.md) — Start here\n- [Command Reference](docs/COMMAND-REFERENCE.md) — Commands, triggers, and provider indicators\n- [Feature Gap Analysis](docs/FEATURE-GAP.md) — CC feature adoption tracker\n- [Architecture](docs/ARCHITECTURE.md) — Provider flow and execution model\n- [Plugin Architecture](docs/PLUGIN-ARCHITECTURE.md) — Internal plugin structure\n- [Agents \u0026 Personas](docs/AGENTS.md) — All 32 personas\n- [CLI Reference](docs/CLI-REFERENCE.md) — Direct CLI usage, debug mode, async, and tmux\n- [Changelog](CHANGELOG.md)\n\n---\n\n## Attribution\n\n- **[wolverin0/claude-skills](https://github.com/wolverin0/claude-skills)** — AI Debate Hub. MIT License.\n- **[obra/superpowers](https://github.com/obra/superpowers)** — Discipline skills patterns, verification-before-completion philosophy, two-stage review approach, and review response patterns. MIT License.\n- **[nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)** — BM25 design intelligence databases. MIT License.\n- **[UK Design Council](https://www.designcouncil.org.uk/our-resources/the-double-diamond/)** — Double Diamond methodology.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/nyldn\"\u003enyldn\u003c/a\u003e | MIT License | \u003ca href=\"https://www.reddit.com/r/ClaudeOctopus/\"\u003er/ClaudeOctopus\u003c/a\u003e | \u003ca href=\"https://github.com/nyldn/claude-octopus/issues\"\u003eReport Issues\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyldn%2Fclaude-octopus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnyldn%2Fclaude-octopus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyldn%2Fclaude-octopus/lists"}