External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-17 17:56:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
SuperClaude/Docs/Reference/troubleshooting.md
NomenAK 418683c265 📝 Complete version update to 4.0.4 across all files 
- Updated all documentation references
- Updated all Python module versions
- Updated configuration and metadata files
- Synchronized version across entire codebase
2025-08-22 21:13:05 +02:00

2.6 KiB
Raw Blame History

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.0.4
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.0.4
  • /sc: commands respond in Claude Code
  • MCP servers listed: SuperClaude install --list-components | grep mcp

Common Issues

Installation Problems

Package Installation Fails:

pip uninstall SuperClaude
pip install --upgrade pip
pip install SuperClaude

Permission Denied:

pip install --user SuperClaude
# Or: sudo chown -R $USER ~/.claude

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