🐙 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.0 — Add automatic Premium peer routing to /octo:auto.
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"
| Version |
Best Features |
| v11.4.0 (new) |
Add automatic Premium peer routing to /octo:auto. |
| v9.50 |
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 (introduced with Opus 4.8 and now following the current Opus 5 default), 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 |
Up to 10 external provider integrations (Codex, Antigravity CLI, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OrcaRouter, OpenCode, and Grok) alongside the Claude Code host. Structured provider debates and configurable multi-LLM councils. Explicit-only activation by default, with an optional smart router. 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. Opt-in discipline gates and token compression. Two-stage review. Circuit breakers with automatic provider recovery inside active workflows. Cursor + OpenCode + Codex cross-compatibility. bin/octopus CLI. 182 Claude Code capability flags through v2.1.219, including Opus 5, Sonnet 5, 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. |
Full changelog →
V10 migration guide →
Upgrading to v10
V10 adds a durable execution contract, fail-closed contribution validation,
Doctor 2.0, Provider Registry 2.0, process-tree cancellation evidence, and
opt-in eval routing. Existing provider and model pins still win. Automation that
uses doctor --json must handle exit 1 while retaining its valid JSON body;
invalid arguments return 2. See the migration guide for compatibility and
rollback details.
Upgrading to 9.5x
- Current fresh configurations use GPT-5.6 Sol for Codex implementation/review, Claude Opus 5 for premium Claude work, and Claude Sonnet 5 for the standard Claude seat. Existing environment, session, and
providers.json pins remain unchanged; OCTOPUS_LEGACY_ROLES=1 restores the pre-frontier role mapping.
- New claude-sdk seat env vars (v9.50):
CLAUDE_SDK_API_KEY, OCTOPUS_CLAUDE_SDK_MODEL, OCTOPUS_CLAUDE_SDK_MAX_TOKENS, OCTOPUS_CLAUDE_SDK_ALLOWED_MODELS, OCTOPUS_CLAUDE_SDK_CONTEXT_BUDGET.
- Fable guards apply to
claude-fable-5-1 and preserved claude-fable-5 pins. OCTOPUS_FABLE5_MAX_EFFORT raises the default high ceiling without disabling the other guards.
- Premium Claude role routing (architect, strategist, security-reviewer to Opus) landed in v9.29; restore the older mapping with
OCTOPUS_LEGACY_ROLES=1.
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.
Install for Codex CLI
codex plugin marketplace add https://github.com/nyldn/plugins.git
codex plugin add claude-octopus@nyldn-plugins
Restart Codex. Skills appear automatically — invoke with $skill-doctor, $skill-debug, etc.
See plugin compatibility for invocation policy,
hook trust, and the distinction between local Codex support and public-directory
submission.
Codex owns the versioned cache. To refresh an existing installation without
editing cache files or symlinks directly, exit Codex and run these commands in
a separate terminal:
codex plugin marketplace upgrade nyldn-plugins
codex plugin add claude-octopus@nyldn-plugins
Restart Codex after the update. Replacing the cache from the session that is
using it can leave hooks and skills bound to a removed version directory.
Install for Cursor IDE
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": {
"OPENAI_API_KEY": "${env:OPENAI_API_KEY}"
}
}
}
}
Restart Cursor. Tools appear in Cursor's AI chat — invoke by asking e.g. "use octopus_discover to research X".
Using Cursor on WSL?
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}"
}
}
}
}
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.
Install for OpenCode
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
Other install methods (Claude Code)
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 / Troubleshooting
Claude Code leaves auto-update off by default for third-party marketplaces.
To opt in to host-managed startup updates, run /plugin, open
Marketplaces, select nyldn-plugins, and choose Enable auto-update.
When Claude reports that Octopus was updated, run /reload-plugins (or restart
Claude Code) before using the new version.
# 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 also checks local host metadata at SessionStart. The advisory is
cooldown-limited and performs no network, package-manager, or authentication
calls; it only reports disabled auto-update, a locally known newer version, or
a loaded session that needs a reload. Run focused diagnostics at any time:
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
This cannot make an arbitrarily old installation self-heal: code that predates
the advisory must be updated once manually. It does make future stale states
visible and hands the actual mutation to Claude Code or Codex, which own their
plugin caches and lifecycle. See Plugin Update Safety.
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.
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 `/o
Claude Octopus 是一个 Claude Code 插件，让你用多个 AI 模型（Codex、Copilot、Ollama、Grok、Kimi 等）运行同一个研究、设计或编程任务，并在你交付之前标出它们之间的分歧。