Skip to main content

​
Using commands effectively

Claude Octopus provides 39+ commands in the /octo:* namespace. This guide covers the most powerful commands, the smart router for natural language workflows, and techniques for command composition.

​
Command structure

All Claude Octopus commands use the /octo: namespace to avoid conflicts with Claude Code’s built-in commands.

​
Basic syntax

/octo:<command> <arguments>
Examples: 
/octo:setup                          # Check provider status
/octo:discover OAuth patterns        # Research workflow
/octo:debate Redis vs Memcached      # AI debate
/octo:embrace build authentication   # Full 4-phase workflow

​
Why the namespace?

Namespace isolation ensures your existing Claude Code setup remains untouched. Only /octo:* commands activate the plugin—everything else works exactly as before.
The /octo: prefix is required for slash commands, but you can skip it when using the smart router: just type octo research X instead of /octo:discover X.

​
Top 8 commands

Eight essential commands—one per tentacle. Each orchestrates up to three AI providers and applies quality gates.

​
1. /octo:embrace

Full lifecycle workflow: discover → define → develop → deliver 
/octo:embrace build stripe integration
What it does:
  • Runs all 4 phases of the Double Diamond methodology
  • Multi-provider research, consensus building, implementation, and validation
  • Quality gates between phases prevent sloppy work from advancing
When to use:
  • Complex features requiring research through implementation
  • High-stakes projects needing validation
  • When you want multiple AI perspectives across the entire lifecycle
Autonomy modes:
  • Supervised (default): Review and approve after each phase
  • Semi-autonomous: Only intervene if quality gates fail
  • Autonomous: Run all 4 phases automatically
See Working with workflows for details on workflow progression.

​
2. /octo:factory

Dark Factory mode—autonomous spec-to-software pipeline 
/octo:factory "build a CLI that converts CSV to JSON"
What it does:
  • Takes a spec and autonomously runs the full pipeline
  • Generates test scenarios, implements via embrace workflow
  • Holdout testing (80/20 split) validates against blind scenarios
  • Satisfaction scoring across 4 dimensions
7-phase pipeline:
  1. Parse spec → validate and extract requirements
  2. Generate scenarios → multi-provider scenario creation
  3. Split holdout → 80/20 split ensuring diverse coverage
  4. Embrace workflow → full 4-phase implementation
  5. Holdout tests → blind evaluation against withheld scenarios
  6. Score satisfaction → weighted scoring across dimensions
  7. Report → verdict (PASS/WARN/FAIL) with composite score
Cost: ~$0.50-2.00 per run (20-30 agent calls)
Factory mode is fully autonomous. Review the spec carefully before running—you’ll see the output, not every step.

​
3. /octo:debate

Structured three-way AI debate with consensus scoring 
/octo:debate monorepo vs microservices
/octo:debate -r 3 Should we use GraphQL or REST?
/octo:debate -d adversarial Review auth.ts security
Participants:
  • 🔴 Codex CLI: Technical perspective
  • 🟡 Gemini CLI: Ecosystem perspective
  • 🔵 Claude: Moderator and synthesis
Options:
  • -r N, --rounds N: Number of debate rounds (default: 2)
  • -d STYLE, --debate-style STYLE: quick, thorough, adversarial, collaborative
Output:
  • Synthesis with recommendations
  • Consensus score (percentage agreement)
  • Areas of disagreement highlighted

​
4. /octo:research

Deep multi-source research with synthesis 
/octo:research htmx vs react in 2026
What it does:
  • Parallel research using Codex CLI + Gemini CLI + Claude
  • Multi-source synthesis from three AI perspectives
  • Technical implementation analysis (Codex)
  • Ecosystem breadth and alternatives (Gemini)
  • Strategic synthesis (Claude)
Visual indicator: 🐙 🔍 Alias: /octo:discover

​
5. /octo:review

Code review with security + 4x10 scoring 
/octo:review src/auth.ts
/octo:review src/components/
What it does:
  • Comprehensive code quality analysis
  • Security vulnerability detection (OWASP)
  • Architecture review
  • Best practices enforcement
  • 4-dimension scoring: correctness, security, performance, maintainability
Multi-perspective review:
  • 🔴 Codex: Code quality analysis
  • 🟡 Gemini: Security and edge cases
  • 🔵 Claude: Synthesis and recommendations

​
6. /octo:tdd

Test-driven development with red-green-refactor 
/octo:tdd create user auth
What it does:
  • Red: Write failing test first
  • Green: Minimal code to pass
  • Refactor: Improve while keeping tests green
Enforces test discipline:
  • Tests written before implementation
  • Incremental feature development
  • Continuous validation

​
7. /octo:security

OWASP vulnerability scan + remediation 
/octo:security src/api/
What it does:
  • OWASP Top 10 vulnerability scanning
  • Authentication and authorization review
  • Input validation checks
  • Red team analysis (adversarial testing)
Security-first review:
  • SQL injection detection
  • XSS vulnerability scanning
  • Authentication bypass checks
  • Sensitive data exposure analysis

​
8. /octo:prd

AI-optimized PRD with 100-point scoring 
/octo:prd mobile checkout redesign
What it does:
  • Generates product requirements document
  • 100-point scoring across dimensions
  • Stakeholder analysis
  • Success metrics definition

​
Smart router

The smart router (/octo) maps natural language to commands automatically—no need to memorize command names.

​
How it works

/octo <describe what you want>
The router analyzes your request using keyword matching and confidence scoring, then routes to the optimal workflow.

​
Routing intelligence

Keywords: research, investigate, explore, learn, study, understand, analyzeRoutes to: /octo:discoverConfidence threshold: 70%Example:
/octo research OAuth authentication patterns
# → Routes to /octo:discover
# 🔍 Multi-AI research and exploration

​
Confidence levels

>80% confidence: Auto-routes with notification 
✓ Routing to Research workflow (/octo:discover)
70-80% confidence: Shows suggestion and asks for confirmation 
I think you want: Implementation workflow (/octo:develop)
Should I proceed with this workflow? (yes/no)
Less than 70% confidence: Asks user to clarify intent 
I'm not sure which workflow fits best. Here are your options:
1. Research - Multi-AI research and exploration
2. Build - Implementation with quality gates
3. Validate - Quality assurance and review
...

​
Natural language examples

/octo research OAuth security patterns
# High confidence (95%)
# → /octo:discover

​
Command chaining and composition

While Claude Octopus doesn’t support explicit command chaining syntax, you can compose workflows through the smart router or by running commands sequentially.

​
Sequential workflows

Run phases individually for more control:
1

Discover

Research the problem space
/octo:discover OAuth authentication patterns
Review the synthesis document, then proceed to define.
2

Define

Clarify requirements and scope
/octo:define requirements for OAuth implementation
Build consensus on approach before implementing.
3

Develop

Implement with quality gates
/octo:develop OAuth authentication system
Implementation validated against 75% consensus threshold.
4

Deliver

Final validation and review
/octo:deliver OAuth implementation
Multi-AI validation produces go/no-go recommendation.

​
Suggested chaining

The smart router can suggest workflow chains: 
/octo build and validate authentication system
# Router suggests: /octo:develop → /octo:review

​
Workflow combinations

Research → Debate → Build: 
# 1. Research options
/octo research session storage solutions

# 2. Debate top candidates
/octo debate Redis vs Memcached

# 3. Implement winner
/octo develop Redis session store
Build → Review → Security: 
# 1. Implement feature
/octo develop user authentication

# 2. Code review
/octo review src/auth/

# 3. Security audit
/octo security src/auth/

​
Best practices

When you’re not sure which workflow fits, let the router analyze your intent:
/octo I need to improve our API performance
The router will suggest appropriate workflows based on keywords and context.
For high-stakes features, run phases individually instead of using embrace:
  • Review research synthesis before defining requirements
  • Review consensus before implementing
  • Intervene if quality gates fail
This gives you maximum control and oversight.
When you have a clear spec, factory mode automates the entire pipeline:
/octo:factory --spec ./specs/api-redesign.md
Holdout testing ensures the implementation satisfies blind scenarios.
Before implementing major features, use debate to explore trade-offs:
/octo debate monorepo vs microservices for our platform
Three AI perspectives reduce blind spots in decision-making.
Run setup to verify provider availability:
/octo:setup
Multi-AI workflows work best with all three providers configured.

​
Next steps

Working with workflows

Learn about workflow progression, quality gates, and choosing the right workflow

Command reference

Complete reference for all 39+ commands

Configuring providers

Set up Codex, Gemini, and cost-aware provider selection

Configuration

Environment variables, autonomy modes, and custom hooks

Build docs developers (and LLMs) love

Get started for freeTalk to us