Skip to main content
This page covers the most common issues users encounter with Claude Octopus and their solutions.

​
Installation problems

Symptom: /plugin install claude-octopus@nyldn-plugins fails with errorCommon causes:
  1. Wrong scope: Add --scope project if you see “scope not found” 
    /plugin install claude-octopus@nyldn-plugins --scope project
  2. Marketplace not added: Add the marketplace first 
    /plugin marketplace add https://github.com/nyldn/claude-octopus.git
/plugin install claude-octopus@nyldn-plugins
  3. Git not installed: Install git and retry 
    # macOS
brew install git

# Ubuntu/Debian
sudo apt install git
  4. Network issues: Check internet connection and retry
Symptom: /octo:setup returns “command not found”Cause: Plugin not installed or not activatedSolution:
# List installed plugins
/plugin list

# If not listed, install
/plugin install claude-octopus@nyldn-plugins

# If listed but not active, activate
/plugin activate claude-octopus
Symptom: bash: ./scripts/orchestrate.sh: Permission deniedCause: Scripts not executableSolution:
# Fix all scripts
cd ~/.claude/plugins/nyldn-plugins/claude-octopus
chmod +x scripts/*.sh
chmod +x scripts/lib/*.sh
chmod +x hooks/*.sh
Symptom: MCP server fails with “Node.js version not supported”Cause: Requires Node.js ≥18Solution:
# Check version
node --version

# Install Node.js 18+ with nvm
nvm install 18
nvm use 18

# Or with Homebrew (macOS)
brew install node@18

​
Provider authentication failures

Symptom: ERROR: Codex CLI not foundCause: Codex CLI not installedSolution:
# Install Codex CLI
npm install -g @anthropic/codex-cli

# Verify installation
which codex

# Authenticate
codex login  # OAuth (recommended)
# OR
export OPENAI_API_KEY=sk-...  # API key
Symptom: ERROR: Gemini CLI not foundCause: Gemini CLI not installedSolution:
# Install Gemini CLI
npm install -g @google/gemini-cli

# Verify installation
which gemini

# Authenticate
gemini login  # OAuth (recommended)
# OR
export GEMINI_API_KEY=...  # API key
Symptom: ERROR: OPENAI_API_KEY not set or ERROR: GEMINI_API_KEY not setCause: Environment variable not configuredSolution:
# Temporary (current session)
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...

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

# Verify
echo $OPENAI_API_KEY
Prefer OAuth authentication (codex login, gemini login) over API keys for better security.
Symptom: ERROR: Authentication expiredCause: OAuth token expiredSolution:
# Re-authenticate
codex login
gemini login

# Verify
codex auth status
gemini auth status
Symptom: ERROR: Insufficient permissionsCause: API key lacks required scopesSolution:
  • OpenAI: Ensure key has “Model capabilities” enabled
  • Google AI: Ensure key has “Gemini API” enabled
  • Regenerate key with correct permissions in provider console

​
Command not found errors

Symptom: Claude Code doesn’t recognize /octo:embrace, /octo:review, etc.Cause: Plugin not active or skills not loadedSolution:
# Check plugin status
/plugin list

# Reload plugin
/plugin reload claude-octopus

# Re-run setup
/octo:setup
Symptom: octo research topic doesn’t route to /octo:discoverCause: Smart router not recognizing intentSolution:
  • Use explicit command: /octo:discover topic
  • Add more context: octo research OAuth patterns in depth
  • Check router config: cat ~/.claude-octopus/config/router.json
Symptom: ERROR: Persona 'typescript-pro' not foundCause: Persona file missing or persona pack not loadedSolution:
# Check built-in personas
ls ~/.claude/plugins/nyldn-plugins/claude-octopus/agents/personas/

# Check active persona packs
cat .octo/active-packs.json

# Reload persona packs
export OCTOPUS_PERSONA_PACKS=auto
./scripts/orchestrate.sh setup

​
Performance issues

Symptom: /octo:embrace takes 10+ minutesCauses and solutions:
  1. Multiple providers active: Disable unused providers 
    export OCTOPUS_DISABLE_CODEX=true
export OCTOPUS_DISABLE_GEMINI=true
  2. Large context: Reduce prompt size or use /octo:quick for fast iteration
  3. Network latency: Check provider status 
    /octo:status
  4. Opus model overuse: Switch personas to Sonnet or Haiku 
    # In persona frontmatter
model: sonnet  # Instead of opus
Symptom: Token budget exceeded quicklyCauses:
  1. Too many Opus personas: Use inherit or Sonnet models
  2. Parallel multi-AI execution: Disable parallel mode 
    export OCTOPUS_PARALLEL_MODE=false
  3. Large codebase context: Use /octo:quick or /octo:define instead of full embrace
Monitor usage:
# Check current usage
cat ~/.claude-octopus/session.json | jq '.tokens_used'

# Set budget
export OCTOPUS_TOKEN_BUDGET=50000
Symptom: ERROR: Agent timed out after 300sCause: Complex prompt or slow providerSolution:
# Increase timeout
export OCTOPUS_AGENT_TIMEOUT=600  # 10 minutes

# Or simplify prompt
./scripts/orchestrate.sh develop "implement simple auth"

# Check provider latency
time codex "test prompt"
time gemini "test prompt"
Symptom: System runs out of memory during workflowsCause: Large result files or logs accumulatingSolution:
# Clean old results
find ~/.claude-octopus/results -mtime +7 -delete

# Clean old logs
find ~/.claude-octopus/logs -mtime +7 -delete

# Disable memory persistence
export OCTOPUS_MEMORY_MODE=local  # Instead of project or global
Symptom: ERROR: No space left on deviceCause: Logs and results filling diskSolution:
# Check disk usage
du -sh ~/.claude-octopus/*

# Clean all results and logs
rm -rf ~/.claude-octopus/results/*
rm -rf ~/.claude-octopus/logs/*

# Set up log rotation (macOS/Linux)
cat > ~/.claude-octopus/logrotate.conf <<EOF
~/.claude-octopus/logs/*.log {
  rotate 7
  daily
  compress
  missingok
}
EOF

​
Quality gate failures

Symptom: Quality gate FAILED: score 65/75Cause: Output doesn’t meet quality thresholdSolution:
# Review validation report
cat ~/.claude-octopus/results/tangle-validation-*.md

# Lower threshold temporarily
export OCTOPUS_QUALITY_THRESHOLD=60

# Or improve output and retry
./scripts/orchestrate.sh tangle "implement with tests"
Symptom: Consensus gate FAILED: 60% agreement (need 75%)Cause: Providers disagree on approachSolution:
# Review divergent opinions
grep -A 10 "Divergence:" ~/.claude-octopus/results/grasp-synthesis-*.md

# Lower consensus threshold
export OCTOPUS_CONSENSUS_THRESHOLD=60

# Or provide more context
./scripts/orchestrate.sh define "requirements: must use OAuth 2.0"
Symptom: Security gate FAILED: Insufficient OWASP coverageCause: Security audit didn’t find enough vulnerability categoriesSolution:
# This is working as intended — security-auditor needs more thorough analysis
# Retry with more context
./scripts/orchestrate.sh squeeze "audit auth module for OWASP Top 10"

# Or disable gate temporarily (not recommended)
export OCTOPUS_DISABLE_SECURITY_GATE=true

​
Uninstallation issues

Symptom: /plugin uninstall claude-octopus@nyldn-plugins failsSolution:
# Try with scope
/plugin uninstall claude-octopus@nyldn-plugins --scope project

# Force uninstall
/plugin uninstall claude-octopus@nyldn-plugins --force

# Manual cleanup
rm -rf ~/.claude/plugins/nyldn-plugins/claude-octopus
Symptom: Claude Octopus still active after uninstallCause: Workspace config not cleanedSolution:
# Remove workspace config
rm -rf ~/.claude-octopus
rm -rf .octo/

# Remove env vars from shell profile
sed -i '' '/OCTOPUS_/d' ~/.zshrc
source ~/.zshrc

​
Getting more help

If these solutions don’t resolve your issue:
  1. Run diagnostics: 
    /octo:doctor
  2. Enable debug mode: 
    export OCTOPUS_DEBUG=true
./scripts/orchestrate.sh <your-command>
  3. Check logs: 
    tail -100 ~/.claude-octopus/logs/orchestrate.log
  4. Report issue with:

Build docs developers (and LLMs) love

Get started for freeTalk to us