nyldn/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, agentmemory, and 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.

Research, design, copywriting, and image tasks can use authenticated Codex or installed Claude seats when Antigravity is unavailable. Provider configuration loads before fallback selection.

Claude Code sessions also identify their active host correctly when the shared plugin is installed in a Codex cache. This keeps Codex council seats independent. See provider availability and host detection.

Model configuration rejects unsafe names while preserving supported Antigravity display labels. Concurrent provider-history updates retain entries even when a directory utility reports success to multiple writers. Optional history recording requires Python 3 and skips the write if it cannot acquire the lock.

The MCP SDK is updated to 1.31.0, including an upstream OAuth client security fix. See the changelog for details.

Parallel work packages now use separate branches. Completed commits remain available after cleanup, and worktrees with uncommitted edits are kept for recovery. Failed packages record their completion status so the wave can finish.

Reviews and research retain provider stdout longer than the configured threshold, even when it contains a context-limit rejection phrase. Short stdout-only rejections and stderr rejection signatures still fail the affected seat. The new OCTO_PROVIDER_REJECTION_MAX_OUTPUT_BYTES setting adjusts the output-size threshold, with a default of 4096 bytes. See provider rejection handling.

Codex can create its thread-coordination and plugin-sync locks inside the Linux Tangle execution boundary. The locks use private temporary storage, while configuration and extension inputs remain read-only. See bounded Codex runs for host requirements and temporary-directory configuration.

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.14.1 — Codex ultra reasoning no longer fails at dispatch.

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.

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

/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 →

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

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.

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 185 Claude Code capability flags through Claude Code v2.1.284.

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

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.

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.

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

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 for the contracts and limits.

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.

Explicit research-breadth, debate, council, and adversarial-review workflows use multiple providers. Generic mergeable work starts with one capable owner and adds another model only for a distinct job. A 75% consensus quality gate prevents questionable work from shipping. Only Claude is required — all others are optional and auto-detected.

Frontier routing defaults architect, strategist, security-reviewer, and opt-in implementer-heavy to Opus 5.5 on Claude Code v2.1.280+ and Opus 5 on v2.1.219+, with Opus 4.8/4.7/4.6 fallbacks. code-reviewer and implementer use GPT-5.6 Sol; synthesizer uses Sonnet 5.5 on Claude Code v2.1.284+, Sonnet 5 on v2.1.197+, and Sonnet 4.6 on older hosts. Fable 5.1 and GPT-6 Astra remain explicit-only models: Premium mode may admit one configured judgment escalation per run, but neither model becomes a tier default, fallback, review-fleet seat, council seat, security seat, or implementation seat. Existing pins/configs win, and OCTOPUS_LEGACY_ROLES=1 restores the v9.28 mapping. See the routing strategy.

Native dynamic workflows: Claude Code v2.1.154+ can run native dynamic workflows for huge single-Claude migrations. Use that path when one Claude workflow is enough; use Octopus when you need multi-provider disagreement, councils, adversarial review, external model validation, or blind-spot coverage.

Four structured phases adapted from the UK Design Council's methodology:

Run phases individually or all four with /octo:embrace. Configure autonomy: supervised (approve each phase), semi-autonomous (intervene on failures), or autonomous (run all four).

Specialized agents selected by explicit Octopus workflows. /octo:security can select security-auditor and /octo:design-ui-ux can select ui-ux-designer; ordinary requests never delegate to these agents merely because keywords match.

Categories span Software Engineering, Specialized Development, Documentation & Communication, Research & Strategy, Business & Compliance, and Creative & Design.

Full persona reference | All 63 skills

When agents create PRs, the reaction engine monitors what happens next — CI failures, review comments, stale agents — and responds automatically. No new commands to learn. It fires transparently inside workflows you already use:

What it auto-handles:

Override defaults per project by creating .octo/reactions.conf:

# EVENT|ACTION|MAX_RETRIES|ESCALATE_AFTER_MIN|ENABLED
ci_failed|forward_logs|5|45|true
changes_requested|forward_comments|3|90|true
stuck|escalate|0|10|true

Reactions track 13 agent lifecycle states: running → pr_open → ci_pending → ci_failed / review_pending → changes_requested / approved → mergeable → merged → done.

OAuth users pay nothing beyond their existing subscriptions. Qwen is the exception: its free OAuth tier ended on 2026-04-15, so use QWEN_API_KEY or Coding-Plan (OPENAI_API_KEY + OPENAI_BASE_URL).

Illustrative token-only estimates, using standard global API rates checked 2026-09-22: GPT-5.6 Sol $4/$20, Sonar Pro $3/$15, and Opus 5.5 $4/$20 per million input/output tokens. The ranges assume roughly 90% input and 10% output tokens, standard (not batch, flex, priority, or fast) processing, no cache discounts, and a representative mix of those models. OAuth/subscription seats (Codex via ChatGPT, Antigravity, Copilot) bill nothing extra; Ollama is free.

The table excludes provider tool charges. Sonar Pro adds a request fee of $6-$14 per 1,000 requests depending on search-context size. Fable 5.1 and GPT-6 Astra each cost $10/$50 per million input/output tokens. Astra requests above 272K input tokens apply OpenAI's long-context multipliers to the whole request. Long-context and provider-specific rate rules can push large runs above these bounds, so check the linked rate cards before material spend.

Before an expensive run, /octo:costs shows a session cost projection; after runs, /octo:usage breaks down actual spend per provider and skill. Anything projected over $1 is called out before dispatch.

Everything except multi-AI features. You get all 31 personas, structured workflows, smart routing, context detection, and every skill. Multi-AI orchestration (parallel analysis, debate, consensus) activates when external providers are configured.

v9.50.0 aligns the plugin with Claude Code's 2026 native capabilities. Each piece degrades gracefully on older Claude Code versions via the existing SUPPORTS_* feature detection.

• Routines (.claude-plugin/routines.json): saved automation configs mapping schedule and GitHub-event triggers to /octo: commands. All ship disabled; each entry carries a provider roster and a cost note so you know what enabling it will bill.
• SubagentStop gate (hooks/subagent-stop-gate.sh): quality scoring, provider attribution, cost logging, and council verdict pre-screening before a subagent's summary reaches the lead.
• /octo:usage: per-provider, per-skill, and per-MCP-server token and cost breakdown in Claude Code's /usage schema, built from local usage records (no provider dispatch).
• Worktree bgIsolation opt-out: mirror of Claude Code's worktree.bgIsolation session flag; disables background worktree cloning for fast direct-edit runs.
• Claude Agent SDK seat (claude-sdk): with CLAUDE_SDK_API_KEY set, workflows can seat Opus 5 with the 1M-token context window independent of the host session.
• Starter pack (skills/octopus-starter-pack/): debate kickoff, council verdict interpretation, provider health summary, and model cost comparison skills.
• /plugin browse manifest (.claude-plugin/plugin-manifest.json): projected context cost and component inventory for the plugin browse pane.

GPT-6 Astra is cataloged as an explicit-only premium model at $10/$50 per MTok. Use OCTOPUS_CODEX_MODEL=gpt-6-astra or an exact codex:gpt-6-astra seat for a direct pin. To keep the default Sol route and allow one bounded architecture or strategy escalation per run, use /octo:model-config tier premium codex gpt-6-astra, select Premium mode, and set an OCTOPUS_MAX_COST_USD ceiling that covers the projected list-price usage for the prompt. Astra is never selected for implementation, review, security, councils, review fleets, or fallback chains, and Astra plus GPT-5.6 does not provide vendor diversity.

Codex CLI v0.153.1 or newer is required; unknown versions fail closed. The configured Premium ceiling is checked against a conservative projected list-price estimate for the prompt before the bounded seat is claimed; a request that does not fit stays on Sol. The generic OpenAI-compatible adapter uses Chat Completions, so it rejects tool-enabled Astra dispatches until that adapter supports the Responses API. No-tool review prompts remain available. Astra's initial rollout is limited, and requests above 272K input tokens incur OpenAI's long-context multipliers.

Claude Fable 5.1 is an explicit-only Mythos-class model at $10/$50 per MTok, compared with $4/$20 for the current Opus 5.5 lead. Pin it with OCTOPUS_OPUS_MODEL=claude-fable-5-1 (opus seats) or OCTOPUS_CLAUDE_SDK_MODEL=claude-fable-5-1 (the 1M-context SDK seat). For a bounded Premium route, /octo:model-config tier premium claude claude-fable-5-1 keeps the version-gated Opus default as the normal seat and admits at most one Fable architecture or strategy dispatch per run. Host-seat pins require Claude Code v2.1.255 or newer to recognize Fable 5.1 and its 1M context window. The independent claude-agent SDK path has no Claude Code version floor; it requires CLAUDE_SDK_API_KEY and the claude-agent executable. If the SDK shim falls back to the headless claude CLI, that executable must also be v2.1.255 or newer. Existing claude-fable-5 pins remain exact and supported. When either model is selected, the plugin enables three guards and prints a one-line banner:

• Security reroute — by default, security-audit dispatches for ordinary Fable pins (security-auditor persona, squeeze red/blue workflow) run on Opus 5 because Fable can refuse adversarial security phrasing even in authorized audits. Exact model-qualified Fable security seats fail closed.
• Effort clamp — xhigh/max effort clamps to high by default. Set OCTOPUS_FABLE5_MAX_EFFORT=xhigh|max for one bounded high-value run without disabling the other guards.
• Refusal retry — a refused or empty Fable 5 dispatch on the claude-sdk seat retries once on Opus 5 instead of failing the seat.

A SessionStart hook injects the dispatch profile (prompt anti-patterns, judgment routing, risk-surface escalation) whenever a pin is active. Full guidance: skills/blocks/fable5-prompting.md.

Oversized prompts can be summarized before dispatch. The preflight summarizer receives a budget derived from the target agent effective budget rather than the ordinary synthesizer role quota.

• OCTOPUS_CONTEXT_SUMMARY_TRIGGER_RATIO defaults to 110 and controls the summarize trigger as a percentage of the target effective budget.
• OCTOPUS_PREFLIGHT_CONTEXT_BUDGET_RATIO defaults to 125 and scales the preflight input budget from the target budget.
• OCTOPUS_PREFLIGHT_CONTEXT_BUDGET_ADDITIVE defaults to 2048 and provides an additive floor above the target budget.

The effective preflight budget is capped by the summarizer provider input ceiling. fail and truncate strategies keep exact budget enforcement; the trigger ratio applies only to summarize. Preflight summaries are rejected when they drop Tangle machine-consumed anchors present in the original prompt. See docs/context-budget.md.

Command namespace — Slash commands are namespaced under /octo:* and the octo natural-language prefix routes through the plugin's intent detection. Lifecycle hooks (session start/end, prompt submit, tool use, compaction, plan mode, worktrees, task lifecycle, idle, config change, permission events) also attach to Claude Code so multi-provider routing, freeze/discipline modes, and the work-queue watcher can function. See hooks/hooks.json for the full list. Uninstall removes every hook.

Data locations — Results in ~/.claude-octopus/results/, logs in ~/.claude-octopus/logs/, project state in .octo/. Nothing hidden.

Provider transparency — Every command shows a 🐙 activation indicator on launch. Provider markers such as 🔴 🟡 🧭 🟣 🔵 show exactly which providers are running and when external APIs are called. You always know what's happening.

Session provider controls — Temporarily disable exhausted providers without uninstalling them. For example, /octo:model-config disable codex --session keeps Codex out of provider detection and multi-LLM fanout for the current session; /octo:model-config clear-allowlist --session restores the default.

Uninstall the plugin. Run claude plugin uninstall octo from your terminal. If you see a scope error, add --scope project. This removes the plugin but does not delete results, logs, configuration, or local state under ~/.claude-octopus/, nor project state in .octo/. Review uninstall and retained-data guidance before removing any of those paths manually.

MCP Client ─── MCP Server ─── orchestrate.sh ─── provider CLIs and APIs

The standalone MCP server exposes Claude Octopus workflows to compatible IDEs and clients without changing the Claude Code plugin.

Add the server to your project's MCP configuration or global client settings:

{
  "mcpServers": {
    "claude-octopus": {
      "command": "node",
      "args": ["--require", "./mcp-server/check-node-version.js", "./mcp-server/dist/index.js"],
      "cwd": "<path-to-claude-octopus>"
    }
  }
}

Once enabled, it exposes:

• octopus_discover, octopus_define, octopus_develop, octopus_deliver — Individual phases
• octopus_embrace — Full Double Diamond workflow
• octopus_debate, octopus_council, octopus_review, octopus_security — Specialized workflows
• octopus_set_editor_context — IDE editor-state context
• octopus_list_skills, octopus_status — Introspection

Any MCP-compatible client can connect to the server.

In v11, workflow tools and status require an absolute project_root for each call. See the migration guide before updating an existing MCP integration.

Do I need every AI provider? No. One external provider plus Claude gives you multi-AI features. No external providers still gives you personas, workflows, and skills.

Will this break my existing Claude Code setup? No. Its commands are namespaced under the octo prefix, and results are stored separately. Lifecycle hooks still attach to Claude Code. If you explicitly set OCTOPUS_AUTO_ROUTER_MODE=invoke, ordinary prompts can also route through Octopus. Uninstalling the plugin removes its commands and hooks but preserves local data until you choose to remove it.

What happens if a provider times out? The workflow continues with available providers. You'll see the status in the visual indicators.

Can bounded Tangle implementation run on macOS? Not currently. Bounded Tangle dispatch is fail-closed and requires Linux with a working Bubblewrap (bwrap) execution boundary. On macOS, Tangle refuses provider dispatch with an explicit operator error rather than falling back to unconfined execution.

Why "octopus"? 🐙 Fun fact: a real octopus has three hearts, blue blood, and 500 million neurons — two-thirds of which live in its eight arms. Each arm can taste, touch, and act independently. Claude Octopus works the same way: each tentacle (command) operates autonomously with its own squeeze of logic, then ink flows back as the final deliverable. The crossfire review? That's the squeeze — adversarial pressure that untangles everything before it ships.

How do I debug when something goes wrong? Run commands with the --verbose flag to get detailed debugging output. Logs are stored in ~/.claude-octopus/logs/ for inspection. You can also invoke /octo:skill-doctor in Claude Code or run octopus doctor in a shell to identify potential issues.

Join r/ClaudeOctopus for help, workflow tips, showcases, and updates.

1. Report issues
2. Submit PRs following existing code style
3. git clone https://github.com/nyldn/claude-octopus.git && make test

See CONTRIBUTING.md for details.

• Documentation Guide — Start here
• Command Reference — Commands, triggers, and provider indicators
• Troubleshooting — Provider auth failures and common errors
• Architecture — Provider flow and execution model
• Agents & Personas — All 31 personas
• Provider Wiring Map — How a provider is wired (contributors)
• Developer Guide — Modular config, E2E testing, enforcement patterns
• Scheduler — Scheduled workflow runner
• Privacy — What leaves your machine and when
• Security Policy — Threat model and trust boundaries
• Releasing — Release checklist (maintainers)
• Changelog

Selected workflow methods adapt patterns from mattpocock/skills under the MIT License. The distribution includes the complete license and a source-to-destination map in Third-party notices.

• wolverin0/claude-skills — AI Debate Hub. MIT License.
• obra/superpowers — Discipline skills patterns, verification-before-completion philosophy, two-stage review approach, and review response patterns. MIT License.
• nextlevelbuilder/ui-ux-pro-max-skill — BM25 design intelligence databases. MIT License.
• UK Design Council — Double Diamond methodology.

MIT — see LICENSE

nyldn | MIT License | r/ClaudeOctopus | Report Issues

Design-review seats and synthesis use versioned JSON v1 contracts for all model-to-model data. Historical free text is accepted only through a deprecated compatibility wrapper that materializes canonical JSON before downstream use. See Design review JSON contracts v1 and the schemas in schemas/design-review-*-v1.schema.json.

Tangle coding agents are unbounded by default at the wall-clock layer and use a progress-aware stall watchdog. Users can still set an explicit absolute timeout. See Tangle adaptive coding supervision.

Planner reconsideration uses a versioned JSON v1 contract: explicit accept/reject decisions for every adequacy scope recommendation plus a nested decomposition JSON v1 object. The historical DECISIONS:/DECOMPOSITION: response remains a deprecated compatibility fallback. See Tangle reconsideration JSON v1 and schemas/tangle-reconsideration-v1.schema.json.

Tangle adequacy review uses a versioned JSON v1 contract and renders validated reviews into the historical internal text format consumed by planner reconsideration. The textual VERDICT:/REASONS:/SCOPE_REVIEW: form remains a deprecated compatibility fallback. See Tangle adequacy review JSON v1 and schemas/tangle-adequacy-v1.schema.json.

Tangle decomposition uses a versioned JSON v1 provider contract and renders validated JSON into the existing internal wire format. The historical wire/Markdown formats remain deprecated compatibility fallbacks during migration. See Tangle decomposition JSON contract and schemas/tangle-decomposition-v1.schema.json.

See Tangle read context for the optional strict/contextual read policy. The upstream default remains strict; read authorization never broadens write permission.