📦 SuperClaude Installation Guide

Transform Claude Code with 30 Commands, 20 Agents, 7 Modes & 8 MCP Servers

<p align="center"> </p> <p align="center"> <a href="#-quick-installation">Quick Install</a> • <a href="#-requirements">Requirements</a> • <a href="#-installation-methods">Methods</a> • <a href="#-verification">Verify</a> • <a href="#-troubleshooting">Troubleshoot</a> </p> </div>

⚡ 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 ... && uv pip install -e ".[dev]"`	All	Contributors & developers

</div>

📋 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`

</td> <td align="center" width="50%">

💡 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

</td> </tr> </table> </div> <details> <summary><b>🔍 Quick System Check</b></summary>

bash

# 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)"

</details>

🚀 Installation Methods

Detailed Installation Instructions

</div>

Method 1: pipx (Recommended)

bash

# 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

</td> <td width="40%">

✅ Advantages:

Isolated environment
No dependency conflicts
Clean uninstall
Automatic PATH setup

📍 Best for:

Linux/macOS users
Clean system installs
Multiple Python projects

</td> </tr> </table>

Method 2: pip (Traditional)

bash

# Standard installation
pip install SuperClaude

# Or user installation
pip install --user SuperClaude

# Run the installer
SuperClaude install

</td> <td width="40%">

✅ Advantages:

Works everywhere
Familiar to Python users
Direct installation

📍 Best for:

Windows users
Virtual environments
Quick setup

</td> </tr> </table>

Method 3: npm (Cross-platform)

bash

# Global installation
npm install -g @bifrost_inc/superclaude

# Run the installer
superclaude install

</td> <td width="40%">

✅ Advantages:

Cross-platform
NPM ecosystem
JavaScript familiar

📍 Best for:

Node.js developers
NPM users
Cross-platform needs

</td> </tr> </table>

Method 4: Development Installation

bash

# Clone repository
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework

# Install uv if not present
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install in development mode
uv pip install -e ".[dev]"

# Test installation
SuperClaude install --dry-run

</td> <td width="40%">

✅ Advantages:

Latest features
Contribute to project
Full source access
Fast installation (uv)

📍 Best for:

Contributors
Custom modifications
Testing new features

</td> </tr> </table>

🎛️ 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

</div>

✅ Verification

Confirm Successful Installation

</div>

Step 1: Check Installation

bash

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

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

Step 2: Test in Claude Code

bash

# 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

</div>

🛠️ Management

<div align="center"> <table> <tr> <th>📦 Update</th> <th>💾 Backup</th> <th>🗑️ Uninstall</th> </tr> <tr> <td>

bash

# Update to latest
pip install --upgrade SuperClaude
SuperClaude update

</td> <td>

bash

# Create backup
SuperClaude backup --create

# Restore backup
SuperClaude backup --restore [file]

</td> <td>

bash

# Remove framework
SuperClaude uninstall

# Uninstall package
pip uninstall SuperClaude

</td> </tr> </table> </div>

🔧 Troubleshooting

<details> <summary><b>❌ PEP 668 Error (Python Package Management)</b></summary>

This error occurs on systems with externally managed Python environments.

Solutions (in order of preference):

bash

# 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

</details> <details> <summary><b>❌ Command Not Found</b></summary>

If SuperClaude command is not found after installation:

bash

# 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

</details> <details> <summary><b>❌ Claude Code Not Found</b></summary>

If Claude Code is not installed or not in PATH:

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

</details> <details> <summary><b>❌ Permission Denied</b></summary>

For permission errors during installation:

bash

# Use user installation
pip install --user SuperClaude

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

# Better: use pipx
pipx install SuperClaude

</details> <details> <summary><b>❌ Missing Python or pip</b></summary>

Linux (Ubuntu/Debian):

bash

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

macOS:

bash

# Install Homebrew first if needed
brew install python3

Windows:

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

</details>

📚 Next Steps

Your Learning Journey

<table> <tr> <th>🌱 Start Here</th> <th>🌿 Expand Skills</th> <th>🌲 Master Framework</th> </tr> <tr> <td valign="top">

First Week:

Quick Start Guide
Commands Reference
Try /sc:brainstorm

</td> <td valign="top">

Week 2-3:

</td> <td valign="top">

Advanced:

</td> </tr> </table> </div>

🎉 Installation Complete!

You now have access to:

<p align="center"> <b>30 Commands</b> • <b>20 AI Agents</b> • <b>7 Behavioral Modes</b> • <b>8 MCP Servers</b> </p>

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