docs/reference/troubleshooting.md
Quick fixes to advanced diagnostics for SuperClaude Framework issues.
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:
/sc: commands respond in Claude CodeSuperClaude install --list-components | grep mcpPackage 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
Commands Not Recognized:
python3 -m SuperClaude --version/sc:brainstorm "test"Agents Not Activating:
/sc:implement "secure JWT authentication"@agent-security "review auth code"Slow Performance:
/sc:analyze . --no-mcp # Test without MCP servers
/sc:analyze src/ --scope file # Limit scope
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
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
Documentation:
Community: