# SuperClaude v4.0.0 ๐Ÿš€ [![Website Preview](https://img.shields.io/badge/Visit-Website-blue?logo=google-chrome)](https://superclaude-org.github.io/SuperClaude_Website/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PyPI version](https://img.shields.io/pypi/v/SuperClaude.svg)](https://pypi.org/project/SuperClaude/) [![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](https://github.com/SuperClaude-Org/SuperClaude_Framework) [![GitHub issues](https://img.shields.io/github/issues/SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/CONTRIBUTING.md) [![Contributors](https://img.shields.io/github/contributors/SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors) [![Website](https://img.shields.io/website?url=https://superclaude-org.github.io/SuperClaude_Website/)](https://superclaude-org.github.io/SuperClaude_Website/) An intelligent framework that transforms Claude Code into a comprehensive development environment with specialized agents, behavioral modes, and advanced MCP integration. **๐Ÿ“ข Status**: v4.0.0 is here! Major architecture overhaul with new behavioral modes, session lifecycle, and comprehensive agent system. ## What is SuperClaude v4.0.0? ๐Ÿค” SuperClaude v4.0.0 represents a complete evolution of the development framework, now featuring: - ๐Ÿ› ๏ธ **21 specialized commands** for comprehensive development workflows - ๐Ÿค– **13 specialized agents** with domain expertise and intelligent routing - ๐Ÿง  **5 Behavioral Modes** for different types of work (Brainstorming, Introspection, Task Management, Orchestration, Token Efficiency) - ๐Ÿ”ง **6 MCP servers** including the powerful new Morphllm and Serena agents - ๐Ÿ’พ **Session Lifecycle** with persistent context via /sc:load and /sc:save This is a complete rethink of how AI-assisted development should work - more intelligent, more capable, and more adaptable to your workflow! ๐ŸŽฏ ## Support SuperClaude Development ๐Ÿ’Ž Help us continue advancing the future of AI-assisted development! SuperClaude v4.0.0 represents a major architectural evolution with significant improvements: ### What Your Support Enables ๐Ÿš€ - **Framework Evolution** - Continued development of behavioral modes and agent intelligence - **Claude Code Subscriptions** - Essential API access for framework development and testing - **Documentation Quality** - Comprehensive guides and technical writing improvements - **Community Resources** - Better tooling, examples, and educational materials ### Ways to Support ๐Ÿค [![Support on Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20Development-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/superclaude) [![GitHub Sponsors](https://img.shields.io/badge/GitHub-Sponsor-EA4AAA?logo=github-sponsors&logoColor=white)](https://github.com/sponsors/SuperClaude-Org) [![Support on Patreon](https://img.shields.io/badge/Patreon-Support%20Us-F96854?logo=patreon&logoColor=white)](https://patreon.com/superclaude) ## Current Status ๐Ÿ“Š โœ… **What's New in v4.0.0:** - Complete rework of behavioral foundation with 30-50% token efficiency gains - 13 specialized agents with domain expertise and collaborative coordination - Context-aware adaptive behavior with automatic activation - Persistent development context across sessions with smart checkpointing - Significant weight reduction while expanding capabilities - Advanced MCP integration with Morphllm and Serena โœ… **What's Working Well:** - All 21 commands with enhanced capabilities - Full MCP server integration suite - Session lifecycle with /sc:load and /sc:save - Behavioral modes with automatic activation - Intelligent agent routing and coordination โœ… **Production Ready:** - Stable release with comprehensive testing - Full documentation and user guides - Performance optimizations implemented ## Key Features โœจ ### 21 Specialized Commands ๐Ÿ› ๏ธ Enhanced command suite for comprehensive development workflows: **Development**: `/sc:implement`, `/sc:build`, `/sc:design` **Analysis**: `/sc:analyze`, `/sc:troubleshoot`, `/sc:explain` **Quality**: `/sc:improve`, `/sc:test`, `/sc:cleanup` **Session**: `/sc:load`, `/sc:save`, `/sc:brainstorm`, `/sc:reflect` **Workflow**: `/sc:task`, `/sc:spawn`, `/sc:workflow`, `/sc:select-tool` **Others**: `/sc:document`, `/sc:git`, `/sc:estimate`, `/sc:index` ### 13 Specialized Agents ๐Ÿค– AI specialists with deep domain expertise and intelligent coordination: - ๐Ÿ—๏ธ **system-architect** - System design and architecture - ๐ŸŽจ **frontend-architect** - UI/UX and modern frontend development - โš™๏ธ **backend-architect** - APIs, infrastructure, and server-side logic - ๐Ÿ” **root-cause-analyst** - Systematic investigation and debugging - ๐Ÿ›ก๏ธ **security-engineer** - Security assessment and vulnerability analysis - โœ๏ธ **technical-writer** - Technical documentation and writing - โšก **performance-engineer** - Optimization and performance engineering - ๐Ÿงช **quality-engineer** - Quality assurance and testing strategies - ๐Ÿ **python-expert** - Python development and best practices - ๐Ÿค– **devops-architect** - Infrastructure and deployment automation - ๐Ÿ”ง **refactoring-expert** - Code refactoring and clean code principles - ๐Ÿ“‹ **requirements-analyst** - Requirements discovery and analysis - ๐ŸŽฏ **learning-guide** - Teaching and educational explanations *These agents feature intelligent routing, context awareness, and collaborative problem-solving capabilities.* ### 5 Behavioral Modes ๐Ÿง  Revolutionary behavioral system that adapts SuperClaude's approach: #### Brainstorming Mode - **Purpose**: Interactive requirements discovery and ideation - **Triggers**: Ambiguous requests, exploration keywords, uncertainty indicators - **Features**: Socratic dialogue, collaborative discovery, automated brief generation #### Introspection Mode - **Purpose**: Meta-cognitive analysis and framework troubleshooting - **Triggers**: Self-analysis requests, complex problem solving, error recovery - **Features**: Reasoning analysis, decision validation, pattern recognition #### Task Management Mode - **Purpose**: Multi-layer orchestration and systematic delegation - **Triggers**: Multi-step operations, complex builds, system-wide changes - **Features**: Progressive orchestration, sub-agent delegation, performance analytics #### Orchestration Mode - **Purpose**: Intelligent tool selection and resource optimization - **Triggers**: Multi-tool operations, performance constraints, parallel execution - **Features**: Smart tool selection, parallel thinking, resource management #### Token Efficiency Mode - **Purpose**: Intelligent optimization with symbol systems and compression - **Triggers**: Resource constraints, large contexts, performance needs - **Features**: 30-50% token reduction, quality preservation, adaptive compression ### 6 MCP Server Integration ๐Ÿ”ง Comprehensive external tool ecosystem: - **Context7** - Official library documentation and patterns - **Sequential** - Multi-step analysis and complex reasoning - **Magic** - Modern UI component generation - **Playwright** - Browser automation and E2E testing - **Morphllm** - Intelligent file editing with Fast Apply capability - **Serena** - Semantic code analysis and project-wide operations ### Session Lifecycle System ๐Ÿ’พ Persistent development context with intelligent management: - **`/sc:load`** - Initialize projects with full context restoration - **`/sc:save`** - Create checkpoints and preserve session state - **Automatic Checkpoints** - Task completion, time-based, risk-based triggers - **Cross-Session Learning** - Accumulated insights and pattern recognition ### Advanced Framework Features Intelligent architecture with built-in capabilities: - **Framework Coordinator** - Cross-component orchestration - **Performance Monitor** - Real-time metrics and optimization - **Quality Gates** - 8-step validation pipeline - **Session Lifecycle** - Event-driven session management ## โš ๏ธ Upgrading from v3? Important! SuperClaude v4.0.0 is a major architectural upgrade. Clean installation recommended: 1. **Backup Important Data** - Save any custom configurations 2. **Clean Previous Installation**: ```bash python3 -m SuperClaude uninstall # If available rm -rf ~/.claude/SuperClaude/ rm -rf ~/.claude/shared/ ``` 3. **Install v4.0.0** - Follow installation instructions below ### ๐Ÿ”„ **Key Changes for v3 Users** - **New Commands**: `/sc:brainstorm`, `/sc:reflect`, `/sc:save`, `/sc:select-tool` - **Session Management**: Use `/sc:load` to initialize projects, `/sc:save` for persistence - **Agent System**: Enhanced from personas to full agent coordination - **Behavioral Modes**: Automatic activation based on context and needs ## Installation ๐Ÿ“ฆ SuperClaude v4.0.0 installation with enhanced capabilities: ### Step 1: Install the Package **Option A: From PyPI (Recommended)** ```bash pip install SuperClaude ``` **Option B: From Source** ```bash git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git cd SuperClaude_Framework pip install -e . ``` --- **Missing Python?** Install Python 3.8+ first: ```bash # Linux (Ubuntu/Debian) sudo apt update && sudo apt install python3 python3-pip # macOS brew install python3 # Windows # Download from https://python.org/downloads/ ``` ### Step 2: Run the v4.0.0 Installer Enhanced installer with behavioral modes and session lifecycle: ```bash # v4.0.0 setup (recommended for most users) python3 -m SuperClaude install # See all v4.0.0 options python3 -m SuperClaude install --help ``` ### Simple bash Command Usage ```bash # v4.0.0 setup SuperClaude install ``` **That's it! ๐ŸŽ‰** The v4.0.0 installer configures everything: behavioral modes, MCP servers, and session lifecycle. ## How v4.0.0 Works ๐Ÿ”„ SuperClaude v4.0.0 transforms Claude Code through intelligent architecture: 1. **Behavioral Modes** - Adaptive behavior based on context and task requirements 2. **Agent Coordination** - 13 specialized agents with intelligent routing and collaboration 3. **Session Lifecycle** - Persistent context with /sc:load and /sc:save commands 4. **MCP Integration** - 6 powerful servers for extended capabilities The system intelligently adapts to your workflow, automatically activating appropriate modes and agents. ๐Ÿง  ## v4.0.0 Architecture Highlights ๐Ÿ—๏ธ ### Behavioral Intelligence - **Automatic Mode Detection** - Context-aware behavioral adaptation - **Cross-Mode Coordination** - Seamless integration between behavioral patterns - **Progressive Enhancement** - Capabilities scale with complexity ### Agent Orchestration - **Intelligent Routing** - Smart agent selection based on domain expertise - **Collaborative Problem-Solving** - Multi-agent coordination for complex tasks - **Context Preservation** - Agents maintain awareness across interactions ### Session Management - **Persistent Context** - Full project state preservation across sessions - **Intelligent Checkpointing** - Automatic saves based on risk and completion - **Cross-Session Learning** - Accumulated insights and pattern recognition ## Configuration โš™๏ธ v4.0.0 configuration with enhanced behavioral controls: - `~/.claude/*.md` - Behavioral mode configurations - `~/.claude/agents/` - Agent-specific customizations - `~/.claude/commands/` - Command definitions and configurations - `~/.serena/` - Session lifecycle and memory management Most users can use defaults - v4.0.0 intelligently adapts to your workflow! ๐ŸŽ›๏ธ ## Documentation ๐Ÿ“– Comprehensive v4.0.0 guides and documentation: - ๐Ÿ“š [**v4.0.0 User Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/superclaude-user-guide.md) - Complete v4.0.0 overview and getting started - ๐Ÿ› ๏ธ [**Commands Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/commands-guide.md) - All 21 commands with v4.0.0 enhancements - ๐Ÿง  [**Behavioral Modes Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/behavioral-modes-guide.md) - Understanding the 5 behavioral modes - ๐Ÿค– [**Agent System Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/agent-system-guide.md) - Working with 13 specialized agents - ๐Ÿณ๏ธ [**Flags Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/flags-guide.md) - v4.0.0 command flags and behavioral controls - ๐Ÿ“ฆ [**Installation Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/installation-guide.md) - Detailed v4.0.0 installation and setup ## Contributing ๐Ÿค v4.0.0 opens new contribution opportunities: - ๐Ÿ› **Bug Reports** - Help us improve the stable release - ๐Ÿ“ **Documentation** - v4.0.0 features need clear explanation - ๐Ÿงช **Testing** - Community participation across different environments - ๐Ÿ”ง **Framework Development** - Extend the framework capabilities - ๐Ÿค– **Agent Enhancement** - Improve specialized agent capabilities - ๐Ÿง  **Behavioral Modes** - Contribute to mode intelligence The v4.0.0 architecture is modular - many ways to contribute! ### Documentation & Community ๐Ÿ“ While we strive for accuracy, the rapid v4.0.0 evolution means documentation may contain errors. We rely on our community to: - **Report Issues** - Help us identify documentation gaps or technical problems - **Submit Improvements** - PRs for documentation fixes and enhancements are always welcome - **Share Feedback** - Your experience helps shape future development priorities *Every contribution, whether code, documentation, or financial support, helps make SuperClaude better for the entire development community! ๐ŸŒŸ* ## Project Structure ๐Ÿ“ ``` SuperClaude_Framework/ โ”œโ”€โ”€ ๐Ÿ“ SuperClaude/ # Core framework documentation & behavioral definitions โ”‚ โ”œโ”€โ”€ ๐Ÿค– Agents/ # 13 specialized agents with domain expertise โ”‚ โ”‚ โ”œโ”€โ”€ backend-architect.md # API & server-side architecture specialist โ”‚ โ”‚ โ”œโ”€โ”€ devops-architect.md # Infrastructure & deployment automation โ”‚ โ”‚ โ”œโ”€โ”€ frontend-architect.md # UI/UX & modern frontend development โ”‚ โ”‚ โ”œโ”€โ”€ learning-guide.md # Educational explanations & tutorials โ”‚ โ”‚ โ”œโ”€โ”€ performance-engineer.md # Optimization & performance engineering โ”‚ โ”‚ โ”œโ”€โ”€ python-expert.md # Python development & best practices โ”‚ โ”‚ โ”œโ”€โ”€ quality-engineer.md # QA strategies & testing frameworks โ”‚ โ”‚ โ”œโ”€โ”€ refactoring-expert.md # Code cleanup & architectural improvements โ”‚ โ”‚ โ”œโ”€โ”€ requirements-analyst.md # Requirements discovery & analysis โ”‚ โ”‚ โ”œโ”€โ”€ root-cause-analyst.md # Systematic debugging & investigation โ”‚ โ”‚ โ”œโ”€โ”€ security-engineer.md # Security assessment & vulnerability analysis โ”‚ โ”‚ โ”œโ”€โ”€ system-architect.md # High-level system design & architecture โ”‚ โ”‚ โ””โ”€โ”€ technical-writer.md # Technical documentation & communication โ”‚ โ”œโ”€โ”€ ๐Ÿ› ๏ธ Commands/ # 21 specialized slash commands โ”‚ โ”‚ โ”œโ”€โ”€ analyze.md # Code & project analysis โ”‚ โ”‚ โ”œโ”€โ”€ brainstorm.md # Interactive requirements discovery โ”‚ โ”‚ โ”œโ”€โ”€ build.md # Smart build with auto-optimization โ”‚ โ”‚ โ”œโ”€โ”€ cleanup.md # Code cleanup & organization โ”‚ โ”‚ โ”œโ”€โ”€ design.md # Architecture & design planning โ”‚ โ”‚ โ”œโ”€โ”€ document.md # Technical documentation generation โ”‚ โ”‚ โ”œโ”€โ”€ estimate.md # Project estimation & planning โ”‚ โ”‚ โ”œโ”€โ”€ explain.md # Code explanation & education โ”‚ โ”‚ โ”œโ”€โ”€ git.md # Advanced git operations โ”‚ โ”‚ โ”œโ”€โ”€ implement.md # Feature implementation & development โ”‚ โ”‚ โ”œโ”€โ”€ improve.md # Code enhancement & optimization โ”‚ โ”‚ โ”œโ”€โ”€ index.md # Command registry & coordination โ”‚ โ”‚ โ”œโ”€โ”€ load.md # Session initialization & context loading โ”‚ โ”‚ โ”œโ”€โ”€ reflect.md # Session reflection & analysis โ”‚ โ”‚ โ”œโ”€โ”€ save.md # Session persistence & context saving โ”‚ โ”‚ โ”œโ”€โ”€ select-tool.md # Intelligent tool selection โ”‚ โ”‚ โ”œโ”€โ”€ spawn.md # Agent spawning & coordination โ”‚ โ”‚ โ”œโ”€โ”€ task.md # Task management & orchestration โ”‚ โ”‚ โ”œโ”€โ”€ test.md # Testing strategies & execution โ”‚ โ”‚ โ”œโ”€โ”€ troubleshoot.md # Problem diagnosis & resolution โ”‚ โ”‚ โ””โ”€โ”€ workflow.md # Workflow automation & management โ”‚ โ”œโ”€โ”€ ๐Ÿง  Core/ # Foundational behavioral rules & principles โ”‚ โ”‚ โ”œโ”€โ”€ FLAGS.md # Behavioral flags for execution modes โ”‚ โ”‚ โ”œโ”€โ”€ PRINCIPLES.md # Software engineering principles โ”‚ โ”‚ โ””โ”€โ”€ RULES.md # Operational rules & guidelines โ”‚ โ”œโ”€โ”€ ๐Ÿ”ง MCP/ # MCP server integration & configs โ”‚ โ”‚ โ””โ”€โ”€ configs/ # MCP server configuration files โ”‚ โ””โ”€โ”€ ๐ŸŽญ Modes/ # 5 behavioral modes for adaptive behavior โ”‚ โ”œโ”€โ”€ MODE_Brainstorming.md # Interactive discovery & ideation โ”‚ โ”œโ”€โ”€ MODE_Introspection.md # Meta-cognitive analysis & reflection โ”‚ โ”œโ”€โ”€ MODE_Orchestration.md # Intelligent tool selection & coordination โ”‚ โ”œโ”€โ”€ MODE_Task_Management.md # Multi-layer orchestration & delegation โ”‚ โ””โ”€โ”€ MODE_Token_Efficiency.md # Symbol-enhanced compression & optimization โ”œโ”€โ”€ ๐Ÿ“š Guides/ # Comprehensive user documentation โ”‚ โ””โ”€โ”€ superclaude-user-guide.md # Complete usage guide & workflows โ”œโ”€โ”€ ๐Ÿ—๏ธ setup/ # Modular installation & configuration system โ”‚ โ”œโ”€โ”€ cli/ # Command-line interface & operations โ”‚ โ”‚ โ”œโ”€โ”€ commands/ # CLI command implementations โ”‚ โ”‚ โ”œโ”€โ”€ install.py # Installation orchestration โ”‚ โ”‚ โ”œโ”€โ”€ update.py # Update management โ”‚ โ”‚ โ””โ”€โ”€ uninstall.py # Clean uninstallation โ”‚ โ”œโ”€โ”€ components/ # Component-based installation modules โ”‚ โ”œโ”€โ”€ core/ # Core installation logic & registry โ”‚ โ”‚ โ”œโ”€โ”€ installer.py # Installation orchestration engine โ”‚ โ”‚ โ””โ”€โ”€ registry.py # Component discovery & dependency resolution โ”‚ โ”œโ”€โ”€ data/ # Installation data & metadata โ”‚ โ””โ”€โ”€ services/ # Configuration management services โ”‚ โ”œโ”€โ”€ claude_md.py # Dynamic CLAUDE.md generation โ”‚ โ”œโ”€โ”€ config.py # Configuration management โ”‚ โ””โ”€โ”€ file_ops.py # File operation utilities โ”œโ”€โ”€ ๐Ÿ”จ scripts/ # Build, validation & publishing automation โ”‚ โ”œโ”€โ”€ build_and_upload.py # PyPI package building & publishing โ”‚ โ”œโ”€โ”€ publish.sh # Production publishing workflow โ”‚ โ””โ”€โ”€ validate_pypi_ready.py # Package validation & compliance โ”œโ”€โ”€ ๐Ÿ“„ Configuration Files โ”‚ โ”œโ”€โ”€ CLAUDE.md # Project-specific Claude Code instructions โ”‚ โ”œโ”€โ”€ pyproject.toml # Python project configuration & dependencies โ”‚ โ”œโ”€โ”€ uv.lock # Dependency lock file for reproducible builds โ”‚ โ””โ”€โ”€ README.md # This comprehensive project overview โ””โ”€โ”€ ๐Ÿ“‹ Documentation โ”œโ”€โ”€ CHANGELOG.md # Version history & release notes โ”œโ”€โ”€ CONTRIBUTING.md # Contribution guidelines & development setup โ”œโ”€โ”€ CODE_OF_CONDUCT.md # Community standards & expectations โ”œโ”€โ”€ SECURITY.md # Security policies & vulnerability reporting โ””โ”€โ”€ PUBLISHING.md # Publishing guidelines & release procedures ``` ## v4.0.0 Architecture Notes ๐Ÿ—๏ธ The v4.0.0 architecture focuses on: - **Behavioral Intelligence** - Context-aware adaptive behavior - **Agent Orchestration** - Sophisticated multi-agent coordination - **Session Persistence** - Continuous learning and context preservation - **Performance** - Token efficiency and resource optimization v4.0.0 represents a fundamental evolution in AI-assisted development frameworks. ## FAQ ๐Ÿ™‹ **Q: What's new in v4.0.0 compared to V3?** A: Complete architecture overhaul with behavioral modes, session lifecycle, 13 agents, and 6 MCP servers. **Q: How does the new architecture work?** A: Built on behavioral modes, intelligent agents, and session persistence for adaptive development workflows. **Q: Should I upgrade from V3?** A: v4.0.0 offers significant improvements, with clean installation recommended for best experience. **Q: How stable is v4.0.0?** A: Production-ready stable release with comprehensive testing and community validation! ## SuperClaude Contributors [![Contributors](https://contrib.rocks/image?repo=SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors) ## License MIT - [See LICENSE file for details](https://opensource.org/licenses/MIT) ## Star History Star History Chart --- *v4.0.0: The future of AI-assisted development is here. Experience intelligent, adaptive, and powerful development workflows! ๐Ÿš€* ---