🐙 Claude Octopus

Every AI model has blind spots. Claude Octopus supports twelve external provider integrations — Codex, Antigravity CLI, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OrcaRouter, OpenCode, Cursor CLI, Grok, and Kimi Code — 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.

Claude Octopus is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Anthropic.

🐙 Research, build, review, and ship — with twelve external providers checking the host's work. Claude-native handles the ordinary path. Octopus remains dormant until you explicitly run /octo:*, then handles the escalated path. A 75% consensus gate catches disagreements before they reach production.

🧠 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.

🔄 Choose the workflow the task needs. Use a focused method for architecture, debugging, or TDD. Use /octo:embrace for Discover → Define → Develop → Deliver, with quality gates between phases.

🐙 31 specialized personas (role-specific AI agents like security-auditor, backend-architect), 53 commands (slash commands you type), 63 skills (reusable workflow modules). Explicit workflows select the experts they need; ordinary Claude requests do not activate Octopus.

🐙 Works with just Claude. Adds up to twelve external provider integrations. Zero external providers are needed to start. Add them one at a time — each becomes available when detected and runs only inside an explicit workflow.

💰 Five providers cost nothing extra when you already have access. Codex, Antigravity CLI, Copilot, and Cursor CLI 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.

What's New

Engineering methods

Octopus includes eight engineering methods adapted from Matt Pocock's skills. Routine architecture, TDD, and debugging use your current host. Ask for an independent opinion when a reviewer would help. Plans capture domain terms and blocking decisions, compare interface designs, and can propose a time-limited prototype.

Setup can resume an interrupted configuration and rechecks readiness before reporting success. See workflow methods for usage and the changelog for release details.

Premium /octo:auto routes also run one bounded cross-provider peer check after an eligible single-owner result, without requiring a second command or flag. Budget and Standard routes do not add the check, and existing multi-model workflows are not double-reviewed. Set OCTOPUS_PREMIUM_PEER_CHECK=off to disable it.

🆕 v11.4.1 — Fix doctor diagnostics for non-interactive agent checks and recurring failure reports.

Default roster: Claude Opus 5 leads architecture, planning, security reasoning, and final judgment; GPT-5.6 Sol is the independent implementation/review peer; Claude Sonnet 5 is the standard Claude seat; Fable 5.1 remains an opt-in judgment escalation. Existing model pins and provider configuration still win. See the routing strategy.

/octo:model-config                         # inspect or override the frontier roster
OCTOPUS_OPUS5_AUTO_XHIGH=1                 # opt in to automatic xhigh Opus 5 phases
OCTOPUS_OPUS_MODEL=claude-fable-5-1        # explicitly opt in to Fable 5.1
OCTOPUS_CODEX_MODEL=gpt-6-astra            # explicitly opt in to Astra

🆕 v9.41 — Multi-LLM Council. /octo:council runs a structured 3/5/7-persona deliberation across Claude, Codex, Antigravity, 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"

Full changelog →

V10 migration guide →

Quickstart

# 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.

Dormant by default

Installing Octopus does not route ordinary prompts, launch provider workflows, or delegate to Octopus agents. Every shipped command and skill uses Claude Code's native manual-invocation gate. Start it with /octo:*.

Seeing cannot be used with Skill tool due to disable-model-invocation? That is the gate working as intended — the model tried to auto-invoke an Octopus skill. Invoke it explicitly instead: type /octo:skill-doctor (the manually invokable skill), not a model call to the skill-doctor skill. Slash skills are user-invoked, so they bypass this invocation gate; the model will not call Octopus skills on its own unless you opt into the router below. Rule of thumb: invoke Octopus with /octo:…, don't expect Claude to reach for it for you.

Optional automation remains available, but it is explicit opt-in:

export OCTOPUS_AUTO_ROUTER_MODE=suggest  # suggest a route for plain prompts
# or: OCTOPUS_AUTO_ROUTER_MODE=invoke    # load the matched command route
export OCTO_DONE_CRITERIA=on             # compound-task completion coaching
export OCTOPUS_COMPRESS_ENABLED=true     # PostToolUse output compression
export OCTO_STRATEGY_ROTATION=on         # failure strategy rotation
export OCTOPUS_CONTEXT_AWARENESS=on      # statusline-to-context reinforcement
export OCTOPUS_SESSION_MEMORY=on         # SessionStart preference restoration

This legacy opt-in examines ordinary prompts. invoke can start paid external-provider workflows and share the routed prompt context with configured providers; prefer suggest unless that behavior is intentional. Provider-side retention follows each provider account's policy. Unset the variable (or set it to off) to opt out without disabling direct /octo:* commands.

Safety guards that prevent invalid direct Codex, Qwen, or retired Gemini CLI dispatch remain available, but host-side command filters keep them out of unrelated tool calls.

Claude 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 183 Claude Code capability flags through Claude Code v2.1.219.

codex plugin marketplace add https://github.com/nyldn/plugins.git
codex plugin add claude-octopus@nyldn-plugins

codex plugin marketplace upgrade nyldn-plugins
codex plugin add claude-octopus@nyldn-plugins

# 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": {
        "OPENAI_API_KEY": "${env:OPENAI_API_KEY}"
      }
    }
  }
}

{
  "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}"
      }
    }
  }
}

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

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

# Manual update
claude plugin marketplace update nyldn-plugins
claude plugin update octo@nyldn-plugins

# Or let Octopus select the active host's supported plugin-manager commands
~/.claude-octopus/plugin/scripts/orchestrate.sh update-plugin

# 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

octopus doctor config   # install path, version, manifest, Claude Code feature flags
octopus doctor skills   # skill loading, skillOverrides, plugin zip/URL capability notes
octopus doctor updates  # loaded/install/catalog/cache versions and auto-update state

export ANTHROPIC_BASE_URL=https://your-gateway.example/v1
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

Claude Code Web and Remote Sessions

When an explicit Octopus workflow is running in a hosted, web, or remote-control environment, set OCTOPUS_REMOTE_SESSION=true in that environment. Claude hosting alone does not activate Octopus. Once a workflow starts, orchestrate.sh also recognizes CLAUDE_CODE_REMOTE=true or CLAUDE_CODE_WEB=true and applies unattended-safe runtime defaults:

• CLAUDE_OCTOPUS_AUTONOMY=autonomous / OCTOPUS_AUTONOMY=autonomous unless already set
• provider smoke tests and Codex tier probes are skipped
• the statusline uses a lightweight remote-safe display

Set 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 @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 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=...
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.

9 Commands That Matter Most

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, 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.

Pick a Command by Goal

Not sure which command to use? Pick by goal:

Or type /octo:auto <what you want> and the smart router picks for you. Plain-prompt routing is off until you run /octo:setup, which turns on suggestions (Octopus names a matching command; it never dispatches a provider on its own). Set OCTOPUS_AUTO_ROUTER_MODE=off to silence them, or invoke to let a matched route load automatically. 🔍