System Commands

Setup, configuration, diagnostics, and environment management

System Commands

System commands help you configure providers, diagnose issues, manage project state, and switch between work modes.

---

/octo:setup - Provider Configuration

Check setup status and get configuration instructions for AI providers.

Syntax

/octo:setup
/octo:sys-setup    # Full version with detailed docs

What It Checks

• Codex CLI installation and authentication
• Gemini CLI installation and authentication
• Perplexity API key configuration (optional)
• Environment variables and shell configuration
• Node.js and npm availability

Output Example

Claude Octopus Setup Status:

🔴 Codex CLI:
   Status: Installed ✓
   Auth: OAuth configured ✓
   
🟡 Gemini CLI:
   Status: Not installed ✗
   Action: Run `npm install -g @google/gemini-cli`
   
🟣 Perplexity:
   Status: Not configured (optional)
   Info: Adds web search to research workflows

Provider Setup

Codex CLI (OpenAI)

Installation:

npm install -g @openai/codex

Authentication (Option 1 - OAuth):

codex login

Authentication (Option 2 - API Key):

export OPENAI_API_KEY="sk-..."
# Add to ~/.zshrc or ~/.bashrc for persistence
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc

Get API key from: https://platform.openai.com/api-keys

Gemini CLI (Google)

Installation:

npm install -g @google/gemini-cli

Authentication (Option 1 - OAuth):

gemini    # Opens browser for OAuth

Authentication (Option 2 - API Key):

export GEMINI_API_KEY="AIza..."
# Add to ~/.zshrc or ~/.bashrc for persistence
echo 'export GEMINI_API_KEY="AIza..."' >> ~/.zshrc

Get API key from: https://aistudio.google.com/app/apikey

Perplexity (Optional)

Purpose: Adds live web search with citations to research workflows

Configuration:

export PERPLEXITY_API_KEY="pplx-..."
# Add to ~/.zshrc or ~/.bashrc for persistence
echo 'export PERPLEXITY_API_KEY="pplx-..."' >> ~/.zshrc

Get API key from: https://www.perplexity.ai/settings/api

Perplexity is fully optional. All workflows work without it.

Do I Need Both Providers?

No! You only need ONE provider (Codex or Gemini) to use Claude Octopus.

Provider Strengths:

• Codex (OpenAI): Best for code generation, refactoring, complex logic
• Gemini (Google): Best for analysis, long-context understanding, multi-modal tasks
• Perplexity: Adds live web search to ground research in current data

Having both enables multi-AI workflows where different models review each other’s work, but a single provider works great for most tasks.

Verification

After setup, verify with:

${CLAUDE_PLUGIN_ROOT}/scripts/orchestrate.sh detect-providers

You should see:

• ✓ Codex: Installed and authenticated (oauth or api-key)
• ✓ Gemini: Installed and authenticated (oauth or api-key)
• ✓ Perplexity: Configured (api-key) — optional

Troubleshooting

npm: command not found

You need Node.js and npm installed.

Install from: https://nodejs.org/

Permission denied when installing CLIs

Use sudo npm install -g or configure npm for user directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

codex/gemini: command not found after installation

The CLI may not be in your PATH. Try:

# Reload shell profile
source ~/.zshrc  # or source ~/.bashrc

# Or restart terminal

API key not persisting after terminal restart

Add the export statement to your shell profile:

# For zsh (macOS default)
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
echo 'export GEMINI_API_KEY="AIza..."' >> ~/.zshrc
source ~/.zshrc

# For bash
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc
echo 'export GEMINI_API_KEY="AIza..."' >> ~/.bashrc
source ~/.bashrc

---

/octo:doctor - Environment Diagnostics

Comprehensive health check for Claude Octopus environment.

Syntax

/octo:doctor

What It Checks

Provider Health

• Codex CLI availability and authentication
• Gemini CLI availability and authentication
• Perplexity API configuration
• Model access and API quotas

Configuration

• Plugin installation and version
• Environment variables
• File permissions and paths
• Hook registration status

System Components

• Scheduler service status
• orchestrate.sh script availability
• Result file directory access
• Session state management

Output Example

🐙 Claude Octopus Health Check

Providers:
  ✓ Codex CLI - Installed, authenticated (oauth)
  ✓ Gemini CLI - Installed, authenticated (api-key)
  ✓ Perplexity - Configured
  ✓ Claude - Active session

Configuration:
  ✓ Plugin installed (v8.25.0)
  ✓ CLAUDE_PLUGIN_ROOT set
  ✓ orchestrate.sh executable
  ✓ Results directory writable

Scheduler:
  ✓ Scheduler service running
  ✓ No pending jobs

Hooks:
  ✓ Pre-session hook registered
  ✓ Auto-activation enabled

✅ All systems operational

When to Use

• After initial installation
• When commands aren’t working as expected
• Before running complex workflows
• After environment changes (new shell, updated keys)
• When debugging provider issues

Natural Language

Just say:

• “Run doctor”
• “Check my setup”
• “Is everything working?”
• “Why isn’t octopus working?”

---

/octo:status - Project State

Show current Claude Octopus workflow and provider status.

Syntax

/octo:status

What It Shows

• Current work mode (Dev/Knowledge)
• Provider readiness and availability
• Active workflow phase (if any)
• Available result files from recent runs
• Recommended next command

Output Example

🐙 Claude Octopus Status

Mode: Dev Work Mode 🔧
  Active personas: backend-architect, code-reviewer, debugger

Providers:
  🔴 Codex: Ready
  🟡 Gemini: Ready
  🔵 Claude: Active

Recent Results:
  - discover-synthesis (2 min ago)
  - define-consensus (5 min ago)
  
Next: Run /octo:develop to begin implementation

When to Use

• Check current workflow state
• Verify provider availability before starting
• Find result files from previous phases
• Understand where you are in a workflow

---

/octo:resume - Restore Context

Resume work from the last known Claude Octopus session.

Syntax

/octo:resume

What It Does

• Restores context from persisted Octopus state
• Shows completed phases and current position
• Identifies open blockers or issues
• Suggests immediate next action

Output Example

🐙 Resuming Claude Octopus Session

Project: User Authentication Feature
Last active: 2 hours ago

Completed:
  ✓ Discover - OAuth research complete
  ✓ Define - Requirements scoped
  
Current Phase: Develop
  Status: 60% complete
  Blocker: Need to resolve JWT signing algorithm
  
Next Action: Continue with /octo:develop

When to Use

• Starting a new terminal session
• After a break in work
• When you’ve lost context
• To check what’s left to do

If no state exists, resume will explain there’s nothing to restore and suggest starting with /octo:embrace or /octo:discover.

---

/octo:dev - Dev Work Mode

Switch to Dev Work Mode - optimized for software development.

Syntax

/octo:dev

What It Does

• Activates development-focused AI personas
• Optimizes workflows for code, architecture, debugging
• Sets default mode for technical tasks
• Persists across sessions

Dev Mode Personas

• backend-architect - System design and architecture
• code-reviewer - Code quality and best practices
• debugger - Problem diagnosis and fixes
• test-automator - Testing and quality assurance
• performance-engineer - Optimization and scalability

Best For

• Building features and implementing APIs
• Debugging code and fixing bugs
• Technical architecture decisions
• Code review and refactoring
• Test-driven development

Output Example

🔧 Switched to Dev Work Mode

Active Personas:
  - backend-architect
  - code-reviewer
  - debugger
  - test-automator
  - performance-engineer

Providers: Codex + Gemini + Claude

Ready for: octo build, octo develop, octo review, octo tdd

---

/octo:km - Knowledge Work Mode

Switch to Knowledge Work Mode - optimized for research and analysis.

Syntax

/octo:km [on|off]
/octo:km         # Switch to Knowledge mode
/octo:km on      # Switch to Knowledge mode (explicit)
/octo:km off     # Switch to Dev mode

What It Does

• Activates research-focused AI personas
• Optimizes workflows for user research, strategy, literature reviews
• Persists across sessions
• Can be toggled on/off

Knowledge Mode Personas

• ux-researcher - User research and insights
• strategy-analyst - Strategic planning and analysis
• research-synthesizer - Literature review and synthesis
• data-analyst - Quantitative analysis
• market-researcher - Competitive analysis

Best For

• User research and interviews
• Strategy analysis and planning
• Literature reviews and synthesis
• Market research and competitive analysis
• Document analysis and summarization

Output Example

🎓 Switched to Knowledge Work Mode

Active Personas:
  - ux-researcher
  - strategy-analyst
  - research-synthesizer
  - data-analyst
  - market-researcher

Providers: Gemini + Claude (research-optimized)

Ready for: octo research, octo discover, document analysis

Recommended: Install document-skills plugin
  /plugin install document-skills@anthropic-agent-skills

Toggling Modes

/octo:km on      # Enable Knowledge mode
/octo:km off     # Disable (switch to Dev mode)
/octo:dev        # Alternative way to switch to Dev mode

---

Work Mode Comparison

Feature	Dev Work Mode 🔧	Knowledge Work Mode 🎓
Primary Use	Code, implementation	Research, analysis
Personas	backend-architect, code-reviewer, debugger	ux-researcher, strategy-analyst, synthesizer
Providers	Codex + Gemini + Claude	Gemini + Claude (research-optimized)
Commands	develop, review, tdd, security	discover, research, analyze
Switch To	/octo:dev	/octo:km on

Both modes use the same AI providers but with different personas and optimizations for the task type.

---

Configuration Files

Claude Octopus uses these configuration files:

.claude/claude-octopus.local.md

Local configuration for work mode and preferences

---
knowledge_mode: false  # true for Knowledge mode, false for Dev mode
---

.claude/session-intent.md

Intent contract from planning phase (created by /octo:plan)

Captures:

• User goal and success criteria
• Constraints and boundaries
• Knowledge level and scope clarity

.claude/session-plan.md

Execution plan with phase weights (created by /octo:plan)

Contains:

• Phase weights (Discover/Define/Develop/Deliver)
• Deliverable description
• Execution commands

---

Environment Variables

Provider Authentication

export OPENAI_API_KEY="sk-..."           # Codex authentication
export GEMINI_API_KEY="AIza..."          # Gemini authentication
export PERPLEXITY_API_KEY="pplx-..."     # Perplexity authentication (optional)

Model Configuration

export OCTOPUS_CODEX_MODEL="gpt-4"       # Override Codex model
export OCTOPUS_GEMINI_MODEL="gemini-pro" # Override Gemini model
export OCTOPUS_OPUS_MODE="fast"          # Use fast Opus (6x cost, lower latency)

Provider Control

export CODEX_SKIP=true                    # Disable Codex provider
export GEMINI_SKIP=true                   # Disable Gemini provider

Workflow Control

export OCTOPUS_AUTONOMY="autonomous"     # Set default autonomy mode

---

Next Steps

Workflow Commands

Learn the Double Diamond phases

Skill Commands

Explore specialized capabilities