SuperClaude/Reference/troubleshooting.md

SuperClaude Troubleshooting Guide 🔧

Comprehensive Problem Resolution: Step-by-step solutions for common SuperClaude issues, from installation problems to advanced configuration challenges. Each solution includes diagnosis steps, resolution procedures, and prevention strategies.

Quick Resolution Focus: Most issues can be resolved in under 5 minutes with the right diagnostic approach. This guide provides systematic troubleshooting methods to get you back to productive development quickly.

Installation Issues

Common Installation Problems

Issue: Permission Denied During Installation

# Error message
ERROR: Permission denied: '/home/user/.claude/CLAUDE.md'

# Diagnosis
ls -la ~/.claude/
# Check file ownership and permissions

# Solution 1: Fix permissions
sudo chown -R $USER ~/.claude
chmod 755 ~/.claude

# Solution 2: Use --user installation
pip install --user SuperClaude
SuperClaude install --install-dir ~/superclaude

# Prevention
# Always install SuperClaude in user space, avoid sudo for installation

Issue: Python Version Compatibility

# Error message
ERROR: SuperClaude requires Python 3.8+ but found Python 3.7

# Diagnosis
python3 --version
which python3

# Solution 1: Update Python (Linux/Ubuntu)
sudo apt update
sudo apt install python3.8 python3.8-pip
python3.8 -m pip install SuperClaude

# Solution 2: Use pyenv for version management
curl https://pyenv.run | bash
pyenv install 3.9.0
pyenv global 3.9.0
pip install SuperClaude

# Solution 3: Virtual environment with specific Python
python3.9 -m venv superclaude-env
source superclaude-env/bin/activate
pip install SuperClaude

Issue: Component Installation Failures

# Error message
ERROR: Component 'mcp' installation failed - dependency not met

# Diagnosis
SuperClaude install --dry-run --components mcp
SuperClaude debug --components

# Solution 1: Install dependencies first
SuperClaude install --components core  # Install core first
SuperClaude install --components mcp   # Then install MCP

# Solution 2: Force reinstallation
SuperClaude install --components mcp --force

# Solution 3: Clean installation
rm -rf ~/.claude/
SuperClaude install --fresh

# Prevention
# Always install components in dependency order: core → agents → modes → mcp

Platform-Specific Issues

Windows Platform Issues:

# Issue: Path separator problems
ERROR: Cannot find file 'C:\Users\name\.claude\CLAUDE.md'

# Solution: Use proper Windows paths
set CLAUDE_CONFIG_DIR=C:\Users\%USERNAME%\.claude
SuperClaude install --install-dir "%CLAUDE_CONFIG_DIR%"

# Issue: Node.js not found for MCP servers
# Solution: Install Node.js from official source
winget install OpenJS.NodeJS
# or download from https://nodejs.org/

# Issue: PowerShell execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS Platform Issues:

# Issue: Homebrew Python conflicts
# Solution: Use pyenv for Python management
brew install pyenv
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
pyenv install 3.9.0
pyenv global 3.9.0

# Issue: Rosetta compatibility on Apple Silicon
# Solution: Install native Python and Node.js
arch -arm64 brew install python@3.9
arch -arm64 brew install node

Linux Distribution Issues:

# Ubuntu/Debian
# Issue: Missing system dependencies
sudo apt update
sudo apt install python3-dev python3-pip build-essential

# CentOS/RHEL
# Issue: Python 3.8+ not available
sudo yum install python39 python39-pip
python3.9 -m pip install SuperClaude

# Arch Linux
# Issue: Package conflicts
sudo pacman -S python python-pip
pip install --user SuperClaude

Command Issues

Command Execution Problems

Issue: Command Not Found

# Error message
ERROR: Command '/sc:analyze' not recognized

# Diagnosis
# Check if SuperClaude is properly installed
SuperClaude --version
ls ~/.claude/

# Check Claude Code session
claude --version

# Solution 1: Restart Claude Code session
# Exit and restart Claude Code completely

# Solution 2: Verify installation
SuperClaude install --list-components
SuperClaude install --components core --force

# Solution 3: Manual verification
cat ~/.claude/CLAUDE.md
# Should contain SuperClaude instructions and imports

# Prevention
# Always restart Claude Code after SuperClaude installation

Issue: Command Timeout or Hanging

# Symptoms: Command runs but never completes

# Diagnosis
# Check system resources
top
df -h
ps aux | grep claude

# Solution 1: Reduce scope
/sc:analyze src/ --scope file    # Instead of entire project
/sc:implement "simple task"      # Instead of complex features

# Solution 2: Use timeout flags
/sc:analyze . --timeout 300      # 5-minute timeout
/sc:implement "feature" --quick  # Faster implementation mode

# Solution 3: Clear cache and restart
rm -rf ~/.claude/cache/
# Restart Claude Code session

# Prevention
# Use appropriate scope for large projects
# Monitor system resources before large operations

Issue: Command Returns Unexpected Results

# Symptoms: Command executes but produces wrong output

# Diagnosis
# Check current directory and context
pwd
ls -la
/sc:reflect  # Check current session context

# Solution 1: Reset session context
/sc:save "backup-session"  # Backup current state
# Restart Claude Code and reload if needed

# Solution 2: Use explicit scope
/sc:analyze ./specific-folder/  # Explicit path
/sc:implement "specific task" --focus area

# Solution 3: Debug mode
export SUPERCLAUDE_DEBUG=true
/sc:analyze . --verbose

# Prevention
# Use explicit paths and clear task descriptions
# Save session state before complex operations

Command Selection and Routing Issues

Issue: Wrong Agent or Mode Activated

# Symptoms: Wrong specialist activated for the task

# Example problem
/sc:implement "database optimization"
# Activates frontend-architect instead of database specialist

# Diagnosis
# Check keyword patterns and triggers
/sc:explain "why was frontend-architect selected for database work?"

# Solution 1: Use explicit keywords
/sc:implement "PostgreSQL database performance optimization"
# More specific keywords trigger correct specialist

# Solution 2: Use focus flags
/sc:implement "database optimization" --focus backend --database

# Solution 3: Manual agent specification
/sc:implement "database optimization" --agent database-specialist

# Prevention
# Use domain-specific terminology
# Include technology names in descriptions

Issue: Mode Selection Problems

# Symptoms: Wrong behavioral mode for the task complexity

# Diagnosis
# Check complexity score and mode thresholds
/sc:reflect "task complexity analysis"

# Example: Task management mode not activating for complex project
/sc:implement "entire microservices platform"
# Should activate task management mode but doesn't

# Solution 1: Explicit mode activation
/sc:implement "microservices platform" --task-manage

# Solution 2: Break down complexity
/sc:workflow "microservices platform"  # Plan first
/sc:implement "authentication service"  # Then implement pieces

# Solution 3: Use complexity flags
/sc:implement "platform" --complex --multi-step

# Prevention
# Describe task complexity explicitly
# Use workflow planning for large projects

Agent & Mode Issues

Agent Activation Problems

Issue: Expected Agent Not Activating

# Example: Security agent not activating for security-related tasks
/sc:implement "user login system"
# Expected: security-engineer activation
# Actual: Only backend-architect activates

# Diagnosis
# Check agent trigger patterns
/sc:explain "agent activation patterns for security tasks"

# Solution 1: Use explicit security keywords
/sc:implement "secure user authentication with JWT and encryption"
# Keywords: "secure", "authentication", "encryption" trigger security-engineer

# Solution 2: Explicit security focus
/sc:implement "user login" --focus security

# Solution 3: Multi-keyword approach
/sc:implement "user login with security best practices and vulnerability protection"

# Verification
# Check which agents activated in response
/sc:reflect "which agents were activated for the last task?"

Issue: Too Many Agents Activating

# Symptoms: Overwhelming agent coordination, slow performance

# Example: Simple task activating multiple agents
/sc:implement "add console.log statement"
# Multiple agents activate unnecessarily

# Solution 1: Reduce task scope
/sc:implement "add debug logging to user.js line 45"
# More specific, simpler task

# Solution 2: Use scope limiting
/sc:implement "logging" --scope file --simple

# Solution 3: Agent limitation
/sc:implement "logging" --max-agents 2

# Prevention
# Use specific, focused task descriptions
# Avoid complex terminology for simple tasks

Issue: Agent Coordination Conflicts

# Symptoms: Agents providing conflicting recommendations

# Diagnosis
# Review agent recommendations and conflicts
/sc:reflect "agent coordination issues in last task"

# Solution 1: Establish priority hierarchy
/sc:implement "payment system" --lead-agent security-engineer
# Security-engineer leads, others support

# Solution 2: Sequential agent consultation
/sc:design "payment architecture" --agent system-architect
/sc:implement "payment security" --agent security-engineer
/sc:implement "payment UI" --agent frontend-architect

# Solution 3: Single-domain focus
/sc:implement "payment backend only" --focus backend

# Prevention
# Break complex tasks into domain-specific subtasks
# Use lead agent designation for complex coordination

Behavioral Mode Problems

Issue: Brainstorming Mode Not Activating

# Expected: Interactive discovery for vague requests
/sc:brainstorm "build something for productivity"
# Should activate brainstorming mode but doesn't

# Diagnosis
# Check for explicit brainstorming keywords
echo "Requirements: vague project, needs discovery"

# Solution 1: Use uncertainty indicators
/sc:brainstorm "maybe we could build some kind of productivity tool"
# Keywords: "maybe", "some kind of" trigger exploration

# Solution 2: Explicit mode activation
/sc:brainstorm "productivity tool" --mode brainstorming

# Solution 3: Question-based approach
/sc:brainstorm "not sure what kind of productivity solution we need"

# Verification
# Mode should respond with Socratic questions

Issue: Task Management Mode Overwhelming Simple Tasks

# Symptoms: Simple task gets complex project management treatment

# Example
/sc:implement "fix typo in README"
# Activates task management mode unnecessarily

# Solution 1: Use simple language
/sc:implement "correct spelling error in README.md"

# Solution 2: Scope limitation
/sc:implement "typo fix" --scope file --simple

# Solution 3: Single-step indication
/sc:implement "one-line fix in README" --quick

# Prevention
# Use simple, direct language for simple tasks
# Indicate single-step nature explicitly

MCP Server Issues

MCP Server Connection Problems

Issue: Context7 Server Not Connecting

# Error message
ERROR: MCP server 'context7' failed to connect

# Diagnosis
# Check Node.js installation
node --version  # Should be 16.0.0 or higher
npm list -g @context7/mcp-server

# Check server configuration
cat ~/.claude/.claude.json | grep context7

# Solution 1: Install/reinstall Node.js and server
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @context7/mcp-server

# Solution 2: Reconfigure MCP servers
SuperClaude install --components mcp --force

# Solution 3: Manual server testing
node -e "console.log('Node.js working')"
npm test @context7/mcp-server

# Verification
/sc:implement "React component" --c7
# Should connect to Context7 for React patterns

Issue: MCP Server Communication Timeout

# Error message
ERROR: MCP server request timeout after 30 seconds

# Diagnosis
# Check network connectivity and server health
ping context7-server.example.com
curl -I https://context7-api.example.com/health

# Check system resources
top
free -h

# Solution 1: Increase timeout
export SUPERCLAUDE_MCP_TIMEOUT=60
/sc:implement "complex task" --timeout 60

# Solution 2: Restart MCP servers
SuperClaude debug --mcp-restart

# Solution 3: Disable problematic server temporarily
/sc:implement "task" --no-mcp
# or
/sc:implement "task" --seq --magic  # Enable specific servers only

# Prevention
# Monitor system resources before large operations
# Use server-specific flags for targeted operations

Issue: Sequential MCP Server Errors

# Error message
ERROR: Sequential reasoning server encountered internal error

# Diagnosis
# Check Sequential server logs
tail -f ~/.claude/logs/sequential-mcp.log

# Check server version compatibility
SuperClaude debug --mcp-versions

# Solution 1: Restart Sequential server
SuperClaude debug --mcp-restart sequential

# Solution 2: Use alternative reasoning approach
/sc:analyze complex-problem --native-reasoning
# Fall back to native analysis

# Solution 3: Reinstall Sequential MCP
npm uninstall -g @sequential/mcp-server
npm install -g @sequential/mcp-server@latest

# Verification
/sc:troubleshoot "test complex debugging scenario" --seq
# Should activate Sequential reasoning successfully

MCP Server Configuration Issues

Issue: Magic MCP Server Not Generating UI Components

# Symptoms: UI component requests not producing expected output

# Diagnosis
# Check Magic server status and configuration
SuperClaude debug --mcp-servers
grep "magic" ~/.claude/.claude.json

# Solution 1: Verify Magic server installation
npm list -g @magic/ui-generator
npm install -g @magic/ui-generator@latest

# Solution 2: Use explicit Magic activation
/sc:implement "React button component" --magic --ui

# Solution 3: Check component request format
/sc:implement "modern responsive navigation component with accessibility"
# More descriptive request for better Magic activation

# Verification
# Should produce complete UI component with modern patterns

Issue: Playwright MCP Server Browser Automation Failures

# Error message
ERROR: Playwright browser automation failed - browser not installed

# Diagnosis
SuperClaude debug --mcp-servers playwright
npx playwright --version

# Solution 1: Install Playwright browsers
npx playwright install
npx playwright install-deps

# Solution 2: Specify browser explicitly
/sc:test "login flow" --browser chromium --playwright

# Solution 3: Fallback to headless mode
/sc:test "ui validation" --headless --playwright

# Verification
/sc:test "simple page load test" --play
# Should successfully run browser automation

Session Management Issues

Session Lifecycle Problems

Issue: Session Context Lost After Restart

# Symptoms: Previous work context not available after Claude Code restart

# Diagnosis
# Check session persistence
ls ~/.claude/sessions/
/sc:load  # Lists available sessions

# Solution 1: Save session before closing
/sc:save "current-work-session"
# Before closing Claude Code

# Solution 2: Auto-save configuration
export SUPERCLAUDE_AUTO_SAVE=true
# Enables automatic session saving

# Solution 3: Manual session recovery
/sc:load "last-session"
/sc:reflect "previous work context"

# Prevention
# Always save important session state
# Use descriptive session names for easy identification

Issue: Session Memory Corruption

# Error message
ERROR: Session data corrupted - cannot restore context

# Diagnosis
# Check session file integrity
ls -la ~/.claude/sessions/
file ~/.claude/sessions/session-*.json

# Solution 1: Restore from backup
/sc:load "backup-session-20241201"  # Use backup session

# Solution 2: Partial context recovery
/sc:reflect "what do I remember about the project?"
# Manually rebuild context

# Solution 3: Fresh session with project analysis
/sc:load project-directory/ --fresh-analysis
# Start fresh with project re-analysis

# Prevention
# Regular session backups with meaningful names
# Avoid force-closing Claude Code during session operations

Issue: Cross-Session Context Inconsistency

# Symptoms: Different sessions provide inconsistent project understanding

# Diagnosis
# Compare session contexts
/sc:load "session-1" && /sc:reflect "project understanding"
/sc:load "session-2" && /sc:reflect "project understanding"

# Solution 1: Consolidate session contexts
/sc:load "session-1"
/sc:save "consolidated-session"
/sc:load "session-2"
/sc:save "consolidated-session" --merge

# Solution 2: Rebuild authoritative context
/sc:load project/ --comprehensive-analysis
/sc:save "authoritative-project-context"

# Solution 3: Use session hierarchy
/sc:load "main-project-session"  # Primary context
/sc:load "feature-branch-session" --inherit-context

# Prevention
# Maintain single authoritative session per project
# Use session inheritance for feature branches

Memory and Context Issues

Issue: Context Memory Leaks

# Symptoms: Session memory usage grows over time, performance degrades

# Diagnosis
# Check session size and memory usage
/sc:debug --memory-usage
du -sh ~/.claude/sessions/

# Solution 1: Clean session memory
/sc:cleanup --session-memory --preserve-important

# Solution 2: Archive old context
/sc:save "archived-context-$(date +%Y%m%d)"
/sc:cleanup --session-reset

# Solution 3: Selective memory cleanup
/sc:cleanup --memory-threshold 100MB --keep-recent 30days

# Prevention
# Regular session maintenance and archiving
# Use focused contexts for specific features

Configuration Issues

Configuration Problems and Validation

Issue: CLAUDE.md Import Conflicts

# Error message
ERROR: Circular import detected in CLAUDE.md

# Diagnosis
# Check import structure
grep -n "@" ~/.claude/CLAUDE.md
# Look for circular references

# Solution 1: Fix circular imports
# Edit ~/.claude/CLAUDE.md to remove problematic @imports
# Remove any @CLAUDE.md references from imported files

# Solution 2: Reset to default configuration
SuperClaude install --reset-config --backup

# Solution 3: Manual configuration repair
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.backup
SuperClaude install --components core --force

# Verification
# Check that imports work correctly
grep "@" ~/.claude/CLAUDE.md
# Verify no circular references

Issue: Component Configuration Conflicts

# Symptoms: Components interfering with each other

# Diagnosis
# Check component installation order and dependencies
SuperClaude install --list-components
SuperClaude debug --component-conflicts

# Solution 1: Reinstall in correct order
SuperClaude install --components core agents modes mcp --force

# Solution 2: Selective component installation
SuperClaude uninstall --components mcp
SuperClaude install --components mcp --clean

# Solution 3: Configuration validation
SuperClaude install --validate-config --fix-conflicts

# Prevention
# Install components in dependency order
# Use --dry-run to preview configuration changes

Issue: Custom Configuration Not Loading

# Symptoms: Personal customizations in CLAUDE.md not taking effect

# Diagnosis
# Check file syntax and structure
cat ~/.claude/CLAUDE.md
# Look for syntax errors

# Solution 1: Validate configuration syntax
SuperClaude debug --validate-config

# Solution 2: Backup and reset
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.custom
SuperClaude install --reset-config
# Manually merge custom content back

# Solution 3: Step-by-step integration
SuperClaude install --components core  # Base installation
# Add custom content gradually and test

# Prevention
# Always backup custom configurations before updates
# Use --dry-run to test configuration changes

Reset and Recovery Procedures

Issue: Complete Configuration Corruption

# Symptoms: SuperClaude completely non-functional after configuration changes

# Emergency Recovery Procedure
# Step 1: Backup current state
cp -r ~/.claude ~/.claude.corrupted.$(date +%Y%m%d)

# Step 2: Complete reset
rm -rf ~/.claude/
SuperClaude install --fresh

# Step 3: Selective recovery
# Restore specific custom files from backup if needed
cp ~/.claude.corrupted.*/custom-file.md ~/.claude/

# Step 4: Gradual reconfiguration
SuperClaude install --components core agents modes
# Test after each component

# Prevention
# Regular configuration backups
# Test configuration changes in non-production environment

Performance Issues

Performance Problems and Optimization

Issue: Slow Command Execution

# Symptoms: Commands taking much longer than expected

# Diagnosis
# Check system resources
top
df -h
iostat 1 5

# Check SuperClaude resource usage
ps aux | grep -i superclaude
/sc:debug --performance-metrics

# Solution 1: Reduce operation scope
/sc:analyze src/ --scope file          # Instead of entire project
/sc:implement "simple task" --quick    # Use quick mode

# Solution 2: Optimize resource allocation
export SUPERCLAUDE_MAX_MEMORY=2GB
export SUPERCLAUDE_CONCURRENCY=2
/sc:analyze . --parallel 2

# Solution 3: Clear caches and restart
rm -rf ~/.claude/cache/
# Restart Claude Code session

# Prevention
# Monitor system resources before large operations
# Use appropriate scope for project size

Issue: Memory Usage Problems

# Symptoms: High memory usage, system slowdown

# Diagnosis
# Check memory usage
free -h
ps aux --sort=-%mem | head -10
/sc:debug --memory-analysis

# Solution 1: Enable memory optimization
export SUPERCLAUDE_MEMORY_OPTIMIZE=true
/sc:analyze . --memory-efficient

# Solution 2: Use streaming mode for large operations
/sc:analyze large-project/ --stream --chunk-size 10MB

# Solution 3: Cleanup and optimization
/sc:cleanup --memory --cache --sessions
# Remove unnecessary cached data

# Prevention
# Regular cache cleanup
# Use memory-efficient modes for large projects
# Monitor memory usage during long sessions

Issue: MCP Server Performance Bottlenecks

# Symptoms: MCP server operations causing delays

# Diagnosis
# Check MCP server performance
/sc:debug --mcp-performance
tail -f ~/.claude/logs/mcp-*.log

# Solution 1: Selective MCP server usage
/sc:implement "task" --c7 --seq  # Use only needed servers
# Instead of --all-mcp

# Solution 2: MCP server optimization
SuperClaude debug --mcp-optimize
# Optimize server configurations

# Solution 3: Local fallback mode
/sc:implement "task" --no-mcp --native-mode
# Use native capabilities when MCP servers slow

# Prevention
# Use targeted MCP server activation
# Monitor MCP server health regularly
# Keep MCP servers updated

Resource Usage Monitoring

Issue: Identifying Resource Bottlenecks

# Comprehensive resource monitoring

# System-level monitoring
htop
iotop
netstat -i

# SuperClaude-specific monitoring
/sc:debug --comprehensive-performance
export SUPERCLAUDE_PROFILE=true
/sc:analyze . --profile

# Analysis and optimization
# Based on monitoring results:
# - High CPU: Use --concurrency flags to limit parallel operations
# - High Memory: Use --memory-efficient modes and cleanup
# - High I/O: Use --cache and reduce file operations
# - High Network: Minimize MCP server usage or use local alternatives

# Automated monitoring setup
crontab -e
# Add: */5 * * * * /usr/local/bin/superclaude debug --quick-health >> ~/.claude/health.log

Common Error Messages

Frequently Encountered Errors

Error: "Command not recognized"

# Full error message
ERROR: Command '/sc:analyze' not recognized by Claude Code

# Meaning: SuperClaude instructions not loaded into Claude Code session
# Resolution:
1. Verify SuperClaude installation: SuperClaude --version
2. Check ~/.claude/CLAUDE.md exists and contains SuperClaude instructions
3. Restart Claude Code completely
4. If persistent: SuperClaude install --components core --force

Error: "Component dependency not met"

# Full error message
ERROR: Component 'mcp' installation failed - dependency 'core' not met

# Meaning: Attempting to install component without required dependencies
# Resolution:
1. Install dependencies first: SuperClaude install --components core
2. Then install desired component: SuperClaude install --components mcp
3. Or use automatic dependency resolution: SuperClaude install --components mcp --resolve-dependencies

Error: "MCP server connection failed"

# Full error message
ERROR: MCP server 'context7' connection failed - server not responding

# Meaning: MCP server unavailable or misconfigured
# Resolution:
1. Check Node.js installation: node --version (should be 16+)
2. Reinstall MCP servers: SuperClaude install --components mcp --force
3. Verify server status: SuperClaude debug --mcp-servers
4. Test without MCP: /sc:command --no-mcp

Error: "Session context corrupted"

# Full error message
ERROR: Cannot load session - data corruption detected

# Meaning: Session file damaged or incompatible format
# Resolution:
1. Try backup session: /sc:load "backup-session-name"
2. List available sessions: /sc:load (shows all sessions)
3. Start fresh: /sc:load project-directory/ --fresh-analysis
4. Rebuild context: /sc:analyze . --comprehensive && /sc:save "new-session"

Error: "Agent activation failed"

# Full error message
ERROR: No suitable agent found for task complexity

# Meaning: Task description insufficient for agent selection
# Resolution:
1. Add specific keywords: /sc:implement "React TypeScript component with security validation"
2. Use explicit focus: /sc:implement "task" --focus frontend --agent frontend-architect
3. Break down complex tasks: /sc:workflow "complex task" first, then implement pieces

Error Interpretation Strategies

Reading Error Context:

# Error format understanding
ERROR: [Component] [Operation] failed - [Specific reason] [Error code]

# Example breakdown
ERROR: MCP context7 connection failed - timeout after 30s [E001]
# Component: MCP context7 server
# Operation: connection attempt  
# Reason: timeout after 30 seconds
# Code: E001 (network/connectivity issue)

# Resolution strategy based on error structure
1. Component issues → Check component installation and configuration
2. Operation issues → Verify prerequisites and permissions
3. Specific reasons → Address the exact cause mentioned
4. Error codes → Look up in documentation or report to support

Getting Help

Bug Reporting Process

Required Information for Bug Reports:

# Essential diagnostic information
SuperClaude --version                    # Version information
uname -a                                 # System information  
python --version                         # Python version
node --version                           # Node.js version (if using MCP)

# SuperClaude-specific diagnostics
SuperClaude debug --comprehensive > debug-report.txt

# Error reproduction
# 1. Exact command that caused the issue
# 2. Expected behavior vs actual behavior
# 3. Screenshots or terminal output
# 4. Steps to reproduce consistently

Bug Report Template:

## Bug Report

**SuperClaude Version:** [Output of `SuperClaude --version`]

**Environment:**
- OS: [Linux/macOS/Windows + version]
- Python: [Output of `python --version`]
- Node.js: [Output of `node --version`] (if using MCP servers)
- Claude Code Version: [Output of `claude --version`]

**Description:**
[Clear description of the issue]

**Steps to Reproduce:**
1. [Step one]
2. [Step two]  
3. [Step three]

**Expected Behavior:**
[What should happen]

**Actual Behavior:**
[What actually happens]

**Error Messages:**

[Paste exact error messages here]

**Debug Information:**
[Attach output of `SuperClaude debug --comprehensive`]

**Additional Context:**
[Any other relevant information]

Available Support Channels

Primary Support Channels:

1. GitHub Issues (Technical Problems)

   • URL: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues
   • Use for: Bug reports, installation issues, feature requests
   • Response time: 24-48 hours for critical issues

2. GitHub Discussions (General Help)

   • URL: https://github.com/SuperClaude-Org/SuperClaude_Framework/discussions
   • Use for: Usage questions, best practices, community support
   • Response time: Community-driven, usually <24 hours

3. Documentation (Self-Service)

   • Installation Guide: ../Getting-Started/installation.md
   • Troubleshooting: This guide
   • Examples: examples-cookbook.md

Community Support:

• Community-maintained FAQ and tips
• User-contributed examples and workflows
• Peer support for common issues

Enterprise Support:

• Available for organizations requiring dedicated support
• Contact: GitHub repository maintainers

Frequently Asked Questions

Installation and Setup

Q: Can I use SuperClaude without Node.js? A: Yes, but with limited functionality. Core SuperClaude works with Python only. MCP servers (Context7, Magic, Sequential) require Node.js 16+ for enhanced capabilities.

Q: Does SuperClaude work on Windows? A: Yes, SuperClaude supports Windows 10/11. Use PowerShell or Command Prompt for installation. Some features may require WSL for optimal compatibility.

Q: How much disk space does SuperClaude require? A: Core installation: ~50MB. With all MCP servers: ~200MB. Session storage grows over time but can be managed with cleanup commands.

Q: Can I install SuperClaude in a virtual environment? A: Yes, recommended for isolation. Use python -m venv superclaude-env && source superclaude-env/bin/activate && pip install SuperClaude.

Usage and Features

Q: How do I know which agent will activate for my task? A: Use descriptive keywords related to your domain (e.g., "secure" for security-engineer, "React" for frontend-architect). Check Agents Guide for trigger patterns.

Q: Can I use specific MCP servers only? A: Yes, use server-specific flags like --c7 (Context7), --seq (Sequential), --magic (Magic UI), or --no-mcp for none.

Q: How do I save and resume work sessions? A: Use /sc:save "session-name" to save and /sc:load "session-name" to resume. See Session Management for details.

Q: What's the difference between modes and agents? A: Modes control behavior style (brainstorming, task management, etc.). Agents provide domain expertise (security, frontend, etc.). They work together automatically.

Troubleshooting

Q: Commands are slow or hanging - what should I do? A: 1) Check system resources with top, 2) Reduce scope with --scope file, 3) Use --quick flag, 4) Clear cache with /sc:cleanup.

Q: How do I reset SuperClaude to default configuration? A: SuperClaude install --reset-config --backup creates backup and resets to defaults.

Q: Can I contribute to SuperClaude development? A: Yes! See Contributing Guide for development setup and contribution process.

System Diagnostics

Diagnostic Commands and Health Checks

Comprehensive System Health Check:

# Complete SuperClaude diagnostics
SuperClaude debug --comprehensive

# Expected output includes:
# - Installation status and component health
# - System compatibility and requirements
# - MCP server status and connectivity  
# - Session management functionality
# - Performance metrics and resource usage
# - Configuration validation and integrity

Quick Health Verification:

# Basic functionality test
SuperClaude --version                    # Version verification
SuperClaude install --list-components    # Component status
SuperClaude debug --quick               # Quick health check

# Test core functionality
echo "Test SuperClaude functionality" | claude
# Then try: /sc:analyze README.md

Component-Specific Diagnostics:

# Test specific components
SuperClaude debug --components core agents modes mcp
SuperClaude debug --mcp-servers         # MCP server health
SuperClaude debug --sessions           # Session management
SuperClaude debug --performance        # Performance metrics

System Requirement Validation

Automated Compatibility Check:

# System requirements validation
SuperClaude install --check-requirements

# Expected validations:
# ✅ Python 3.8+ detected
# ✅ Claude Code installation verified  
# ✅ Sufficient disk space (50MB minimum)
# ✅ Write permissions to ~/.claude directory
# ⚠️  Node.js 16+ recommended for MCP servers
# ✅ System compatibility verified

Manual Verification Steps:

# Python version check
python3 --version
# Should be 3.8.0 or higher

# Claude Code availability
claude --version
# Should return version number without error

# Directory permissions
ls -la ~/.claude/
touch ~/.claude/test-write && rm ~/.claude/test-write
# Should succeed without permission errors

# Optional: Node.js for MCP servers
node --version
# Should be 16.0.0 or higher for full MCP functionality

# System resources
df -h ~                    # Check available disk space
free -h                    # Check available memory (1GB+ recommended)

Performance Baseline Testing:

# Establish performance baselines
time SuperClaude install --dry-run       # Installation speed test
time /sc:analyze small-file.py           # Analysis speed test  
/sc:debug --benchmark                     # Performance benchmarks

# Create performance profile for troubleshooting
export SUPERCLAUDE_PROFILE=true
/sc:analyze . --profile > performance-profile.txt

---

Related Guides

Essential Troubleshooting Resources

Installation and Setup:

• Installation Guide - Complete installation procedures and platform-specific setup
• Quick Start Guide - Basic setup verification and first steps
• System Requirements - Hardware and software requirements

Configuration and Customization:

• Configuration Overview - Configuration flags and customization options
• Session Management - Session lifecycle and persistence troubleshooting
• MCP Servers - MCP server setup and connection troubleshooting

Usage and Features:

• Commands Reference - Command syntax and usage examples
• Agents Guide - Agent activation patterns and coordination troubleshooting
• Behavioral Modes - Mode selection and behavioral troubleshooting

Advanced Topics:

• Examples Cookbook - Working examples and practical troubleshooting scenarios
• Best Practices - Performance optimization and efficiency troubleshooting
• Technical Architecture - Deep system understanding for complex issues

Developer Resources

Framework Development:

• Contributing Code - Development environment setup and troubleshooting
• Testing & Debugging - Advanced debugging techniques and testing procedures

Community Support:

• GitHub Issues - Bug reports and technical support
• GitHub Discussions - Community help and best practices
• Contributing Guidelines - How to contribute fixes and improvements

Quick Reference Links

Immediate Help:

• Installation Issues → Installation Guide
• Command Problems → Commands Reference
• Performance Issues → Best Practices
• Configuration Issues → MCP Servers

Learning Resources:

• New Users → Quick Start Guide
• Practical Examples → Examples Cookbook
• Advanced Usage → Technical Architecture

---

Emergency Recovery: If SuperClaude is completely non-functional:

1. Backup current configuration: cp -r ~/.claude ~/.claude.backup
2. Complete reset: rm -rf ~/.claude && SuperClaude install --fresh
3. Restore custom configurations gradually from backup
4. If issues persist, report to GitHub Issues with diagnostic information