octo — плагин для Claude Code: что делает и как установить

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

<p align="center">
  <img src="docs/assets/demo.gif" alt="Claude Octopus Demo — debate and research with multiple AI providers" width="720">
</p>

<p align="center">
  <a href="https://claude.ai"><img src="https://img.shields.io/badge/Claude-Built_with_AI-c96442?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTEyIDJhMTAgMTAgMCAxIDAgMCAyMCAxMCAxMCAwIDAgMCAwLTIwbTAgMS44YTEuMiAxLjIgMCAwIDEgLjg1LjM1bDEuNSA0LjVhLjYuNiAwIDAgMCAuMzUuMzVsNC41IDEuNWExLjIgMS4yIDAgMCAxIDAgMi4yN2wtNC41IDEuNWEuNi42IDAgMCAwLS4zNS4zNWwtMS41IDQuNWExLjIgMS4yIDAgMCAxLTIuMjcgMGwtMS41LTQuNWEuNi42IDAgMCAwLS4zNS0uMzVsLTQuNS0xLjVhMS4yIDEuMiAwIDAgMSAwLTIuMjdsNC41LTEuNWEuNi42IDAgMCAwIC4zNS0uMzVsMS41LTQuNUExLjIgMS4yIDAgMCAxIDEyIDMuOCIvPjwvc3ZnPg==&labelColor=333" alt="Built with Claude"></a>
  <a href="https://github.com/nyldn/claude-octopus/actions/workflows/test.yml"><img src="https://github.com/nyldn/claude-octopus/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
  <img src="https://img.shields.io/badge/Version-11.15.1-blue" alt="Version 11.15.1">
  <img src="https://img.shields.io/badge/Claude_Code-v2.1.14+_required-blueviolet" alt="Requires Claude Code v2.1.14+">
  <img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License">
</p>

🐙 **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](https://github.com/thedotmack/claude-mem), [agentmemory](https://github.com/rohitg00/agentmemory), and [deja-vu](https://github.com/vshulcz/deja-vu) 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

### Research uses your chosen intensity

`/octo:discover` and `/octo:research` pass your quick, standard, or deep
selection to the research engine. The workflow examples also pass prior-phase
results correctly and put focus, depth, and audit scope in the prompt.
See [knowledge workflows](docs/KNOWLEDGE-WORKERS.md#workflow-customization).

### Session preferences stay outside your repository

SessionEnd saves preferences and Markdown session learnings in the current
project's existing Claude auto-memory directory. SessionStart restores
preferences from that directory. The hooks no longer create `memory/` in your
repository or fall back to an unrelated project's memory. Custom Claude
configuration directories use the same mapping at session start and end.

SessionEnd also saves structured cross-task learnings as JSON under
`~/.claude-octopus/learnings`. That store is shared across projects and is not
automatically read by SessionStart. See [session memory troubleshooting](docs/TROUBLESHOOTING.md#session-preferences-and-memory).

<!-- BEGIN CURRENT RELEASE -->
> 🆕 **v11.15.1 — Honor selected research intensity, correct workflow examples, and keep session memory outside repositories.**
>
> **Default roster:** Claude Opus 5.5 leads architecture, planning, security reasoning, and final judgment; GPT-5.6 Sol is the independent implementation/review peer; Claude Sonnet 5.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](docs/MODEL-ROUTING-STRATEGY.md).
<!-- END CURRENT RELEASE -->
>
> ```bash
> /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
> /octo:model-config tier premium claude claude-fable-5-1  # one bounded Fable judgment seat
> /octo:model-config tier premium codex gpt-6-astra        # one bounded Astra judgment seat
> ```

> 🆕 **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.
>
> ```bash
> /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.15.1** (new) | Honor selected research intensity, correct workflow examples, and keep session memory outside repositories. |
| **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 →](CHANGELOG.md)

[V10 migration guide →](docs/V10-MIGRATION.md)

<details>
<summary>Upgrading to v10</summary>

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.

</details>

<details>
<summary>Upgrading to 9.5x</summary>

<!-- BEGIN CURRENT MODEL DEFAULTS -->
- Current fresh configurations use **GPT-5.6 Sol** for Codex implementation/review, **Claude Opus 5.5** for premium Claude work, and **Claude Sonnet 5.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.
<!-- END CURRENT MODEL DEFAULTS -->
- 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`.

</details>

## Quickstart

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

**Supported platforms:** Linux and macOS run natively. For Windows, use the
[Claude Code CLI inside WSL or a desktop SSH session](#using-claude-code-from-windows).
Native Git Bash, MSYS2, and Cygwin are unsupported. Octopus hooks exit immediately
on those hosts in Claude Code and Codex, without writing install or session state.

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

```bash
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.

```bash
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](docs/INSTALLATION-HEALTH.md) 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 185 Claude Code capability flags through **Claude Code v2.1.284**.

<details>
<summary>Install for Codex CLI</summary>

```bash
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](docs/PLUGIN-COMPATIBILITY.md) 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:

```bash
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.

</details>

<details>
<summary>Install for Cursor IDE</summary>

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.

```bash
# 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):
```

```json
{
  "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 Claude Code from Windows

Install and launch the Claude Code CLI inside your WSL distribution, then install
Octopus there. Run `claude` from the WSL terminal. Its Linux home has its own
plugins and settings; a Windows-side installation does not carry over.

For Claude Code Desktop, select an SSH environment connected to a Linux or macOS
host and install Octopus on that host. The desktop app's built-in WSL environment
currently does not load plugins. See the official [WSL limitations](https://code.claude.com/docs/en/desktop-wsl)
and [desktop SSH guide](https://code.claude.com/docs/en/desktop#ssh-sessions).

### Using Cursor on WSL

<details>
<summary>Show Cursor setup steps</summary>

If you're running Cursor on Windows with WSL, clone the repo inside WSL and point the MCP config through `wsl.exe`:

```json
{
  "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.
</details>

See [docs/IDE-INTEGRATION.md](docs/IDE-INTEGRATION.md) for the full guide including `ide-attach.sh` auto-setup.
</details>

<details>
<summary>Install for OpenCode</summary>

```bash
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
```
</details>

<details>
<summary>Other install methods (Claude Code)</summary>

**From the Claude Code UI:** Type `/plugin` in a session → **Marketplace** tab → install **octo**.

**Factory AI (Droid):**
```bash
droid plugin marketplace add https://github.com/nyldn/claude-octopus.git
droid plugin install octo@nyldn-plugins
```
</details>

<details>
<summary>Update / Troubleshooting</summary>

[Claude Code leaves auto-update off by default for third-party marketplaces](https://code.claude.com/docs/en/discover-plugins#configure-auto-updates).
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.

```bash
# 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:

```bash
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
```

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](docs/PLUGIN-UPDATES.md).

For Anthropic-compatible gateways, Claude Code v2.1.129+ requires an explicit opt-in before `/model` discovers models from `/v1/models`:

```bash
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`.
</details>

---

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

```bash
#!/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:

```bash
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.

```bash
/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](docs/COMMAND-REFERENCE.md).

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:

| 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:skill-doctor` or `octopus doctor` (includes RTK install + token tips) |
| Just run something quick | `/octo:quick` |

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

<details>
<summary><strong>How does this compare to Superpowers or plain Claude Code?</strong></summary>

| | Claude Code alone | [Superpowers](https://github.com/obra/superpowers) | Claude Octopus |
|---|---|---|---|
| **Core idea** | One model, your prompts | Structured methodology for one agent | Built-in Claude plus up to 12 external integrations cross-checking each other |
| **Providers** | Claude only | Claude only | Claude host; Codex, Antigravity CLI, Copilot, Qwen, Ollama, Perplexity, OpenRouter, OrcaRouter, OpenCode, Cursor CLI, Grok, and Kimi Code |
| **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.

</details>

---

## How It Works

### Focused engineering methods

Architecture, TDD, and debugging now run on the current host by default. This
keeps routine work fast and avoids a provider call that adds little value. Add
an independent-review request when one bounded review would materially improve the
decision. Explicit debate, council, and multi-model commands are unchanged.

Planning can propose a time-boxed prototype for one risky assumption. Setup can
resume an interrupted human login without treating old authentication evidence as
current. Maintainers can also inspect policy or production provider selection with
the offline routing preview. The preview never claims to verify the final model,
entitlement, quota, fallback, or dispatch.

See [Workflow methods](docs/WORKFLOW-METHODS.md) for the contracts and limits.

### How 12 External Providers Work Together

Claude Octopus coordinates twelve 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.6 Sol/Terra/Luna; explicit GPT-6 Astra) | Code review + implementation — edge-case hunting, terminal-heavy execution, patch/test loops |
| 🧭 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 |
| 🐋 OrcaRouter | OpenAI-compatible gateway routing with policy enforcement and model fallbacks |
| 🟢 Copilot (GitHub) | Zero-cost...