🐙 Works with just Claude. Scales to eight. Zero providers needed to start. Add them one at a time — each activates automatically when detected.

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

What's New

| Version | Best Features | |---------|--------------| | v9 (current) | Up to 8 providers (Codex, Gemini, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OpenCode). Four-way AI debates. Smart router — just say what you need. 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. 122 CC feature flags through v2.1.91. | | 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 →

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.

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

Claude Code Web and Remote Sessions

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 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 @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 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 t