A framework that extends Claude Code with specialized commands, personas, and MCP server integration.
📢 Status: Initial release, fresh out of beta! Bugs may occur as we continue improving things.
SuperClaude tries to make Claude Code more helpful for development work by adding:
- 🛠️ 16 specialized commands for common dev tasks (some work better than others!)
- 🎭 Smart personas that usually pick the right expert for different domains
- 🔧 MCP server integration for docs, UI components, and browser automation
- 📋 Task management that tries to keep track of progress
- ⚡ Token optimization to help with longer conversations
This is what we've been building to make development workflows smoother. Still rough around the edges, but getting better! 😊
✅ What's Working Well:
- Installation suite (rewritten from the ground up)
- Core framework with 9 documentation files
- 16 slash commands for various development tasks
- MCP server integration (Context7, Sequential, Magic, Playwright)
- Unified CLI installer for easy setup
- This is an initial release - bugs are expected
- Some features may not work perfectly yet
- Documentation is still being improved
- Hooks system was removed (coming back in v4)
We focused on 16 essential commands for the most common tasks:
Development: /sc:implement, /sc:build, /sc:design
Analysis: /sc:analyze, /sc:troubleshoot, /sc:explain
Quality: /sc:improve, /sc:test, /sc:cleanup
Others: /sc:document, /sc:git, /sc:estimate, /sc:task, /sc:index, /sc:load, /sc:spawn
AI specialists that try to jump in when they seem relevant:
- 🏗️ architect - Systems design and architecture stuff
- 🎨 frontend - UI/UX and accessibility
- ⚙️ backend - APIs and infrastructure
- 🔍 analyzer - Debugging and figuring things out
- 🛡️ security - Security concerns and vulnerabilities
- ✍️ scribe - Documentation and writing
- ...and 5 more specialists
(They don't always pick perfectly, but usually get it right!)
External tools that connect when useful:
- Context7 - Grabs official library docs and patterns
- Sequential - Helps with complex multi-step thinking
- Magic - Generates modern UI components
- Playwright - Browser automation and testing stuff
(These work pretty well when they connect properly! 🤞)
If you're coming from SuperClaude v2, you'll need to clean up first:
- Uninstall v2 using its uninstaller if available
- Manual cleanup - delete these if they exist:
SuperClaude/~/.claude/shared/~/.claude/commands/~/.claude/CLAUDE.md
- Then proceed with v3 installation below
This is because v3 has a different structure and the old files can cause conflicts.
The /build command changed! In v2, /build was used for feature implementation. In v3:
/sc:build= compilation/packaging only/sc:implement= feature implementation (NEW!)
Migration: Replace v2 /build myFeature with v3 /sc:implement myFeature
SuperClaude installation is a two-step process:
- First install the Python package
- Then run the installer to set up Claude Code integration
Option A: From PyPI (Recommended)
uv add SuperClaudeOption B: From Source
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude
uv syncSuperClaude v3 also supports installation via uv (a faster, modern Python package manager) or uvx for cross-platform usage.
Make sure uv is installed:
curl -Ls https://astral.sh/uv/install.sh | shOr follow instructions from: https://github.com/astral-sh/uv
Once uv is available, you can install SuperClaude like this:
uv venv
source .venv/bin/activate
uv pip install SuperClaudeIf you’re using uvx, just run:
uvx pip install SuperClaudeAfter installing, continue with the usual installer step:
python3 -m SuperClaude installOr using bash-style CLI:
SuperClaude installuvprovides better caching and performance.- Compatible with Python 3.8+ and works smoothly with SuperClaude.
Missing Python? Install Python 3.7+ first:
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip
# macOS
brew install python3
# Windows
# Download from https://python.org/downloads/After installing the package, run the SuperClaude installer to configure Claude Code (You can use any of the method):
After installing the SuperClaude.
You can use SuperClaude commands
, python3 -m SuperClaude commands or also python3 SuperClaude commands
# Quick setup (recommended for most users)
python3 SuperClaude install
# Interactive selection (choose components)
python3 SuperClaude install --interactive
# Minimal install (just core framework)
python3 SuperClaude install --minimal
# Developer setup (everything included)
python3 SuperClaude install --profile developer
# See all available options
python3 SuperClaude install --help# Quick setup (recommended for most users)
python3 -m SuperClaude install
# Interactive selection (choose components)
python3 -m SuperClaude install --interactive
# Minimal install (just core framework)
python3 -m SuperClaude install --minimal
# Developer setup (everything included)
python3 -m SuperClaude install --profile developer
# See all available options
python3 -m SuperClaude install --help# Quick setup (recommended for most users)
SuperClaude install
# Interactive selection (choose components)
SuperClaude install --interactive
# Minimal install (just core framework)
SuperClaude install --minimal
# Developer setup (everything included)
SuperClaude install --profile developer
# See all available options
SuperClaude install --helpThat's it! 🎉 The installer handles everything: framework files, MCP servers, and Claude Code configuration.
SuperClaude tries to enhance Claude Code through:
- Framework Files - Documentation installed to
~/.claude/that guides how Claude responds - Slash Commands - 16 specialized commands for different dev tasks
- MCP Servers - External services that add extra capabilities (when they work!)
- Smart Routing - Attempts to pick the right tools and experts based on what you're doing
Most of the time it plays nicely with Claude Code's existing stuff. 🤝
We're hoping to work on these things for the next version:
- Hooks System - Event-driven stuff (removed from v3, trying to redesign it properly)
- MCP Suite - More external tool integrations
- Better Performance - Trying to make things faster and less buggy
- More Personas - Maybe a few more domain specialists
- Cross-CLI Support - Might work with other AI coding assistants
(No promises on timeline though - we're still figuring v3 out! 😅)
After installation, you can customize SuperClaude by editing:
~/.claude/settings.json- Main configuration~/.claude/*.md- Framework behavior files
Most users probably won't need to change anything - it usually works okay out of the box. 🎛️
Want to learn more? Check out our guides:
- 📚 User Guide - Complete overview and getting started
- 🛠️ Commands Guide - All 16 slash commands explained
- 🏳️ Flags Guide - Command flags and options
- 🎭 Personas Guide - Understanding the persona system
- 📦 Installation Guide - Detailed installation instructions
These guides have more details than this README and are kept up to date.
We welcome contributions! Areas where we could use help:
- 🐛 Bug Reports - Let us know what's broken
- 📝 Documentation - Help us explain things better
- 🧪 Testing - More test coverage for different setups
- 💡 Ideas - Suggestions for new features or improvements
The codebase is pretty straightforward Python + documentation files.
SuperClaude/
├── setup.py # pypi setup file
├── SuperClaude/ # Framework files
│ ├── Core/ # Behavior documentation (COMMANDS.md, FLAGS.md, etc.)
│ ├── Commands/ # 16 slash command definitions
│ └── Settings/ # Configuration files
├── setup/ # Installation system
└── profiles/ # Installation profiles (quick, minimal, developer)
The v3 architecture focuses on:
- Simplicity - Removed complexity that wasn't adding value
- Reliability - Better installation and fewer breaking changes
- Modularity - Pick only the components you want
- Performance - Faster operations with smarter caching
We learned a lot from v2 and tried to address the main pain points.
Q: Why was the hooks system removed?
A: It was getting complex and buggy. We're redesigning it properly for v4.
Q: Does this work with other AI assistants?
A: Currently Claude Code only, but v4 will have broader compatibility.
Q: Is this stable enough for daily use?
A: The basic stuff works pretty well, but definitely expect some rough edges since it's a fresh release. Probably fine for experimenting! 🧪
MIT - See LICENSE file for details
Built by developers who got tired of generic responses. Hope you find it useful! 🙂
