mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-17 17:56:46 +00:00
fdfb05e981
* The -i flag has been removed from the `_run_command_cross_platform` function in `setup/components/mcp.py`. * fix: Prevent installer from hanging during MCP installation The SuperClaude installer was hanging during the installation of MCP components on non-Windows systems. This was caused by the use of an interactive shell (`-i`) when executing the `claude mcp add` command. The interactive shell would attempt to read from standard input, causing the process to be suspended by the shell. This commit fixes the issue by removing the `-i` flag from the `_run_command_cross_platform` function in `setup/components/mcp.py`. This ensures that the installation process runs non-interactively and completes without hanging. * fix: Add 'cmd /c' for Windows and refactor shell execution This commit resolves an issue with `npx` command execution on Windows by prepending `cmd /c` to the command. It also refactors the shell command execution for non-Windows systems to use the `executable` argument in `subprocess.run` for a cleaner and more robust implementation. * fix: Add 'cmd /c' for Windows and refactor shell execution This commit resolves an issue with `npx` command execution on Windows by prepending `cmd /c` to the command. It also refactors the shell command execution for non-Windows systems to use the `executable` argument in `subprocess.run` for a cleaner and more robust implementation. * docs: Update Chrome DevTools MCP documentation This commit updates the documentation for the Chrome DevTools MCP server to be more comprehensive and consistent with the existing documentation structure. The file `SuperClaude/MCP/MCP_Chrome-DevTools.md` has been updated with detailed information about the server's purpose, triggers, and usage examples. * docs: Update documentation for Chrome DevTools MCP This commit updates the main README.md and the MCP servers user guide to include information about the new Chrome DevTools MCP server. The documentation has been updated to reflect the new server count and provide details about the new server's functionality. * chore: Bump version to 4.1.5 This commit updates the version number from 4.1.4 to 4.1.5 across the entire codebase. This includes updates to: - CHANGELOG.md - Documentation files - Configuration files (package.json, pyproject.toml) - Source code fallbacks - The main VERSION file --------- Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
514 lines
9.9 KiB
Markdown
514 lines
9.9 KiB
Markdown
<div align="center">
|
|
|
|
# 📦 SuperClaude Installation Guide
|
|
|
|
### **Transform Claude Code with 21 Commands, 14 Agents & 6 MCP Servers**
|
|
|
|
<p align="center">
|
|
<img src="https://img.shields.io/badge/version-4.1.5-blue?style=for-the-badge" alt="Version">
|
|
<img src="https://img.shields.io/badge/Python-3.8+-green?style=for-the-badge" alt="Python">
|
|
<img src="https://img.shields.io/badge/Platform-Linux%20|%20macOS%20|%20Windows-orange?style=for-the-badge" alt="Platform">
|
|
</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**
|
|
|
|
<div align="center">
|
|
|
|
### **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 |
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## 📋 **Requirements**
|
|
|
|
<div align="center">
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="50%">
|
|
|
|
### ✅ **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**
|
|
|
|
<div align="center">
|
|
|
|
### **Detailed Installation Instructions**
|
|
|
|
</div>
|
|
|
|
### **Method 1: pipx (Recommended)**
|
|
|
|
<table>
|
|
<tr>
|
|
<td width="60%">
|
|
|
|
```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)**
|
|
|
|
<table>
|
|
<tr>
|
|
<td width="60%">
|
|
|
|
```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)**
|
|
|
|
<table>
|
|
<tr>
|
|
<td width="60%">
|
|
|
|
```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**
|
|
|
|
<table>
|
|
<tr>
|
|
<td width="60%">
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
</td>
|
|
<td width="40%">
|
|
|
|
**✅ Advantages:**
|
|
- Latest features
|
|
- Contribute to project
|
|
- Full source access
|
|
|
|
**📍 Best for:**
|
|
- Contributors
|
|
- Custom modifications
|
|
- Testing new features
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
---
|
|
|
|
## 🎛️ **Installation Options**
|
|
|
|
<div align="center">
|
|
|
|
### **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**
|
|
|
|
<div align="center">
|
|
|
|
### **Confirm Successful Installation**
|
|
|
|
</div>
|
|
|
|
### **Step 1: Check Installation**
|
|
|
|
```bash
|
|
# 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**
|
|
|
|
```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**
|
|
|
|
<div align="center">
|
|
|
|
| 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:
|
|
|
|
1. Download from [https://claude.ai/code](https://claude.ai/code)
|
|
2. Install following platform instructions
|
|
3. Verify with: `claude --version`
|
|
4. 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](https://python.org)
|
|
- Check "Add Python to PATH" during installation
|
|
- Restart terminal after installation
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## 📚 **Next Steps**
|
|
|
|
<div align="center">
|
|
|
|
### **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](quick-start.md)
|
|
- [Commands Reference](../User-Guide/commands.md)
|
|
- Try `/sc:brainstorm`
|
|
|
|
</td>
|
|
<td valign="top">
|
|
|
|
**Week 2-3:**
|
|
- [Behavioral Modes](../User-Guide/modes.md)
|
|
- [Agents Guide](../User-Guide/agents.md)
|
|
- [Examples Cookbook](../Reference/examples-cookbook.md)
|
|
|
|
</td>
|
|
<td valign="top">
|
|
|
|
**Advanced:**
|
|
- [MCP Servers](../User-Guide/mcp-servers.md)
|
|
- [Technical Architecture](../Developer-Guide/technical-architecture.md)
|
|
- [Contributing Code](../Developer-Guide/contributing-code.md)
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
### **🎉 Installation Complete!**
|
|
|
|
You now have access to:
|
|
|
|
<p align="center">
|
|
<b>21 Commands</b> • <b>14 AI Agents</b> • <b>6 Behavioral Modes</b> • <b>6 MCP Servers</b>
|
|
</p>
|
|
|
|
**Ready to start?** Try `/sc:brainstorm` in Claude Code for your first SuperClaude experience!
|
|
|
|
<p align="center">
|
|
<a href="quick-start.md">
|
|
<img src="https://img.shields.io/badge/📖_Continue_to-Quick_Start_Guide-blue?style=for-the-badge" alt="Quick Start">
|
|
</a>
|
|
</p>
|
|
|
|
</div> |