SuperClaude/docs/Getting-Started/installation.md

📦 SuperClaude Installation Guide

Transform Claude Code with 21 Commands, 14 Agents & 6 MCP Servers

Quick Install • Requirements • Methods • Verify • Troubleshoot

---

⚡ Quick Installation

Choose Your Preferred Method

Method	Command	Platform	Best For
🐍 pipx	pipx install SuperClaude && SuperClaude install	Linux/macOS	✅ Recommended - Isolated environment
📦 pip	pip install SuperClaude && SuperClaude install	All	Traditional Python setups
🌐 npm	npm install -g @bifrost_inc/superclaude && superclaude install	All	Node.js developers
🔧 Dev	git clone ... && pip install -e ".[dev]"	All	Contributors & developers

---

📋 Requirements

✅ Required Component Version Check Command Python 3.8+ python3 --version pip Latest pip --version Claude Code Latest claude --version Disk Space 50MB df -h

💡 Optional Component Purpose Check Command Node.js MCP Servers node --version Git Version Control git --version pipx Isolated Install pipx --version RAM Performance 1GB recommended

🔍 Quick System Check

# Run this to check all requirements at once
python3 --version && echo "✅ Python OK" || echo "❌ Python missing"
claude --version && echo "✅ Claude Code OK" || echo "❌ Claude Code missing"
node --version 2>/dev/null && echo "✅ Node.js OK (optional)" || echo "⚠️ Node.js missing (optional)"
git --version 2>/dev/null && echo "✅ Git OK (optional)" || echo "⚠️ Git missing (optional)"

---

🚀 Installation Methods

Detailed Installation Instructions

Method 1: pipx (Recommended)

# Install pipx if not present python3 -m pip install --user pipx python3 -m pipx ensurepath # Install SuperClaude pipx install SuperClaude # Run the installer SuperClaude install

✅ Advantages: Isolated environment No dependency conflicts Clean uninstall Automatic PATH setup 📍 Best for: Linux/macOS users Clean system installs Multiple Python projects

Method 2: pip (Traditional)

# Standard installation pip install SuperClaude # Or user installation pip install --user SuperClaude # Run the installer SuperClaude install

✅ Advantages: Works everywhere Familiar to Python users Direct installation 📍 Best for: Windows users Virtual environments Quick setup

Method 3: npm (Cross-platform)

# Global installation npm install -g @bifrost_inc/superclaude # Run the installer superclaude install

✅ Advantages: Cross-platform NPM ecosystem JavaScript familiar 📍 Best for: Node.js developers NPM users Cross-platform needs

Method 4: Development Installation

# Clone repository git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git cd SuperClaude_Framework # Install in development mode pip install -e ".[dev]" # Test installation SuperClaude install --dry-run

✅ Advantages: Latest features Contribute to project Full source access 📍 Best for: Contributors Custom modifications Testing new features

---

🎛️ Installation Options

Customize Your Installation

Option	Command	Description
Interactive	SuperClaude install	Guided setup with prompts
Specific Components	SuperClaude install --components core mcp modes	Install only what you need
Preview Mode	SuperClaude install --dry-run	See what will be installed
Force Install	SuperClaude install --force --yes	Skip all confirmations
List Components	SuperClaude install --list-components	View available components

---

✅ Verification

Confirm Successful Installation

Step 1: Check Installation

# Verify SuperClaude version
python3 -m SuperClaude --version
# Expected: SuperClaude 4.1.5

# List installed components
SuperClaude install --list-components
# Expected: List of available components

Step 2: Test in Claude Code

# Open Claude Code and try these commands:
/sc:brainstorm "test project"     # Should trigger discovery questions
/sc:analyze README.md              # Should provide structured analysis
@agent-security "review code"     # Should activate security specialist

Step 3: What's Installed

Location	Contents	Size
~/.claude/	Framework files	~50MB
~/.claude/CLAUDE.md	Main entry point	~2KB
~/.claude/*.md	Behavioral instructions	~200KB
~/.claude/claude-code-settings.json	MCP configurations	~5KB

---

🛠️ Management

📦 Update	💾 Backup	🗑️ Uninstall
# Update to latest pip install --upgrade SuperClaude SuperClaude update	# Create backup SuperClaude backup --create # Restore backup SuperClaude backup --restore [file]	# Remove framework SuperClaude uninstall # Uninstall package pip uninstall SuperClaude

---

🔧 Troubleshooting

❌ PEP 668 Error (Python Package Management)

This error occurs on systems with externally managed Python environments.

Solutions (in order of preference):

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

# Option 2: User installation
pip install --user SuperClaude

# Option 3: Virtual environment
python3 -m venv superclaude-env
source superclaude-env/bin/activate  # Linux/macOS
# or
superclaude-env\Scripts\activate  # Windows
pip install SuperClaude

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

❌ Command Not Found

If SuperClaude command is not found after installation:

# Check if package is installed
python3 -m pip show SuperClaude

# Run using Python module
python3 -m SuperClaude install

# Add to PATH (if using --user)
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # Linux
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # macOS

❌ Claude Code Not Found

If Claude Code is not installed or not in PATH:

1. Download from https://claude.ai/code
2. Install following platform instructions
3. Verify with: claude --version
4. Restart terminal after installation

❌ Permission Denied

For permission errors during installation:

# Use user installation
pip install --user SuperClaude

# Or use sudo (not recommended)
sudo pip install SuperClaude

# Better: use pipx
pipx install SuperClaude

❌ Missing Python or pip

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3 python3-pip python3-venv

macOS:

# Install Homebrew first if needed
brew install python3

Windows:

• Download from python.org
• Check "Add Python to PATH" during installation
• Restart terminal after installation

---

📚 Next Steps

Your Learning Journey

🌱 Start Here	🌿 Expand Skills	🌲 Master Framework
First Week: Quick Start Guide Commands Reference Try /sc:brainstorm	Week 2-3: Behavioral Modes Agents Guide Examples Cookbook	Advanced: MCP Servers Technical Architecture Contributing Code

---

🎉 Installation Complete!

You now have access to:

21 Commands • 14 AI Agents • 6 Behavioral Modes • 6 MCP Servers

Ready to start? Try /sc:brainstorm in Claude Code for your first SuperClaude experience!