Skip to content

troubleshooting.md

Latest commit

 

History

History
124 lines (95 loc) · 2.89 KB

troubleshooting.md

File metadata and controls

124 lines (95 loc) · 2.89 KB

SuperClaude Troubleshooting Guide 🔧

Quick fixes to advanced diagnostics for SuperClaude Framework issues.

Quick Fixes (90% of problems)

Installation Verification:

python3 -m SuperClaude --version    # Should show 4.1.5
SuperClaude install --list-components

Command Issues:

# Test in Claude Code:
/sc:brainstorm "test project"        # Should ask discovery questions

# If no response: Restart Claude Code session

Resolution Checklist:

  • Version commands work and show 4.1.5
  • /sc: commands respond in Claude Code
  • MCP servers listed: SuperClaude install --list-components | grep mcp

Common Issues

Installation Problems

Package Installation Fails:

# For pipx users
pipx uninstall SuperClaude
pipx install SuperClaude

# For pip users
pip uninstall SuperClaude
pip install --upgrade pip
pip install SuperClaude

Permission Denied / PEP 668 Error:

# Option 1: Use pipx (recommended)
pipx install SuperClaude

# Option 2: Use pip with --user flag
pip install --user SuperClaude

# Option 3: Fix permissions
sudo chown -R $USER ~/.claude

# Option 4: Force installation (use with caution)
pip install --break-system-packages SuperClaude

Component Missing:

python3 -m SuperClaude install --components core commands agents modes --force

Command Issues

Commands Not Recognized:

  1. Restart Claude Code completely
  2. Verify: python3 -m SuperClaude --version
  3. Test: /sc:brainstorm "test"

Agents Not Activating:

  • Use specific keywords: /sc:implement "secure JWT authentication"
  • Manual activation: @agent-security "review auth code"

Slow Performance:

/sc:analyze . --no-mcp               # Test without MCP servers
/sc:analyze src/ --scope file        # Limit scope

MCP Server Issues

Server Connection Fails:

ls ~/.claude/.claude.json            # Check config exists
node --version                       # Verify Node.js 16+
SuperClaude install --components mcp --force

API Key Required (Magic/Morphllm):

export TWENTYFIRST_API_KEY="your_key"
export MORPH_API_KEY="your_key"
# Or use: /sc:command --no-mcp

Advanced Diagnostics

System Analysis:

SuperClaude install --diagnose
cat ~/.claude/logs/superclaude.log | tail -50

Component Analysis:

ls -la ~/.claude/                    # Check installed files
grep -r "@" ~/.claude/CLAUDE.md      # Verify imports

Reset Installation:

SuperClaude backup --create          # Backup first
SuperClaude uninstall
SuperClaude install --fresh

Get Help

Documentation:

Community:

  • GitHub Issues
  • Include: OS, Python version, error message, steps to reproduce