mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
Consolidate documentation: Extract valuable content from Docs/ into Guides/
- Added Core Philosophy section from Docs/commands-guide.md to Guides/ - Added Command Flags & Options section with comprehensive flag documentation - Added Expert Activation section with complete technical specialists list - Added Command Relationships section showing workflow patterns - Removed Docs/ directory to eliminate duplication - Guides/ now serves as single source of truth for all documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
449
Guides/installation-guide.md
Normal file
449
Guides/installation-guide.md
Normal file
@@ -0,0 +1,449 @@
|
||||
# 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)
|
||||
```bash
|
||||
pip install SuperClaude
|
||||
|
||||
# Install with interactive selection
|
||||
SuperClaude install
|
||||
|
||||
# That's it! 🎉
|
||||
```
|
||||
|
||||
### Option B: From Source
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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](#prerequisites-setup-🛠️) section below.
|
||||
|
||||
## Installation Options 🎛️
|
||||
|
||||
### 🎯 Interactive Installation (Default - Recommended)
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# 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?**
|
||||
```bash
|
||||
# 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)**
|
||||
```bash
|
||||
# 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)**
|
||||
```bash
|
||||
pip install SuperClaude
|
||||
```
|
||||
|
||||
**Option 2: Clone from Git**
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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"**
|
||||
```bash
|
||||
# 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"**
|
||||
```bash
|
||||
# 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"**
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
5. **Explore behavioral modes** - Let SuperClaude adapt to your workflow automatically
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 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. 🙂
|
||||
|
||||
---
|
||||
|
||||
*Last updated: August 2025 - Let us know if anything in this guide is wrong or confusing!*
|
||||
Reference in New Issue
Block a user