Installation

Complete guide to installing and configuring Claude Octopus for Claude Code.

Prerequisites

Required

Claude Code v2.1.50 or later — Check your version in the about menu
Git — Used by the plugin marketplace to fetch plugins
Bash shell — For orchestration scripts (default on macOS/Linux, WSL on Windows)

Claude Code version requirement: Claude Octopus requires v2.1.50 or newer. Earlier versions lack critical plugin APIs for multi-AI orchestration.

Optional (for multi-AI features)

Codex CLI — For OpenAI integration
Gemini CLI — For Google integration
Node.js 18+ — Required only if using the OpenClaw MCP server

You can start using Claude Octopus immediately with just Claude built-in. External providers are optional and only needed for multi-AI orchestration features (parallel research, adversarial debate, consensus validation).

Installation methods

Method 1: Plugin marketplace (recommended)

The plugin marketplace method is the recommended approach:

Add the marketplace repository

In Claude Code, run:

/plugin marketplace add https://github.com/nyldn/claude-octopus.git

This registers the Claude Octopus repository as a plugin source.

Install the plugin

/plugin install claude-octopus@nyldn-plugins

Installation scope:

Default: User-scoped (--scope user) — available across all projects
Alternative: Project-scoped (--scope project) — only available in current project

Enable the plugin

The plugin should enable automatically, but you can verify:

/plugin enable claude-octopus

Restart Claude Code

Fully quit and reopen Claude Code:

macOS: Cmd+Q, then reopen
Windows/Linux: Complete exit, then relaunch

A simple window close may not be sufficient. Ensure Claude Code fully terminates.

Method 2: Terminal installation

Alternatively, install from your terminal:

# Add marketplace
claude -p "/plugin marketplace add https://github.com/nyldn/claude-octopus.git"

# Install plugin
claude -p "/plugin install claude-octopus@nyldn-plugins"

# Fully restart Claude Code

Method 3: Manual installation (advanced)

For development or custom modifications:

# Clone the repository
git clone https://github.com/nyldn/claude-octopus.git
cd claude-octopus

# Run install script
./install.sh

The install script uses the Claude Code plugin manager internally and is equivalent to Method 1.

Verification

Verify plugin is installed

claude plugin list | grep claude-octopus

Expected output:

claude-octopus@nyldn-plugins (enabled)

Test a command

Try running setup:

/octo:setup

You should see provider detection output.

Run diagnostics

Run the comprehensive diagnostic tool:

/octo:doctor

This checks 9 categories: providers, auth, config, state, smoke tests, hooks, scheduler, skills, and conflicts.

Provider setup

Claude Octopus works with three AI providers. Claude is built-in. Codex and Gemini are optional.

Claude (built-in)

✅ No setup required — Claude is included with Claude Code and works immediately. Cost: Included in your Claude Code subscription (Sonnet 4.6). Opus 4.6 uses per-token billing at

5/

25 per MTok.

Codex (OpenAI)

Codex provides implementation depth — code patterns, technical analysis, and architecture.

OAuth (recommended)
API key

OAuth authentication is included in your ChatGPT subscription:

# Install Codex CLI (if not already installed)
npm install -g @openai/codex-cli

# Authenticate
codex login

Benefits:

No separate billing — included in ChatGPT subscription
Automatic token refresh
More secure than API keys

For per-token billing without a subscription:

# Set environment variable
export OPENAI_API_KEY=sk-...

# Or add to shell profile (~/.zshrc or ~/.bashrc)
echo 'export OPENAI_API_KEY=sk-...' >> ~/.zshrc
source ~/.zshrc

Cost: ~$0.01-0.15 per query depending on model:

GPT-5.3-Codex: $1.75/$ 14 per MTok
Spark: 15x faster
Mini: ~ $0.30/$ 1.25 per MTok

Gemini (Google)

Gemini provides ecosystem breadth — alternatives, security review, and research synthesis.

OAuth (recommended)
API key

OAuth authentication is included in your Google AI subscription:

# Install Gemini CLI (if not already installed)
npm install -g @google/gemini-cli

# Authenticate
gemini login

Benefits:

Included in Google AI subscription
Automatic credential management

For per-token billing:

# Set environment variable
export GEMINI_API_KEY=...

# Or add to shell profile
echo 'export GEMINI_API_KEY=...' >> ~/.zshrc
source ~/.zshrc

Cost: ~$0.01-0.03 per query (Gemini Pro)

Verify provider configuration

After configuring providers, run setup to verify:

/octo:setup

Expected output with all providers:

Claude Octopus Setup Status

Providers:
  Claude: ✓ Built-in
  Codex CLI: ✓ Authenticated via OAuth
  Gemini CLI: ✓ Authenticated via API key

You're all set! Multi-AI features are enabled.

Try: /octo:embrace build a user authentication system

Configuration

Project-specific settings

Claude Octopus stores project state in .octo/ directory:

project-root/
├── .octo/
│   ├── STATE.md           # Current phase and progress
│   ├── LESSONS.md         # Captured insights
│   └── checkpoints/       # Rollback points

This directory is automatically created on first use.

Global settings

User-level configuration lives in ~/.claude-octopus/:

~/.claude-octopus/
├── results/               # Workflow outputs
├── logs/                  # Execution logs
└── config/                # User preferences

Autonomy modes

Configure how much human oversight workflows require:

Mode	Behavior	When to use
Supervised (default)	Pause after each phase for approval	Learning the tool, high-stakes projects
Semi-autonomous	Only prompt if quality gates fail	Trusted workflows, moderate oversight
Autonomous	Run all phases without intervention	Repeated patterns, full automation

Set during workflow execution:

/octo:embrace build feature  # Will prompt for autonomy preference

Or configure via orchestrate.sh:

${CLAUDE_PLUGIN_ROOT}/scripts/orchestrate.sh embrace --autonomy autonomous "your prompt"

Troubleshooting

Commands not recognized

Plugin not loading after installation

Symptoms: /octo:* commands show “unknown command” errorSolutions:

Verify installation: claude plugin list | grep claude-octopus
Check plugin is enabled: /plugin enable claude-octopus
Fully restart Claude Code (Cmd+Q on macOS, not just close window)
Check debug logs: ~/.claude/debug/*.txt

Try reinstalling:

/plugin uninstall claude-octopus@nyldn-plugins
/plugin install claude-octopus@nyldn-plugins

Scope errors during uninstall

Symptoms: “Plugin not found” when trying to uninstallSolution: Match the scope used during installation:

# If installed user-scoped (default)
/plugin uninstall claude-octopus@nyldn-plugins --scope user

# If installed project-scoped
/plugin uninstall claude-octopus@nyldn-plugins --scope project

Provider issues

Codex CLI not detected

Symptoms: Setup shows Codex as unavailableSolutions:

Check CLI is installed: which codex

Verify authentication:

codex --version
codex whoami  # Check logged-in user

Re-authenticate:
```
codex logout
codex login
```
Check PATH includes npm global bin directory

Gemini CLI not detected

Symptoms: Setup shows Gemini as unavailableSolutions:

Check CLI is installed: which gemini
Verify API key is set:
```
echo $GEMINI_API_KEY
```
Test authentication:
```
gemini --version
```

Provider timeouts during workflows

Symptoms: Workflows fail with timeout errorsSolutions:

Check network connectivity
Verify API keys are valid (not expired)
Check rate limits on provider accounts

Try running with single provider first:

/octo:discover <query>  # Uses only Claude by default

Workflow issues

Results not appearing in expected location

Symptoms: Workflow completes but files aren’t foundCheck these locations:

# Global results
ls -la ~/.claude-octopus/results/

# Project state
ls -la .octo/

# Recent results
ls -lt ~/.claude-octopus/results/ | head -10

Quality gates failing unexpectedly

Symptoms: Workflows blocked at 75% consensus gateUnderstanding quality gates:

75% threshold means 2 out of 3 providers must agree
Failures indicate genuine disagreement worth investigating
Review synthesis files to see divergent perspectives

Solutions:

Review the synthesis: ~/.claude-octopus/results/*-synthesis-*.md
Provide more context in your prompt

Run phases individually to isolate issues:

/octo:discover <topic>  # Research first
/octo:define <scope>    # Then clarify

Environment diagnostics

Use the built-in doctor command for comprehensive checks:

# Run all diagnostics
/octo:doctor

# Check specific category
/octo:doctor providers
/octo:doctor auth --verbose

# Machine-readable output
/octo:doctor --json

Doctor checks 9 categories:

Category	What it checks
`providers`	Claude Code version, Codex CLI, Gemini CLI installation
`auth`	Authentication status for each provider
`config`	Plugin version, install scope, feature flags
`state`	Project state.json, stale results, workspace writability
`smoke`	Smoke test cache, model configuration
`hooks`	hooks.json validity, hook scripts
`scheduler`	Scheduler daemon, jobs, budget gates
`skills`	Skill files loaded and valid
`conflicts`	Detection of conflicting plugins

Update and maintenance

Updating Claude Octopus

# Update from marketplace
/plugin update claude-octopus

# Or via terminal
claude -p "/plugin update claude-octopus"

Checking version

View current version:

/plugin list | grep claude-octopus

Or check the plugin.json:

cat ~/.claude/plugins/claude-octopus@nyldn-plugins/.claude-plugin/plugin.json | grep version

Clean uninstall

Remove plugin and all data:

# Uninstall plugin
/plugin uninstall claude-octopus@nyldn-plugins

# Remove global data (optional)
rm -rf ~/.claude-octopus/

# Remove project state (optional, per-project)
rm -rf .octo/

Removing ~/.claude-octopus/ deletes all workflow results and logs. Consider backing up first.

What’s next?

Quickstart

Run your first workflow in under 5 minutes

Command Reference

Explore all 46 commands

Double Diamond

Learn the four-phase workflow methodology

Personas

Discover the 33 specialized AI agents

Get Started

Core Concepts

Guides

Installation

Installation

Prerequisites

Required

Optional (for multi-AI features)

Installation methods

Method 1: Plugin marketplace (recommended)

Method 2: Terminal installation

Method 3: Manual installation (advanced)

Verification

Provider setup

Claude (built-in)

Codex (OpenAI)

Gemini (Google)

Verify provider configuration

Configuration

Project-specific settings

Global settings

Autonomy modes

Troubleshooting

Commands not recognized

Provider issues

Workflow issues

Environment diagnostics

Update and maintenance

Updating Claude Octopus

Checking version

Clean uninstall

What’s next?

Quickstart

Command Reference

Double Diamond

Personas

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Installation

​Prerequisites

​Required

​Optional (for multi-AI features)

​Installation methods

​Method 1: Plugin marketplace (recommended)

​Method 2: Terminal installation

​Method 3: Manual installation (advanced)

​Verification

​Provider setup

​Claude (built-in)

​Codex (OpenAI)

​Gemini (Google)

​Verify provider configuration

​Configuration

​Project-specific settings

​Global settings

​Autonomy modes

​Troubleshooting

​Commands not recognized

​Provider issues

​Workflow issues

​Environment diagnostics

​Update and maintenance

​Updating Claude Octopus

​Checking version

​Clean uninstall

​What’s next?

Quickstart

Command Reference

Double Diamond

Personas

Build docs developers (and LLMs) love

Installation

Prerequisites

Required

Optional (for multi-AI features)

Installation methods

Method 1: Plugin marketplace (recommended)

Method 2: Terminal installation

Method 3: Manual installation (advanced)

Verification

Provider setup

Claude (built-in)

Codex (OpenAI)

Gemini (Google)

Verify provider configuration

Configuration

Project-specific settings

Global settings

Autonomy modes

Troubleshooting

Commands not recognized

Provider issues

Workflow issues

Environment diagnostics

Update and maintenance

Updating Claude Octopus

Checking version

Clean uninstall

What’s next?