SuperClaude/Guides/installation-guide.md

SuperClaude Installation Guide 📦

🎯 It's Easier Than It Looks!

The honest truth: This guide looks comprehensive because we want to cover all the details, but installation is actually simple. Most people are done in 2 minutes with one command!

Quick Start 🚀

🏆 The "Just Get It Working" Approach (Recommended for 90% of Users)

Option A: From PyPI (Recommended)

pip install SuperClaude

# Install with interactive selection
SuperClaude install

# That's it! 🎉

Option B: From Source

git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
pip install .

# Install with interactive selection
SuperClaude install

# That's it! 🎉

What you just got:

• ✅ 21 intelligent commands that auto-activate specialized capabilities
• ✅ 13 specialized AI agents with domain expertise and smart routing
• ✅ 5 behavioral modes for different types of work
• ✅ 6 MCP servers for extended functionality (optional)
• ✅ Session lifecycle management with persistent context
• ✅ About 2 minutes of your time and ~50MB disk space

Nervous about what it will do? See first with:

SuperClaude install --dry-run

Before You Start 🔍

What You Need 💻

SuperClaude works on Windows, macOS, and Linux. Here's what you need:

Required:

• Python 3.8 or newer - The framework is written in Python
• Claude Code - SuperClaude enhances Claude Code, so you need it installed first

Optional (but recommended):

• Node.js 16+ - Only needed if you want MCP server integration
• Git - Helpful for development workflows

Quick Check 🔍

Before installing, let's make sure you have the basics:

# Check Python version (should be 3.8+)
python3 --version

# Check if Claude Code is available
claude --version

# Check Node.js (optional, for MCP servers)
node --version

If any of these fail, see the Prerequisites Setup section below.

Installation Options 🎛️

🎯 Interactive Installation (Default - Recommended)

SuperClaude install

• Stage 1: Select MCP servers (Context7, Sequential, Magic, Playwright, etc.)
• Stage 2: Choose framework components (Core, Commands, Agents, Modes)
• Time: ~3-5 minutes depending on selections
• Space: ~50-100MB depending on selections
• Good for: All users - gives you full control over what gets installed
• Interactive: Shows detailed descriptions and lets you pick exactly what you want

⚡ Component-Specific Installation

SuperClaude install --components core commands modes

• What: Install only specific components you need
• Available components: core, commands, agents, modes, mcp, mcp_docs
• Good for: Users who know exactly what they want

🔍 Other Useful Options

# See all available components
SuperClaude install --list-components

# See what would be installed without doing it
SuperClaude install --dry-run

# System diagnostics and installation help
SuperClaude install --diagnose

# Quiet installation (minimal output)
SuperClaude install --quiet

# Install everything
SuperClaude install --components all

Step-by-Step Installation 📋

Prerequisites Setup 🛠️

Missing Python?

# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip

# macOS  
brew install python3

# Windows
# Download from https://python.org/downloads/
# Or use winget
winget install python

Missing Claude Code?

• Visit https://claude.ai/code for installation instructions
• SuperClaude enhances Claude Code, so you need it first

Missing Node.js? (Optional)

# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install nodejs npm

# macOS
brew install node

# Windows  
# Download from https://nodejs.org/
# Or use winget
winget install nodejs

Getting SuperClaude 📥

Option 1: From PyPI (Recommended)

pip install SuperClaude

Option 2: Clone from Git

git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
pip install .

Running the Installer 🎬

The installer is smart and will guide you through the process:

# See all available options
SuperClaude install --help

# Interactive installation (recommended)
SuperClaude install

# Want to see what would happen first?
SuperClaude install --dry-run

# Install specific components
SuperClaude install --components core commands agents modes

# Quiet installation (minimal output)
SuperClaude install --quiet

During Installation 📱

Here's what happens when you install:

1. System Check - Verifies you have required dependencies
2. Component Selection - Interactive selection of what to install
3. MCP Server Setup - Downloads and configures MCP servers (if selected)
4. API Key Collection - Prompts for required API keys for selected servers
5. Framework Installation - Copies framework documentation files
6. Configuration Setup - Creates settings and CLAUDE.md imports
7. Validation - Tests that everything works

The installer shows progress and will tell you if anything goes wrong.

After Installation ✅

Quick Test 🧪

Let's make sure everything worked:

# Check if files were installed
ls ~/.claude/

# Should show: CLAUDE.md, RULES.md, PRINCIPLES.md, etc.

Test with Claude Code:

1. Open Claude Code
2. Try typing /sc:help - you should see SuperClaude commands
3. Try /sc:analyze --help - should show command options

What Got Installed 📂

SuperClaude installs to ~/.claude/ by default. Here's what you'll find:

~/.claude/
├── CLAUDE.md              # Main framework entry point
├── FLAGS.md               # Command flags and options
├── PRINCIPLES.md          # Development principles
├── RULES.md               # Operational rules
├── MCP_*.md               # MCP server configurations
├── MODE_*.md              # Behavioral modes
├── settings.json          # Configuration file (if created)
└── SuperClaude/           # Framework components
    ├── Core/              # Core framework files
    ├── Commands/          # 21 command definitions
    ├── Agents/            # 13 specialized agents
    ├── Modes/             # 5 behavioral modes
    └── MCP/               # MCP server configurations

What each file does:

• CLAUDE.md - Tells Claude Code about SuperClaude and loads other files
• RULES.md - Operational rules and workflow patterns
• PRINCIPLES.md - Development principles and decision frameworks
• FLAGS.md - Command flags and behavioral controls
• SuperClaude/ - Complete framework with commands, agents, and modes

First Steps 🎯

Try these commands to get started:

# In Claude Code, try these:
/sc:help                    # See available commands
/sc:analyze README.md       # Analyze a file
/sc:build --help           # See build options
/sc:improve --help         # See improvement options
/sc:brainstorm "my app idea" # Try brainstorming mode
/sc:load                   # Initialize session with context

Don't worry if it seems overwhelming - SuperClaude enhances Claude Code gradually. You can use as much or as little as you want.

Managing Your Installation 🛠️

Updates 📅

Keep SuperClaude up to date:

# Update the package
pip install --upgrade SuperClaude

# Reinstall components
SuperClaude install --force

# Update specific components only
SuperClaude install --components core commands --force

Backups 💾

SuperClaude automatically creates backups during installation. You can also create manual backups of your ~/.claude/ directory:

# Create a backup
cp -r ~/.claude/ ~/.claude_backup_$(date +%Y%m%d)

# Restore from backup
rm -rf ~/.claude/
cp -r ~/.claude_backup_20250115/ ~/.claude/

Uninstallation 🗑️

If you need to remove SuperClaude:

# Remove just the package
pip uninstall SuperClaude

# Remove all SuperClaude files (keeps your other Claude settings)
rm -rf ~/.claude/SuperClaude/
rm -f ~/.claude/CLAUDE.md ~/.claude/RULES.md ~/.claude/PRINCIPLES.md ~/.claude/FLAGS.md
rm -f ~/.claude/MCP_*.md ~/.claude/MODE_*.md

What gets removed:

• All SuperClaude files in ~/.claude/
• The SuperClaude Python package

What stays:

• Your other Claude Code settings
• Your projects and other files
• Any backups you created

Troubleshooting 🔧

Common Issues 🚨

"Python not found"

# Try python instead of python3
python --version

# Or check if it's installed but not in PATH
which python3

"Claude Code not found"

• Make sure Claude Code is installed first
• Visit https://claude.ai/code for installation help

"Permission denied"

# Try with explicit Python path
/usr/bin/python3 -m SuperClaude install

# Or check if you need different permissions
ls -la ~/.claude/

"MCP servers won't install"

• Check that Node.js is installed: node --version
• Check that npm is available: npm --version
• Try installing without MCP first: select "Skip MCP Server installation" during interactive setup

"Installation fails partway through"

# Try with verbose output to see what's happening
SuperClaude install --verbose

# Or try a dry run first
SuperClaude install --dry-run

# Try system diagnostics
SuperClaude install --diagnose

Platform-Specific Issues 🖥️

Windows:

• Use python instead of python3 if you get "command not found"
• Run Command Prompt as Administrator if you get permission errors
• Make sure Python is in your PATH

macOS:

• You might need to approve SuperClaude in Security & Privacy settings
• Use brew install python3 if you don't have Python 3.8+
• Try using python3 explicitly instead of python

Linux:

• Make sure you have python3-pip installed
• You might need sudo for some package installations
• Check that ~/.local/bin is in your PATH

Still Having Issues? 🤔

Check our troubleshooting resources:

• GitHub Issues: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues
• Look for existing issues similar to yours
• Create a new issue if you can't find a solution

When reporting bugs, please include:

• Your operating system and version
• Python version (python3 --version)
• Claude Code version (claude --version)
• The exact command you ran
• The complete error message
• What you expected to happen

Advanced Options ⚙️

Custom Installation Directory

# Install to custom location
SuperClaude install --install-dir /custom/path

# Use environment variable
export SUPERCLAUDE_DIR=/custom/path
SuperClaude install

Development Setup

If you're planning to contribute or modify SuperClaude:

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

# Install in development mode
pip install -e .

# Install all components
SuperClaude install --components all

What's Next? 🚀

Now that SuperClaude is installed:

1. Just start using it - Try /sc:analyze some-file.js or /sc:build and see what happens ✨
2. Don't stress about learning - SuperClaude usually figures out what you need
3. Experiment freely - Commands like /sc:improve and /sc:troubleshoot are pretty forgiving
4. Use session management - Try /sc:load and /sc:save for persistent context (Session Management Guide)
5. Explore behavioral modes - Let SuperClaude adapt to your workflow automatically (Behavioral Modes Guide)
6. Give feedback - Let us know what works and what doesn't

The real secret: SuperClaude is designed to enhance your existing workflow without you having to learn a bunch of new stuff. Just use it like you'd use regular Claude Code, but notice how much smarter it gets! 🎯

Still feeling uncertain? Start with just /sc:help and /sc:analyze README.md - you'll see how approachable it actually is.

Next Steps:

• Examples Cookbook - Copy-paste commands for common tasks
• SuperClaude User Guide - Complete framework overview
• Commands Guide - All 21 commands with examples

---

Final Notes 📝

• Installation takes 1-5 minutes depending on what you choose
• Disk space needed: 20-100MB (not much!)
• Works alongside existing tools - doesn't interfere with your setup
• Easy to uninstall if you change your mind
• Community supported - we actively read and respond to issues
• Available commands: Use SuperClaude [command], python3 -m SuperClaude [command], or /sc:[command] in Claude Code

Thanks for trying SuperClaude! We hope it makes your development workflow smoother and more intelligent. 🙂

---

Related Guides

🚀 What to Do Next (Essential)

• Examples Cookbook - Copy-paste commands to get started immediately
• SuperClaude User Guide - Complete framework overview and philosophy

📚 Learning the System (Recommended)

• Commands Guide - All 21 commands with practical examples
• Session Management Guide - Persistent context and project memory
• Behavioral Modes Guide - How SuperClaude adapts automatically

🔧 When You Need Help

• Troubleshooting Guide - Solutions for installation and usage issues
• Best Practices Guide - Proven patterns for effective usage

🎯 Advanced Usage (Optional)

• Agents Guide - Understanding the 13 specialized AI experts
• Flags Guide - Manual control and optimization options
• Technical Architecture Guide - Internal system design

📖 Recommended Reading Path After Installation:

1. Examples Cookbook - Try commands immediately
2. Commands Guide - Learn your toolkit
3. Session Management Guide - Enable persistent context
4. Best Practices Guide - Optimize your workflow

---

Last updated: August 2025 - Let us know if anything in this guide is wrong or confusing!