Loading plugin...
Every AI model has blind spots. Claude Octopus supports ten external provider integrations — Codex, Gemini, Antigravity CLI, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OpenCode, and Grok — alongside the built-in Claude Code host, with consensus gates that flag disagreements before you ship. Claude-native first, Octopus for escalation.
Every AI model has blind spots. Claude Octopus supports ten external provider integrations — Codex, Gemini, Antigravity CLI, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OpenCode, and Grok — alongside the built-in Claude Code host, with consensus gates that flag disagreements before you ship.
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.
🐙 Research, build, review, and ship — with ten external providers checking the host'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.
🧠 Remembers across sessions. Integrates with claude-mem and agentmemory 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), 50 commands (slash commands you type), 58 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. Adds up to ten external provider integrations. Zero external providers are needed to start. Add them one at a time — each activates automatically when detected.
💰 Five providers cost nothing extra when you already have access. Codex, Gemini, Antigravity CLI, and Copilot use existing subscriptions or local auth. Ollama runs locally for free. Qwen now requires API-key or Coding-Plan auth; its free OAuth tier ended on 2026-04-15.
🆕 v9.50 — Claude Code 2026 compatibility layer. Routine manifest for scheduled and GitHub-event automations, a SubagentStop quality/cost gate,
/octo:usageper-provider cost attribution in Claude Code's/usageschema, aworktree.bgIsolationopt-out for fast direct-edit runs, a Claude Agent SDK seat (CLAUDE_SDK_API_KEY, Opus 4.8, 1M context), a four-skill starter pack, and a/plugin browsemanifest with projected context cost./octo:usage --format table # who spent what, per provider/skill/MCP server OCTOPUS_WORKTREE_BG_ISOLATION=false # skip worktree cloning for fast runs
🆕 v9.41 — Multi-LLM Council.
/octo:councilruns 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./octo:council --goal decision --style adversarial "Should this service stay monolithic?" /octo:council --goal implement --implement plan-only "Refactor the auth flow"
| Version | Best Features |
|---|---|
| v9.50 (new) | Claude Code 2026 compatibility layer — routines manifest (schedule + GitHub-event automations), SubagentStop quality/cost gate, /octo:usage cost attribution, worktree.bgIsolation opt-out, Claude Agent SDK seat (Opus 4.8, 1M context), starter skills pack, /plugin browse manifest with projected context cost. |
| v9.41 | /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. |
| v9 (current) | Up to 10 external provider integrations (Codex, Gemini, Antigravity CLI, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OpenCode, Grok) alongside the Claude Code host. Structured provider 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. |
| 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. |
| v7 | Double Diamond workflow. Multi-provider dispatch. Quality gates and consensus scoring. Configurable sandbox modes. |
OCTOPUS_CODEX_MODEL=gpt-5.4 if needed.CLAUDE_SDK_API_KEY, OCTOPUS_CLAUDE_SDK_MODEL, OCTOPUS_CLAUDE_SDK_MAX_TOKENS, OCTOPUS_CLAUDE_SDK_ALLOWED_MODELS, OCTOPUS_CLAUDE_SDK_CONTEXT_BUDGET.OCTOPUS_FABLE5_MODE (auto/off/on), OCTOPUS_FABLE5_NO_RETRY. Guards auto-enable only when you pin claude-fable-5.OCTOPUS_LEGACY_ROLES=1.# Terminal (not inside a Claude Code session):
claude plugin marketplace add https://github.com/nyldn/plugins.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.
Claude Code v2.1.50+ 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.
git clone --depth 1 https://github.com/nyldn/claude-octopus.git ~/.codex/claude-octopus && mkdir -p ~/.agents/skills && ln -sf ~/.codex/claude-octopus/skills ~/.agents/skills/claude-octopus
Restart Codex. Skills appear automatically — invoke with $skill-doctor, $skill-debug, etc.
Cursor 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.
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.
# 1. Clone the repo
git clone --depth 1 https://github.com/nyldn/claude-octopus.git ~/.cursor/claude-octopus
# 2. Install MCP server dependencies
cd ~/.cursor/claude-octopus/mcp-server && npm install
# 3. Configure Cursor — add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):
{
"mcpServers": {
"claude-octopus": {
"command": "npx",
"args": ["tsx", "${userHome}/.cursor/claude-octopus/mcp-server/src/index.ts"],
"env": {
"OCTO_CLAW_ENABLED": "true",
"OPENAI_API_KEY": "${env:OPENAI_API_KEY}",
"GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
}
}
}
}
Restart Cursor. Tools appear in Cursor's AI chat — invoke by asking e.g. "use octopus_discover to research X".
If you're running Cursor on Windows with WSL, clone the repo inside WSL and point the MCP config through wsl.exe:
{
"mcpServers": {
"claude-octopus": {
"command": "wsl",
"args": ["npx", "tsx", "/home/<user>/.cursor/claude-octopus/mcp-server/src/index.ts"],
"env": {
"OPENAI_API_KEY": "${env:OPENAI_API_KEY}",
"GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
}
}
}
}
Replace <user> with your WSL username. Make sure node and npm are installed inside WSL.
See docs/IDE-INTEGRATION.md for the full guide including ide-attach.sh auto-setup.
git clone --depth 1 https://github.com/nyldn/claude-octopus.git ~/.opencode/claude-octopus
mkdir -p ~/.agents/skills
ln -s ~/.opencode/claude-octopus/skills ~/.agents/skills/claude-octopus
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.git
droid plugin install octo@nyldn-plugins
# Update
claude plugin marketplace update nyldn-plugins
claude plugin update octo@nyldn-plugins
# 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/octo
claude plugin marketplace remove nyldn-plugins
claude plugin marketplace add https://github.com/nyldn/plugins.git
claude plugin install octo@nyldn-plugins
Run focused diagnostics after updating:
/octo:doctor config # install path, version, manifest, Claude Code feature flags
/octo:doctor skills # skill loading, skillOverrides, plugin zip/URL capability notes
For Anthropic-compatible gateways, Claude Code v2.1.129+ requires an explicit opt-in before /model discovers models from /v1/models:
export ANTHROPIC_BASE_URL=https://your-gateway.example/v1
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
Claude 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.
When 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:
CLAUDE_OCTOPUS_AUTONOMY=autonomous / OCTOPUS_AUTONOMY=autonomous unless already setSet OCTOPUS_REMOTE_STATUSLINE=full to opt back into the full local HUD, or OCTOPUS_REMOTE_STATUSLINE=off to suppress statusline output entirely.
Cloud environment setup should install provider CLIs and expose only the credentials required for the workflow. Paste this into the cloud environment setup script:
#!/usr/bin/env bash
set -e
npm install -g @openai/codex @google/gemini-cli @qwen-code/qwen-code 2>/dev/null || true
echo "Octopus cloud setup:"
command -v codex >/dev/null 2>&1 && echo " Codex CLI: installed" || echo " Codex CLI: missing"
command -v gemini >/dev/null 2>&1 && echo " Gemini CLI: installed" || echo " Gemini CLI: missing"
command -v agy >/dev/null 2>&1 && echo " Antigravity CLI: installed" || echo " Antigravity CLI: missing"
command -v qwen >/dev/null 2>&1 && echo " Qwen CLI: installed" || echo " Qwen CLI: missing"
command -v gh >/dev/null 2>&1 && echo " GitHub CLI: installed" || echo " GitHub CLI: optional, install if Sentinel needs GitHub"
Set environment variables in the cloud environment, not in the script:
OPENAI_API_KEY=...
GEMINI_API_KEY=...
PERPLEXITY_API_KEY=... # optional
OPENROUTER_API_KEY=... # optional
Provider API calls require internet access from the hosted environment.
For 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.
Set 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.
Nine high-traffic commands cover the common Octopus workflows: lifecycle execution, councils, debate, research, design, quality, and specs.
/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:council --goal decision "Should we keep this service monolithic?" # Persona council with budget/veto gates
/octo:debate monorepo vs microservices # Structured provider debate with consensus
/octo:research --breadth=standard htmx vs react in 2026 # Attributed multi-provider research
/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
/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.
Plus 40+ more: review, debug, extract, deck, docs, schedule, parallel, sentinel, optimize, 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.
Multi-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.
Not sure which command to use? Pick by goal:
| I want to... | Use |
|---|---|
| Research a topic thoroughly | /octo:research or /octo:discover |
| Get a panel recommendation or gated implementation plan | /octo:council |
| Debate two approaches | /octo:debate |
| Build a feature end-to-end | /octo:embrace |
| Design a UI or style system | /octo:design |
| Review existing code | /octo:review |
| Write tests first, then code | /octo:tdd |
| Scan for vulnerabilities | /octo:security |
| Write a product spec | /octo:prd |
| Go from spec to shipping code | /octo:factory |
| Debug a tricky issue | /octo:debug |
| Reduce token usage | /octo:doctor (includes RTK install + token tips) |
| Just run something quick | /octo:quick |
Or skip the table — type /octo:auto <what you want> or just say octo <what you want>, and the smart router picks for you. 🔍
| Claude Code alone | Superpowers | Claude Octopus | |
|---|---|---|---|
| Core idea | One model, your prompts | Structured methodology for one agent | Built-in Claude plus up to 10 external integrations cross-checking each other |
| Providers | Claude only | Claude only | Claude host; Codex, Gemini, Antigravity CLI, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OpenCode, Grok |
| Workflow | Ad-hoc | Spec → plan → subagent-driven dev | Discover → Define → Develop → Deliver (Double Diamond) |
| Strength | Simple, no setup | Long autonomous runs with discipline | Multiple perspectives catching blind spots |
| Consensus gates | No | No | Yes — 75% agreement threshold |
| Best for | Quick tasks, simple features | Large builds with clear specs | Research, review, debates, multi-provider validation |
| Setup | Nothing | Install plugin | Install plugin, optionally add providers |
tl;dr: Superpowers makes one agent work really well for hours. Octopus makes multiple agents check each other's work. They solve different problems.
Claude Octopus coordinates ten external provider integrations alongside the built-in Claude Code host. The optional claude-sdk route is a second Anthropic seat, so it is shown below but is not counted as a separate provider family.
| Provider | Role |
|---|---|
| 🔴 Codex (OpenAI, GPT-5.5) | Code review + implementation — edge-case hunting, terminal-heavy execution, patch/test loops |
| 🟡 Gemini (Google) | Ecosystem breadth — alternatives, research synthesis |
🧭 Antigravity CLI (agy) | Google Antigravity perspective via native stdin print-mode dispatch |
| 🟣 Perplexity | Live web search — CVE lookups, dependency research, current docs |
| 🌐 OpenRouter | Alternative model routing — access 100+ models via single API |
| 🟢 Copilot (GitHub) | Zero-cost research — uses existing GitHub Copilot subscription |
| 🟤 Qwen (Alibaba) | Qwen3-Coder research via API-key or Coding-Plan auth |
| ⚫ Ollama (Local) | Zero-cost local LLM — offline, privacy-sensitive, fallback |
| 🟠 OpenCode | Alternate coding-agent integration and cross-checking seat |
| ⚡ Grok (xAI, via cursor-agent) | Frontier-model second opinion — added as a first-class seat in v9.48 |
| 🔵 Claude (Anthropic, Opus 4.8 + Sonnet 4.6) | Architecture, strategy, security review, orchestration, consensus, final synthesis |
🔵 Claude Agent SDK seat (claude-sdk) | Optional second Anthropic seat: Opus 4.8 with the 1M-token context window, independent of the host session (set CLAUDE_SDK_API_KEY) |
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.
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.5 (Terminal-Bench and edge-case review). Opt out with OCTOPUS_LEGACY_ROLES=1 to restore the v9.28 mapping. See CHANGELOG and GPT-5.4 prompting guide.
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.
Four structured phases adapted from the UK Design Council's methodology:
| Phase | Command | What happens |
|---|---|---|
| Discover | /octo:discover | Multi-AI research and broad exploration |
| Define | /octo:define | Requirements clarification with consensus |
| Develop | /octo:develop | Implementation with quality gates |
| Deliver | /octo:deliver | Adversarial review and go/no-go scoring |
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).
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 58 skills
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:
| Integration Point | When It Fires |
|---|---|
/octo:parallel | Between poll cycles while monitoring work packages |
/octo:sentinel | After triage scan completes |
agent-registry.sh health --react | On-demand health check |
What it auto-handles:
| Event | Reaction | Limits |
|---|---|---|
| CI failure | Collects failure logs into agent inbox | 3 retries, escalates after 30m |
| Changes requested | Collects review comments into agent inbox | 2 retries, escalates after 60m |
| Agent stuck | Escalates to human | After 15m with no progress |
| PR approved + CI green | Notifies you it's ready to merge | — |
| PR merged | Marks agent complete | — |
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.
| Method | Codex | Gemini | Antigravity | Claude |
|---|---|---|---|---|
| OAuth/subscription (recommended) | codex login — included in ChatGPT subscription | Google account — included in AI subscription | agy auth — included with Antigravity access | Built into Claude Code |
| API key | OPENAI_API_KEY — per-token billing | GEMINI_API_KEY — per-token billing | n/a | Built into Claude Code |
OAuth users pay nothing beyond their existing subscriptions. Qwen is the exception: its free OAuth tier ended on 2026-04-15, so use QWEN_API_KEY or Coding-Plan (OPENAI_API_KEY + OPENAI_BASE_URL).
Illustrative token-only estimates, using standard global API rates checked 2026-07-13: GPT-5.5 $5/$30, Gemini 3.1 Pro Preview $2/$12 for prompts through 200K tokens and $4/$18 for prompts over 200K, Sonar Pro $3/$15, and Opus 4.8 $5/$25 per million input/output tokens. The ranges assume roughly 90% input and 10% output tokens, standard (not batch, flex, priority, or fast) processing, no cache discounts, and a representative mix of those models. OAuth/subscription seats (Codex via ChatGPT, Gemini via Google account, Antigravity, Copilot) bill nothing extra; Ollama is free.
The table excludes provider tool charges. Sonar Pro adds a request fee of $6-$14 per 1,000 requests depending on search-context size; Gemini search grounding can add query fees after its included allowance. GPT-5.5 sessions above 272K input tokens and Gemini prompts over 200K use higher long-context rates, so large runs can exceed the upper range. Treat these as planning bounds and check the linked rate cards before material spend.
| Run | Typical volume | Illustrative API token cost (tool fees excluded) |
|---|---|---|
| Single probe / quick question (one provider) | 5-20K tokens | $0.01-0.20 |
| Debate (2-3 providers, multi-round) | 30-80K tokens | $0.20-1.00 |
| Council (4-6 seats + synthesis) | 60-150K tokens | $0.50-2.50 |
| Full embrace (4 phases, multi-provider) | 150-400K tokens | $1.00-6.00+ |
Before an expensive run, /octo:costs shows a session cost projection; after runs, /octo:usage breaks down actual spend per provider and skill. Anything projected over $1 is called out before dispatch.
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.
v9.50.0 aligns the plugin with Claude Code's 2026 native capabilities. Each piece degrades gracefully on older Claude Code versions via the existing SUPPORTS_* feature detection.
.claude-plugin/routines.json): saved automation configs mapping schedule and GitHub-event triggers to /octo: commands. All ship disabled; each entry carries a provider roster and a cost note so you know what enabling it will bill.hooks/subagent-stop-gate.sh): quality scoring, provider attribution, cost logging, and council verdict pre-screening before a subagent's summary reaches the lead./octo:usage: per-provider, per-skill, and per-MCP-server token and cost breakdown in Claude Code's /usage schema, built from local usage records (no provider dispatch).worktree.bgIsolation session flag; disables background worktree cloning for fast direct-edit runs.claude-sdk): with CLAUDE_SDK_API_KEY set, workflows can seat Opus 4.8 with the 1M-token context window independent of the host session.skills/octopus-starter-pack/): debate kickoff, council verdict interpretation, provider health summary, and model cost comparison skills./plugin browse manifest (.claude-plugin/plugin-manifest.json): projected context cost and component inventory for the plugin browse pane.| Variable | Default | Effect |
|---|---|---|
CLAUDE_SDK_API_KEY | unset | Enables the claude-sdk provider seat (Claude Agent SDK; Opus 4.8, 1M context) |
OCTOPUS_CLAUDE_SDK_MODEL | claude-opus-4-8 | Model for the claude-sdk seat |
OCTOPUS_CLAUDE_SDK_MAX_TOKENS | 8192 | Max output tokens for the claude-sdk seat (SDK CLI path) |
OCTOPUS_CLAUDE_SDK_ALLOWED_MODELS | unset | Comma-separated model allowlist for the claude-sdk seat |
OCTOPUS_CLAUDE_SDK_CONTEXT_BUDGET | 1000000 | Prompt context budget for claude-sdk agent types |
OCTOPUS_WORKTREE_BG_ISOLATION | true | Set false to skip background worktree cloning (fast direct-edit runs) |
OCTOPUS_SUBAGENT_GATE_STRICT | false | Set true to let the SubagentStop gate block malformed council verdicts and low-quality summaries |
OCTOPUS_SUBAGENT_MIN_QUALITY | 0 | Quality floor (0-100) enforced by the gate in strict mode; 0 disables |
v9.51.0 adds first-class support for Claude Fable 5 (Anthropic's Mythos-class model, $10/$50 per MTok — 2x Opus 4.8). Fable 5 is never auto-selected; pin it with OCTOPUS_OPUS_MODEL=claude-fable-5 (opus seats) or OCTOPUS_CLAUDE_SDK_MODEL=claude-fable-5 (the 1M-context SDK seat). When a pin is detected, the plugin auto-enables three guards and prints a one-line banner:
xhigh/max effort clamps to high for Fable dispatches. Fable 5 effort applies per tool call; higher settings widen scope at 2x cost without extending runs.claude-sdk seat retries once on Opus 4.8 instead of failing the seat.A SessionStart hook injects the dispatch profile (prompt anti-patterns, judgment routing, risk-surface escalation) whenever a pin is active. Full guidance: skills/blocks/fable5-prompting.md.
| Variable | Default | Effect |
|---|---|---|
OCTOPUS_FABLE5_MODE | auto | off disables all Fable 5 guards; on forces them without a pin |
OCTOPUS_FABLE5_NO_RETRY | unset | Set 1 to disable the refusal retry on the claude-sdk seat |
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 hooks/hooks.json for the full list. Uninstall removes every hook.
Data locations — Results in ~/.claude-octopus/results/, logs in ~/.claude-octopus/logs/, project state in .octo/. Nothing hidden.
Provider transparency — Every command shows a 🐙 activation indicator on launch. Provider markers such as 🔴 🟡 🧭 🟣 🔵 show exactly which providers are running and when external APIs are called. You always know what's happening.
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.
Clean uninstall — Run claude plugin uninstall octo from your terminal. If you see a scope error, add --scope project. No residual config changes.
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.
Claude Code Plugin (unchanged)
└── .mcp.json ─── MCP Server ─── orchestrate.sh
↑
OpenClaw Extension ─────────────────────┘
Three components, zero changes to the core plugin:
| Component | Location | Purpose |
|---|---|---|
| MCP Server | mcp-server/ | Exposes 10 Octopus tools via Model Context Protocol |
| OpenClaw Extension | openclaw/ | Wraps workflows for OpenClaw's extension API |
| Skill Schema | mcp-server/src/schema/skill-schema.json | Universal skill metadata format |
The 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.
To enable it, add the server to your project's .mcp.json or global Claude Code settings:
{
"mcpServers": {
"octo-claw": {
"command": "node",
"args": ["--require", "./mcp-server/check-node-version.js", "./mcp-server/dist/index.js"],
"cwd": "<path-to-claude-octopus>",
"env": {
"OCTO_CLAW_ENABLED": "true"
}
}
}
}
Once enabled, it exposes:
octopus_discover, octopus_define, octopus_develop, octopus_deliver — Individual phasesoctopus_embrace — Full Double Diamond workflowoctopus_debate, octopus_council, octopus_review, octopus_security — Specialized workflowsoctopus_list_skills, octopus_status — IntrospectionAny MCP-compatible client can connect to the server.
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.
./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
Do I need every AI provider? 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.
How do I debug when something goes wrong?
Run 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.
Join r/ClaudeOctopus for help, workflow tips, showcases, and updates.
git clone https://github.com/nyldn/claude-octopus.git && make testSee CONTRIBUTING.md for details.
MIT — see LICENSE
.beads/
.gitignore
config.yaml
hooks/
post-checkout
post-merge
pre-commit
pre-push
prepare-commit-msg
interactions.jsonl
issues.jsonl
metadata.json
README.md
.claude/
.claude-plugin/
marketplace.json
PLUGIN_NAME_LOCK.md
plugin-manifest.json
plugin.json
README.md
routines.json
agents/
backend-architect.md
cloud-architect.md
code-reviewer.md
database-architect.md
debugger.md
docs-architect.md
frontend-developer.md
performance-engineer.md
security-auditor.md
tdd-orchestrator.md
claude-octopus.local.md
DEVELOPMENT.md
hooks/
pre-commit.sh
visual-feedback.sh
references/
stub-detection.md
validation-gates.md
settings.json
skills/
extract-skill/
SKILL.md
flow-define/
flow-define.tmpl
SKILL.md
flow-deliver/
flow-deliver.tmpl
SKILL.md
flow-develop/
flow-develop.tmpl
SKILL.md
flow-discover/
flow-discover.tmpl
SKILL.md
flow-parallel/
SKILL.md
flow-spec/
SKILL.md
skill-architecture/
SKILL.md
skill-audit/
SKILL.md
skill-claw/
SKILL.md
skill-code-review/
SKILL.md
skill-content-pipeline/
SKILL.md
skill-context-detection/
SKILL.md
skill-copilot-provider/
SKILL.md
skill-cost-projections/
SKILL.md
skill-coverage-audit/
SKILL.md
skill-debate/
SKILL.md
skill-debug/
SKILL.md
skill-decision-support/
SKILL.md
skill-deck/
SKILL.md
skill-deep-research/
SKILL.md
skill-design-lineage/
SKILL.md
skill-doc-delivery/
SKILL.md
skill-doc-sync/
SKILL.md
skill-doctor/
SKILL.md
skill-factory/
SKILL.md
skill-finish-branch/
SKILL.md
skill-intent-contract/
SKILL.md
skill-issues/
SKILL.md
skill-iterative-loop/
SKILL.md
skill-knowledge-work/
SKILL.md
skill-meta-prompt/
SKILL.md
skill-native-escalation-routing/
SKILL.md
skill-parallel-agents/
SKILL.md
skill-prd/
SKILL.md
skill-quick/
SKILL.md
skill-resume/
SKILL.md
skill-review-response/
SKILL.md
skill-rollback/
SKILL.md
skill-security-audit/
SKILL.md
skill-security-framing/
SKILL.md
skill-ship/
SKILL.md
skill-staged-review/
SKILL.md
skill-status/
SKILL.md
skill-task-management-v2/
SKILL.md
skill-tdd/
SKILL.md
skill-thought-partner/
SKILL.md
skill-ui-ux-design/
SKILL.md
skill-verification-gate/
SKILL.md
skill-visual-feedback/
SKILL.md
skill-writing-plans/
SKILL.md
sys-configure/
SKILL.md
state/
state-manager.md
.coderabbit.yaml
.codex-plugin/
plugin.json
.cursor-plugin/
commands/
octo-auto.md
octo-brainstorm.md
octo-careful.md
octo-claw.md
octo-costs.md
octo-council.md
octo-debate.md
octo-debug.md
octo-deck.md
octo-define.md
octo-deliver.md
octo-design-ui-ux.md
octo-dev.md
octo-develop.md
octo-discipline.md
octo-discover.md
octo-docs.md
octo-doctor.md
octo-embrace.md
octo-extract.md
octo-factory.md
octo-freeze.md
octo-guard.md
octo-history.md
octo-km.md
octo-loop.md
octo-meta-prompt.md
octo-model-config.md
octo-multi.md
octo-parallel.md
octo-pipeline.md
octo-plan.md
octo-prd-score.md
octo-prd.md
octo-preflight.md
octo-quick.md
octo-research.md
octo-resume.md
octo-retro.md
octo-review.md
octo-schedule.md
octo-scheduler.md
octo-security.md
octo-sentinel.md
octo-setup.md
octo-spec.md
octo-staged-review.md
octo-tdd.md
octo-unfreeze.md
octo.md
plugin.json
.factory-plugin/
marketplace.json
plugin.json
.gemini/
commands/
octo/
architect.toml
implement.toml
research.toml
review.toml
.github/
agents/
backend-architect.agent.md
cloud-architect.agent.md
code-reviewer.agent.md
database-architect.agent.md
debugger.agent.md
docs-architect.agent.md
frontend-developer.agent.md
performance-engineer.agent.md
security-auditor.agent.md
tdd-orchestrator.agent.md
copilot-instructions.md
dependabot.yml
FUNDING.yml
ISSUE_TEMPLATE/
bug_report.yml
config.yml
feature_request.yml
PULL_REQUEST_TEMPLATE.md
scripts/
post_reddit_update.py
workflows/
claude-octopus.yml
test.yml
.gitignore
.mcp.json
.opencode/
INSTALL.md
agents/
AGENTS.md
config.yaml
droids/
octo-backend-architect.md
octo-cloud-architect.md
octo-code-reviewer.md
octo-database-architect.md
octo-debugger.md
octo-docs-architect.md
octo-frontend-developer.md
octo-performance-engineer.md
octo-security-auditor.md
octo-tdd-orchestrator.md
personas/
academic-writer.md
ai-engineer.md
backend-architect.md
business-analyst.md
cloud-architect.md
code-reviewer.md
context-manager.md
database-architect.md
debugger.md
deployment-engineer.md
devops-troubleshooter.md
docs-architect.md
exec-communicator.md
finance-analyst.md
frontend-developer.md
graphql-architect.md
incident-responder.md
legal-compliance-advisor.md
marketing-strategist.md
mermaid-expert.md
openclaw-admin.md
performance-engineer.md
product-writer.md
python-pro.md
research-synthesizer.md
security-auditor.md
strategy-analyst.md
tdd-orchestrator.md
test-automator.md
typescript-pro.md
ui-ux-designer.md
ux-researcher.md
principles/
general.md
maintainability.md
performance.md
security.md
write-intent.md
skills/
architecture.md
code-review.md
security-audit.md
assets/
octopus-icon.svg
bin/
octo-compress
octo-hud
octopus
CHANGELOG.md
CLAUDE.md
commands/
auto.md
brainstorm.md
careful.md
claw.md
costs.md
council.md
debate.md
debug.md
deck.md
define.md
deliver.md
design-ui-ux.md
dev.md
develop.md
discipline.md
discover.md
docs.md
embrace.md
extract.md
factory.md
freeze.md
guard.md
history.md
km.md
loop.md
meta-prompt.md
model-config.md
multi.md
octo.md
parallel.md
pipeline.md
plan.md
prd-score.md
prd.md
preflight.md
quick.md
research.md
resume.md
retro.md
review.md
schedule.md
scheduler.md
security.md
sentinel.md
setup.md
spec.md
staged-review.md
tdd.md
unfreeze.md
usage.md
config/
blind-spots/
api.json
architecture.json
data.json
manifest.json
operations.json
security.json
ide-templates/
cursor-mcp.json
vscode-mcp.json
zed-settings.json
providers/
agy/
CLAUDE.md
claude/
CLAUDE.md
codex/
CLAUDE.md
copilot/
CLAUDE.md
gemini/
CLAUDE.md
ollama/
CLAUDE.md
opencode/
CLAUDE.md
templates/
config.json.template
ISSUES.md.template
LESSONS.md.template
PROJECT.md.template
ROADMAP.md.template
RUNTIME.md
STATE.md.template
workflows/
CLAUDE.md
... 929 more© 2026 Flowy · Free and open source
Built for Claude Code · Not affiliated with Anthropic