From octo
Orchestrates parallel multi-provider AI execution using Double Diamond methodology (probe, grasp, tangle, ink) for research, building, reviewing code. Triggers on /octo:multi or 'run with all providers'.
npx claudepluginhub nyldn/claude-octopus --plugin octoThis skill uses the workspace's default tool permissions.
**When this skill is invoked, you MUST dispatch work to multiple providers in parallel. You are PROHIBITED from:**
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
When this skill is invoked, you MUST dispatch work to multiple providers in parallel. You are PROHIBITED from:
This skill exists specifically for multi-provider parallel work. If you catch yourself thinking "I'll just do this myself" โ STOP.
Multi-tentacled orchestrator for Claude Code - using Double Diamond methodology for comprehensive problem exploration, consensus building, and validated delivery.
DISCOVER DEFINE DEVELOP DELIVER
(probe) (grasp) (tangle) (ink)
\ / \ / \ / \ /
\ * / \ * / \ * / \ * /
\ * * / \ / \ * * / \ /
\ / \ / \ / \ /
\ / \ / \ / \ /
Diverge then Converge to Diverge with Converge to
converge problem solutions delivery
Note for Claude Code users: You don't need to run these commands! Just talk naturally to Claude:
- "Research OAuth authentication patterns"
- "Build a user authentication system"
- "Review this code for security issues"
The commands below are for direct CLI usage or automation.
# Full Double Diamond workflow (all 4 phases)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Build a user authentication system"
# Individual phases
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "Research authentication best practices"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grasp "Define auth requirements"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Implement auth feature"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Validate and deliver auth implementation"
# Crossfire: Adversarial cross-model review
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple "implement password reset API"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles security "implement JWT auth"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh squeeze "review auth.ts for vulnerabilities"
# Smart auto-routing (detects intent automatically)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "research OAuth patterns" # -> probe
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "build user login" # -> tangle + ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "review the auth code" # -> ink
DO NOT use this skill if the user's request involves:
Built-in Claude Code commands - Commands starting with / that are part of Claude Code itself:
/plugin - Plugin management (add, remove, update, list)/init - Project initialization/help - Help documentation/clear - Clear conversation/commit - Git commit operations/remember - Memory management/ command that isn't /parallel-agents or /octo:*Direct tool usage - Simple file operations, git commands, or terminal tasks
Claude Code configuration - Managing Claude Code itself
If the user's request matches any of the above, DO NOT activate this skill. Handle the request using standard Claude Code tools and capabilities instead.
Claude Octopus uses visual indicators so you always know which AI is responding:
| Indicator | Meaning | Uses |
|---|---|---|
| ๐ | Parallel Mode | Multiple CLIs orchestrated via orchestrate.sh |
| ๐ด | Codex CLI | OpenAI Codex (your OPENAI_API_KEY) |
| ๐ก | Gemini CLI | Google Gemini (your GEMINI_API_KEY) |
| ๐ต | Claude Subagent | Claude Code Task tool (built-in) |
External CLIs execute when:
/parallel-agents command explicitly/debate command (AI Debate Hub)Claude Subagents execute when:
Why this matters: External CLIs use your OpenAI/Google API quotas and incur costs. Claude subagents are included with Claude Code at no additional charge.
When you see ๐ CLAUDE OCTOPUS ACTIVATED, external CLI providers (Codex/Gemini) will be invoked for multi-perspective analysis.
Sometimes you want multi-provider analysis even for simple tasks that wouldn't normally trigger workflows. This is useful when you need comprehensive perspectives on decisions, want to compare how different models think, or when automatic routing underestimates task complexity.
Force multi-provider execution using the /octo:multi command:
/octo:multi "Explain how Redis works"
/octo:multi "What is OAuth?"
/octo:multi "Review this simple function"
/octo:multi "Should we use TypeScript?"
You can also force multi-provider mode with natural language:
"Run this with all providers: What is JWT?"
"I want all three AI models to look at our architecture"
"Get multiple perspectives on this design decision"
"Use all providers for explaining caching strategies"
"Force multi-provider analysis of our API design"
Use forced parallel mode when:
Don't force parallel mode when:
octo research, octo build, octo review)Forcing parallel mode uses external CLIs for every task, which incurs API costs:
| Provider | Cost per Query | What It Uses |
|---|---|---|
| ๐ด Codex CLI | ~$0.01-0.05 | Your OPENAI_API_KEY |
| ๐ก Gemini CLI | ~$0.01-0.03 | Your GEMINI_API_KEY |
| ๐ต Claude | Included | Claude Code subscription |
Total cost per forced query: ~$0.02-0.08
Use forced parallel mode judiciously for tasks where multiple perspectives genuinely add value. For routine work, let automatic routing decide when multi-provider analysis is beneficial.
When you force parallel mode, you'll see this banner:
๐ **CLAUDE OCTOPUS ACTIVATED** - Multi-provider mode
Force parallel execution
Providers:
๐ด Codex CLI - [Role in this task]
๐ก Gemini CLI - [Role in this task]
๐ต Claude - [Role in this task]
Followed by results from each provider marked with their indicators (๐ด ๐ก ๐ต).
IMPORTANT: Once you've determined this skill should activate (user asked to research, build, review, etc.), immediately run the provider detection below. DO NOT ask the user for permission - just check providers and proceed or show welcome message.
Silently run this fast detection script (completes in <1 second):
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh detect-providers
IMPORTANT - First Time Setup Detection: If the detect-providers command shows BOTH providers are missing (CODEX_STATUS=missing AND GEMINI_STATUS=missing), this is likely a first-time user. Before showing error messages, provide a friendly welcome message:
"๐ Welcome to Claude Octopus! I see this is your first time using the plugin.
To get started, you need to install one AI provider (you don't need both):
Option 1: OpenAI Codex (best for code generation)
npm install -g @openai/codex codex login # OAuth recommendedOr set API key:
export OPENAI_API_KEY="sk-..."Get key from: https://platform.openai.com/api-keysOption 2: Google Gemini (best for analysis)
npm install -g @google/gemini-cli gemini # OAuth recommendedOr set API key:
export GEMINI_API_KEY="AIza..."Get key from: https://aistudio.google.com/app/apikeyOnce you've installed one provider, you can start using Claude Octopus by just talking naturally:
- 'Research OAuth authentication patterns'
- 'Build a user authentication system'
- 'Review this code for security issues'
Need guided setup? Run
/octo:setup"
After showing this welcome message, STOP and wait for the user to set up a provider. Do not proceed with the original task until at least one provider is configured.
Expected output format:
Detecting Claude Code version...
CLAUDE_CODE_VERSION=2.1.9
CLAUDE_CODE_STATUS=ok
CLAUDE_CODE_MINIMUM=2.1.9
โ Claude Code version: 2.1.9 (meets minimum 2.1.9)
Detecting providers...
CODEX_STATUS=ok
CODEX_AUTH=oauth
GEMINI_STATUS=ok
GEMINI_AUTH=none
Summary:
โ Codex: Installed and authenticated (oauth)
โ Gemini: Installed but not authenticated
Parse the output and route accordingly:
Scenario 0: Claude Code version is outdated (CRITICAL - Check First)
CLAUDE_CODE_VERSION=2.1.8
CLAUDE_CODE_STATUS=outdated
CLAUDE_CODE_MINIMUM=2.1.9
Action: STOP immediately and show this prominent warning:
"โ ๏ธ Claude Code Update Required
Your current Claude Code version (2.1.8) is outdated. Claude Octopus requires version 2.1.9 or higher for full functionality.
How to update:
If installed via npm:
npm update -g @anthropic/claude-codeIf installed via Homebrew:
brew upgrade claude-codeIf installed via download: Visit https://github.com/anthropics/claude-code/releases
After updating, please restart Claude Code and then we can proceed with your task."
Do NOT proceed with the task until the user has updated and restarted. The detect-providers output will show this warning prominently.
Scenario A: Both providers missing
CODEX_STATUS=missing
CODEX_AUTH=none
GEMINI_STATUS=missing
GEMINI_AUTH=none
Action: STOP and tell the user:
"Claude Octopus needs at least one AI provider (Codex or Gemini) to work.
You have two options:
Option 1: Install Codex CLI
npm install -g @openai/codex export OPENAI_API_KEY=\"sk-...\"Get API key from: https://platform.openai.com/api-keys
Option 2: Install Gemini CLI
npm install -g @google/gemini-cli gemini # Run OAuth setupAfter installing one, run
/octo:setupto verify everything works."
Scenario B: One provider working, one missing/partial
CODEX_STATUS=ok
CODEX_AUTH=oauth (or api-key)
GEMINI_STATUS=missing (or ok with AUTH=none)
Action: IMMEDIATELY proceed with the user's task using the available provider. No need to announce setup status - just execute the task. The user doesn't care about which provider you're using, they just want their task done.
Scenario C: Both providers working
CODEX_STATUS=ok
CODEX_AUTH=oauth
GEMINI_STATUS=ok
GEMINI_AUTH=oauth
Action: IMMEDIATELY proceed with the user's task using both providers for comprehensive results. No need to announce setup status - just execute the task.
If only ONE provider is available:
You do NOT need both providers to proceed. One is sufficient for most tasks.
The detect-providers command writes results to ~/.claude-octopus/.provider-cache with a timestamp. This cache is valid for 1 hour.
If the cache exists and is fresh (<1 hour old), you can skip re-detection.
Only proceed when at least ONE provider is available and authenticated. Multi-provider tasks will automatically adapt to available providers.
IMPORTANT: This detection is fast (~1 second) and non-blocking. Always verify provider availability before running octopus commands, but don't require BOTH providers - one is enough!
Diverge then converge on understanding
Parallel research from 4 perspectives:
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "What are the best approaches for real-time notifications?"
Build consensus on the problem
Multi-tentacled problem definition:
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grasp "Define requirements for notification system" --context probe-synthesis-*.md
Diverge with multiple solutions
Enhanced map-reduce with validation:
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Implement notification service" --context grasp-consensus-*.md
Converge to validated delivery
Pre-delivery validation:
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Deliver notification system" --context tangle-validation-*.md
Run all 4 phases sequentially with automatic context passing:
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Create a complete user dashboard feature"
Different models have different blind spots. Crossfire commands force models to critique each other's work, catching more issues than single-model review.
Two tentacles wrestling until consensus
Codex and Gemini each propose solutions, then critique each other's work. A synthesis determines the winner.
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ
โ Codex โ โ Gemini โ
โ (Proposer) โ โ (Proposer) โ
โโโโโโโโฌโโโโโโโ โโโโโโโโฌโโโโโโโ
โ โ
โผ โผ
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ
โ PROPOSAL A โ โโโ โ PROPOSAL B โ
โโโโโโโโฌโโโโโโโ โโโโโโโโฌโโโโโโโ
โ โ
โผ โผ
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ
โ Gemini โ โ Codex โ
โ (Critic) โ โ (Critic) โ
โโโโโโโโฌโโโโโโโ โโโโโโโโฌโโโโโโโ
โ โ
โโโโโโโโโโโฌโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโ
โ SYNTHESIS โ
โ (Winner + Fix) โ
โโโโโโโโโโโโโโโโโโโ
# Basic grapple
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple "implement password reset API"
# Grapple with security principles
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles security "implement JWT authentication"
# Grapple with performance principles
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles performance "optimize database queries"
Octopus squeezes prey to test for weaknesses
Blue Team (Codex) implements secure code. Red Team (Gemini) attacks to find vulnerabilities. Then remediation and validation.
Phase 1: Blue Team implements secure solution
Phase 2: Red Team finds vulnerabilities
Phase 3: Remediation fixes all issues
Phase 4: Validation verifies all fixed
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh squeeze "implement user login form"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh squeeze "review auth.ts for vulnerabilities"
Grapple supports domain-specific critique principles:
| Principle | Focus | Use Case |
|---|---|---|
general | Overall quality | Default for most reviews |
security | OWASP Top 10, secure coding | Auth, payments, user data |
performance | N+1 queries, caching, async | Database, API optimization |
maintainability | Clean code, testability | Refactoring, code reviews |
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles security "implement password reset"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles performance "optimize search API"
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grapple --principles maintainability "refactor user service"
The auto command detects intent keywords and routes to the appropriate workflow:
| Keywords | Routes To | Phases |
|---|---|---|
| research, explore, investigate, analyze | probe | Discover |
| develop, dev, build, implement, create | tangle + ink | Develop + Deliver |
| qa, test, review, validate, check | ink | Deliver (quality focus) |
| security audit, red team, pentest | squeeze | Red Team |
| adversarial, cross-model, debate | grapple | Debate |
| (other coding keywords) | codex agent | Single agent |
| (other design keywords) | gemini agent | Single agent |
Examples:
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "research best practices for caching" # -> probe
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "build the caching layer" # -> tangle + ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "review the cache implementation" # -> ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "security audit the auth module" # -> squeeze
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "have both models debate the API design" # -> grapple
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "fix the cache invalidation bug" # -> codex
The tangle phase enforces quality gates:
| Score | Status | Behavior |
|---|---|---|
| >= 90% | PASSED | Proceed to ink |
| 75-89% | WARNING | Proceed with caution |
| < 75% | FAILED | Ink phase flags for review |
| Command | Phase | Description |
|---|---|---|
probe <prompt> | Discover | Parallel research with AI synthesis |
grasp <prompt> | Define | Consensus building on problem definition |
tangle <prompt> | Develop | Enhanced map-reduce with quality gates |
ink <prompt> | Deliver | Validation and final delivery |
embrace <prompt> | All 4 | Full Double Diamond workflow |
preflight | - | Validate all dependencies |
| Command | Description |
|---|---|
grapple <prompt> | Codex vs Gemini debate until consensus |
grapple --principles TYPE <prompt> | Debate with domain principles (security, performance, maintainability) |
squeeze <prompt> | Red Team security review (Blue Team vs Red Team) |
| Command | Description |
|---|---|
init | Initialize workspace |
spawn <agent> <prompt> | Spawn single agent |
auto <prompt> | Smart routing (Double Diamond or agent) |
fan-out <prompt> | Send to multiple agents |
map-reduce <prompt> | Decompose and parallelize |
parallel [tasks.json] | Execute task file |
status | Show running agents |
kill [id|all] | Terminate agents |
clean | Reset workspace |
aggregate [filter] | Combine results |
| Option | Default | Description |
|---|---|---|
-p, --parallel | 3 | Max concurrent agents |
-t, --timeout | 300 | Timeout per task (seconds) |
-v, --verbose | false | Verbose logging |
-n, --dry-run | false | Show without executing |
--context <file> | - | Context from previous phase |
| Agent | Model | Best For |
|---|---|---|
codex | gpt-5.3-codex | Complex code, deep refactoring (premium default) |
codex-standard | gpt-5.2-codex | Standard tier implementation |
codex-mini | gpt-5.4-mini | Quick fixes, simple tasks |
gemini | gemini-3-pro-preview | Deep analysis, 1M context |
gemini-fast | gemini-3-flash-preview | Speed-critical tasks |
gemini-image | gemini-3-pro-image-preview | Image generation |
codex-review | gpt-5.2-codex | Code review mode |
openrouter | Various | Universal fallback (400+ models) |
Claude Octopus now intelligently routes tasks based on your subscription tiers and costs.
| Provider | Tiers | Monthly Cost | Capabilities |
|---|---|---|---|
| Codex/OpenAI | Free, Plus, Pro, API | $0-200 | code, chat, review |
| Gemini | Free, Google One, Workspace, API | $0-20 or bundled | code, chat, vision, long-context (2M) |
| Claude | Pro, Max 5x, Max 20x, API | $20-200 | code, chat, analysis, long-context |
| OpenRouter | Pay-per-use | Variable | 400+ models, routing variants |
| Strategy | Description |
|---|---|
balanced (default) | Smart mix of cost and quality |
cost-first | Prefer cheapest capable provider |
quality-first | Prefer highest-tier provider |
Example: If you have Google Workspace (bundled Gemini Pro), the system prefers Gemini for heavy analysis tasks since it's "free" with your work account.
# Force a specific provider
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --provider gemini auto "analyze code structure"
# Prefer cheapest option
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --cost-first auto "research best practices"
# Prefer highest quality
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --quality-first auto "complex refactoring task"
# OpenRouter routing variants
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --openrouter-nitro auto "quick task" # Fastest
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh --openrouter-floor auto "bulk task" # Cheapest
Provider tiers are configured during setup or via the providers config file:
# Run setup wizard (includes provider tier steps)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh setup
# View current provider status
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh status
Configuration file: ~/.claude-octopus/.providers-config
version: "2.0"
providers:
codex:
installed: true
auth_method: "oauth"
subscription_tier: "plus" # free|plus|pro|api-only
cost_tier: "low" # free|low|medium|high|bundled|pay-per-use
gemini:
installed: true
auth_method: "oauth"
subscription_tier: "workspace" # free|google-one|workspace|api-only
cost_tier: "bundled"
openrouter:
enabled: false
routing_preference: "default" # default|nitro|floor
cost_optimization:
strategy: "balanced" # cost-first|quality-first|balanced
OpenRouter provides 400+ models as a universal fallback when Codex/Gemini are unavailable:
# Set up OpenRouter API key
export OPENROUTER_API_KEY="sk-or-..."
# Re-run setup to configure
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh setup
~/.claude-octopus/
โโโ results/
โ โโโ probe-synthesis-*.md # Research findings
โ โโโ grasp-consensus-*.md # Problem definitions
โ โโโ tangle-validation-*.md # Quality gate reports
โ โโโ delivery-*.md # Final deliverables
โโโ logs/ # Execution logs
โโโ plans/ # Execution plan history
โโโ .gitignore
# 1. Explore the problem space
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "Authentication patterns for microservices"
# 2. Define the approach (with probe context)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh grasp "OAuth2 with JWT for our API" \
--context ~/.claude-octopus/results/probe-synthesis-*.md
# 3. Implement with validation
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Implement OAuth2 authentication"
# 4. Deliver with quality checks
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Finalize auth implementation"
# Auto-detects "build" intent -> runs tangle + ink
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh auto "build a rate limiting middleware"
# All 4 phases in one command
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Create a user notification system with email and push support"
embrace for new features requiring explorationprobe alone when researching before committing to an approachauto for smart routing based on your intent--context for incremental workflowspreflight before long workflows to verify dependencies${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh preflight
# Verify: codex CLI, gemini CLI, OPENAI_API_KEY, GOOGLE_API_KEY
Tangle phase requires 75% success rate. If failing:
-t 600~/.claude-octopus/logs/${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh clean
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh init