nyldn/claude-octopus

🐙 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), 54 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.8.0 — Durable evidence-backed research, validated planning and design reviews, and safer concurrent setup.

> 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

🆕 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?"

| Version | Best Features | |---------|--------------| | v11.8.0 (new) | Durable evidence-backed research, validated planning and design reviews, and safer concurrent setup. | | 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 →

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.

Installation health

Not sure which command to use? Run /octo:guide or /octo:auto help to browse the commands in your installed version. Neither starts a provider workflow.

Octopus records non-secret install metadata for each host. Claude Code and Codex keep separate entries, so switching hosts or updating one cache does not make the other look current. SessionStart refreshes the active host entry when the loaded root, version, scope, or profile changes.

octopus capabilities --json    # provider readiness and supported interfaces
octopus doctor installation    # loaded root, stable root, and saved metadata
octopus cache-check --json     # active, newest, stale, and stable plugin roots
octopus repair --dry-run       # explain a broken or stale stable link
octopus repair --apply         # repair that link and refresh install metadata
octopus security-audit --json  # offline checks of the installed plugin files
octopus handoff export --json  # redacted checkpoint for another supported host

repair --apply changes only the Octopus-owned stable plugin root and install metadata. On platforms without symlink support, the stable root contains generated wrappers for Octopus script entry points. Repair does not delete host caches. The security audit checks the plugin itself; use /octo:security when you want a multi-model review of your project.

The core context profile keeps optional context hooks off. Use octopus profile orchestration to enable context reinforcement and post-tool coordination during active Octopus workflows, or octopus profile full to allow every profile-managed context hook. Profiles never disable safety or lifecycle hooks. See installation health for exit codes and stored state.

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//.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
octopus doctor installation # loaded root, stable root, saved metadata, and profile
octopus cache-check --json   # validate active, newest, and stale cache entries
octopus repair --dry-run     # inspect a stable-root problem without changing it

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

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