a0def375e1
Replace hardcoded file arrays with dynamic discovery system: - CoreComponent: Auto-discovers framework .md files in Core directory - CommandsComponent: Auto-discovers command .md files in Commands directory - Eliminates manual maintenance of file lists - Maintains backward compatibility and error handling - Adds comprehensive logging and validation Key changes: - Added _discover_framework_files() and _discover_command_files() methods - Added shared _discover_files_in_directory() utility - Replaced hardcoded arrays with dynamic discovery calls - Includes filtering, sorting, and error handling - Validates 9 framework files and 16 command files correctly - Clean up documentation formatting Resolves maintenance burden described in PR #133 while preserving all existing functionality and security validation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
SuperClaude v3 🚀
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.
What is SuperClaude? 🤔
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! 😊
Current Status 📊
✅ 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
⚠️ Known Issues:
- 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)
Key Features ✨
Commands 🛠️
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
Smart Personas 🎭
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!)
MCP Integration 🔧
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! 🤞)
⚠️ Upgrading from v2? Important!
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.
🔄 Key Change for v2 Users
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
Installation 📦
Quick Start
# Clone the repo
git clone https://github.com/NomenAK/SuperClaude.git
cd SuperClaude
# Install with our unified CLI
python3 SuperClaude.py install --quick
# That's it! 🎉
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/
Other Installation Options
# Minimal install (just core framework)
python3 SuperClaude.py install --minimal
# Developer setup (everything)
python3 SuperClaude.py install --profile developer
# Interactive selection
python3 SuperClaude.py install
# See what's available
python3 SuperClaude.py install --list-components
The installer handles everything: framework files, MCP servers, and Claude Code configuration.
How It Works 🔄
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. 🤝
What's Coming in v4 🔮
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! 😅)
Configuration ⚙️
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. 🎛️
Documentation 📖
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.
Contributing 🤝
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.
Project Structure 📁
SuperClaude/
├── SuperClaude.py # Main installer CLI
├── 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)
Architecture Notes 🏗️
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.
FAQ 🙋
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! 🧪
SuperClaude Contributors
License
MIT - See LICENSE file for details
Star History
Built by developers who got tired of generic responses. Hope you find it useful! 🙂