# Repository: SuperClaude-Org/SuperClaude_Framework
# Stars: 22324
## CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## π Python Environment Rules
**CRITICAL**: This project uses **UV** for all Python operations. Never use `python -m`, `pip install`, or `python script.py` directly.
### Required Commands
```bash
# All Python operations must use UV
uv run pytest # Run tests
uv run pytest tests/pm_agent/ # Run specific tests
uv pip install package # Install dependencies
uv run python script.py # Execute scripts
```
## π Project Structure
**Current v4.3.0 Architecture**: Python package with 30 commands, 20 agents, 7 modes
```
# Claude Code Configuration (v4.3.0)
# Installed via `superclaude install` to user's home directory
~/.claude/
βββ settings.json
βββ commands/sc/ # 30 slash commands (/sc:research, /sc:implement, etc.)
β βββ pm.md
β βββ research.md
β βββ implement.md
β βββ ... (30 total)
βββ agents/ # 20 domain-specialist agents (@pm-agent, @system-architect, etc.)
β βββ pm-agent.md
β βββ system-architect.md
β βββ ... (20 total)
βββ skills/ # Skills (confidence-check, etc.)
# Python Package
src/superclaude/
βββ __init__.py # Public API: ConfidenceChecker, SelfCheckProtocol, ReflexionPattern
βββ pytest_plugin.py # Auto-loaded pytest integration (5 fixtures, 9 markers)
βββ pm_agent/ # confidence.py, self_check.py, reflexion.py, token_budget.py
βββ execution/ # parallel.py, reflection.py, self_correction.py
βββ cli/ # main.py, doctor.py, install_commands.py, install_mcp.py, install_skill.py
βββ commands/ # 30 slash command definitions (.md files)
βββ agents/ # 20 agent definitions (.md files)
βββ modes/ # 7 behavioral modes (.md files)
βββ skills/ # Installable skills (confidence-check, etc.)
βββ hooks/ # Claude Code hook definitions
βββ mcp/ # MCP server configurations (10 servers)
βββ core/ # Core utilities
# Project Files
tests/ # Python test suite (136 tests)
βββ unit/ # Unit tests (auto-marked @pytest.mark.unit)
βββ integration/ # Integration tests (auto-marked @pytest.mark.integration)
docs/ # Documentation
scripts/ # Analysis tools (workflow metrics, A/B testing)
plugins/ # Exported plugin artefacts for distribution
PLANNING.md # Architecture, absolute rules
TASK.md # Current tasks
KNOWLEDGE.md # Accumulated insights
```
### Claude Code Integration Points
SuperClaude integrates with Claude Code through these mechanisms:
- **Slash Commands**: 30 commands installed to `~/.claude/commands/sc/` (e.g., `/sc:pm`, `/sc:research`)
- **Agents**: 20 agents installed to `~/.claude/agents/` (e.g., `@pm-agent`, `@system-architect`)
- **Skills**: Installed to `~/.claude/skills/` (e.g., confidence-check)
- **Hooks**: Session lifecycle hooks in `src/superclaude/hooks/`
- **Settings**: Project settings in `.claude/settings.json`
- **Pytest Plugin**: Auto-loaded via entry point, provides fixtures and markers
- **MCP Servers**: 8+ servers configurable via `superclaude mcp`
## π§ Development Workflow
### Essential Commands
```bash
# Setup
make dev # Install in editable mode with dev dependencies
make verify # Verify installation (package, plugin, health)
# Testing
make test # Run full test suite
uv run pytest tests/pm_agent/ -v # Run specific directory
uv run pytest tests/test_file.py -v # Run specific file
uv run pytest -m confidence_check # Run by marker
uv run pytest --cov=superclaude # With coverage
# Code Quality
make lint # Run ruff linter
make format # Format code with ruff
make doctor # Health check diagnostics
# MCP Servers
superclaude mcp # Interactive install (gateway default)
superclaude mcp --list # List available servers
superclaude mcp --servers airis-mcp-gateway # Install AIRIS Gateway (recommended)
superclaude mcp --servers tavily context7 # Install individual servers
# Plugin Packaging
make build-plugin # Build plugin artefacts into dist/
make sync-plugin-repo # Sync artefacts into ../SuperClaude_Plugin
# Maintenance
make clean # Remove build artifacts
```
## π¦ Core Architecture
### Pytest Plugin (Auto-loaded)
Registered via `pyproject.toml` entry point, automatically available after installation.
**Fixtures**: `confidence_checker`, `self_check_protocol`, `reflexion_pattern`, `token_budget`, `pm_context`
**Auto-markers**:
- Tests in `/unit/` β `@pytest.mark.unit`
- Tests in `/integration/` β `@pytest.mark.integration`
**Custom markers**: `@pytest.mark.confidence_check`, `@pytest.mark.self_check`, `@pytest.mark.reflexion`
### PM Agent - Three Core Patterns
**1. ConfidenceChecker** (src/superclaude/pm_agent/confidence.py)
- Pre-execution confidence assessment: β₯90% required, 70-89% present alternatives, <70% ask questions
- Prevents wrong-direction work, ROI: 25-250x token savings
**2. SelfCheckProtocol** (src/superclaude/pm_agent/self_check.py)
- Post-implementation evidence-based validation
- No speculation - verify with tests/docs
**3. ReflexionPattern** (src/superclaude/pm_agent/reflexion.py)
- Error learning and prevention
- Cross-session pattern matching
### Parallel Execution
**Wave β Checkpoint β Wave pattern** (src/superclaude/execution/parallel.py):
- 3.5x faster than sequential execution
- Automatic dependency analysis
- Example: [Read files in parallel] β Analyze β [Edit files in parallel]
### Slash Commands, Agents & Modes (v4.3.0)
- Install via: `pipx install superclaude && superclaude install`
- **30 Commands** installed to `~/.claude/commands/sc/` (e.g., `/sc:pm`, `/sc:research`, `/sc:implement`)
- **20 Agents** installed to `~/.claude/agents/` (e.g., `@pm-agent`, `@system-architect`, `@deep-research`)
- **7 Behavioral Modes**: Brainstorming, Business Panel, Deep Research, Introspection, Orchestration, Task Management, Token Efficiency
- **Skills**: Installable to `~/.claude/skills/` (e.g., confidence-check)
> **Note**: TypeScript plugin system planned for v5.0 ([#419](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues/419))
## π§ͺ Testing with PM Agent
### Example Test with Markers
```python
@pytest.mark.confidence_check
def test_feature(confidence_checker):
"""Pre-execution confidence check - skips if < 70%"""
context = {"test_name": "test_feature", "has_official_docs": True}
assert confidence_checker.assess(context) >= 0.7
@pytest.mark.self_check
def test_implementation(self_check_protocol):
"""Post-implementation validation with evidence"""
implementation = {"code": "...", "tests": [...]}
passed, issues = self_check_protocol.validate(implementation)
assert passed, f"Validation failed: {issues}"
@pytest.mark.reflexion
def test_error_learning(reflexion_pattern):
"""If test fails, reflexion records for future prevention"""
pass
@pytest.mark.complexity("medium") # simple: 200, medium: 1000, complex: 2500
def test_with_budget(token_budget):
"""Token budget allocation"""
assert token_budget.limit == 1000
```
## πΏ Git Workflow
**Branch structure**: `master` (production) β `integration` (testing) β `feature/*`, `fix/*`, `docs/*`
**Standard workflow**:
1. Create branch from `integration`: `git checkout -b feature/your-feature`
2. Develop with tests: `uv run pytest`
3. Commit: `git commit -m "feat: description"` (conventional commits)
4. Merge to `integration` β validate β merge to `master`
**Current branch**: See git status in session start output
### Parallel Development with Git Worktrees
**CRITICAL**: When running multiple Claude Code sessions in parallel, use `git worktree` to avoid conflicts.
```bash
# Create worktree for integration branch
cd ~/github/SuperClaude_Framework
git worktree add ../SuperClaude_Framework-integration integration
# Create worktree for feature branch
git worktree add ../SuperClaude_Framework-feature feature/pm-agent
```
**Benefits**:
- Run Claude Code sessions on different branches simultaneously
- No branch switching conflicts
- Independent working directories
- Parallel development without state corruption
**Usage**:
- Session A: Open `~/github/SuperClaude_Framework/` (current branch)
- Session B: Open `~/github/SuperClaude_Framework-integration/` (integration)
- Session C: Open `~/github/SuperClaude_Framework-feature/` (feature branch)
**Cleanup**:
```bash
git worktree remove ../SuperClaude_Framework-integration
```
## π Key Documentation Files
**PLANNING.md** - Architecture, design principles, absolute rules
**TASK.md** - Current tasks and priorities
**KNOWLEDGE.md** - Accumulated insights and troubleshooting
Additional docs in `docs/user-guide/`, `docs/developer-guide/`, `docs/reference/`
## π‘ Core Development Principles
### 1. Evidence-Based Development
**Never guess** - verify with official docs (Context7 MCP, WebFetch, WebSearch) before implementation.
### 2. Confidence-First Implementation
Check confidence BEFORE starting: β₯90% proceed, 70-89% present alternatives, <70% ask questions.
### 3. Parallel-First Execution
Use **Wave β Checkpoint β Wave** pattern (3.5x faster). Example: `[Read files in parallel]` β Analyze β `[Edit files in parallel]`
### 4. Token Efficiency
- Simple (typo): 200 tokens
- Medium (bug fix): 1,000 tokens
- Complex (feature): 2,500 tokens
- Confidence check ROI: spend 100-200 to save 5,000-50,000
## π§ MCP Server Integration
**Recommended**: Use **airis-mcp-gateway** for unified MCP management.
```bash
superclaude mcp # Interactive install, gateway is default (requires Docker)
```
**Gateway Benefits**: 60+ tools, 98% token reduction, single SSE endpoint, Web UI
**High Priority Servers** (included in gateway):
- **Tavily**: Web search (Deep Research)
- **Context7**: Official documentation (prevent hallucination)
- **Sequential**: Token-efficient reasoning (30-50% reduction)
- **Serena**: Session persistence
- **Mindbase**: Cross-session learning
**Optional**: Playwright (browser automation), Magic (UI components), Chrome DevTools (performance)
**Usage**: TypeScript plugins and Python pytest plugin can call MCP servers. Always prefer MCP tools over speculation for documentation/research.
## π Development & Installation
### Current Installation Method (v4.3.0)
**Standard Installation**:
```bash
# Option 1: pipx (recommended)
pipx install superclaude
superclaude install
# Option 2: Direct from repo
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
./install.sh
```
**Development Mode**:
```bash
# Install in editable mode
make dev
# Run tests
make test
# Verify installation
make verify
```
### Plugin System (v5.0 - Not Yet Available)
The TypeScript plugin system (`.claude-plugin/`, marketplace) is planned for v5.0.
See `docs/plugin-reorg.md` for details.
## π Package Information
**Package name**: `superclaude`
**Version**: 4.3.0
**Python**: >=3.10
**Build system**: hatchling (PEP 517)
**Entry points**:
- CLI: `superclaude` command
- Pytest plugin: Auto-loaded as `superclaude`
**Dependencies**:
- pytest>=7.0.0
- click>=8.0.0
- rich>=13.0.0
## π Claude Code Native Features (for developers)
SuperClaude extends Claude Code through its native extension points. When developing SuperClaude features, use these Claude Code capabilities:
### Extension Points We Use
- **Custom Commands** (`~/.claude/commands/sc/*.md`): 30 `/sc:*` commands
- **Custom Agents** (`~/.claude/agents/*.md`): 20 domain-specialist agents
- **Skills** (`~/.claude/skills/`): confidence-check skill
- **Settings** (`.claude/settings.json`): Permission rules, hooks
- **MCP Servers**: 8 pre-configured + AIRIS gateway
- **Pytest Plugin**: Auto-loaded via entry point
### Extension Points We Should Use More
- **Hooks** (28 events): `SessionStart`, `Stop`, `PostToolUse`, `TaskCompleted` β ideal for PM Agent auto-restore, self-check validation, and reflexion triggers
- **Skills System**: Commands should migrate to proper skills with YAML frontmatter for auto-triggering, tool restrictions, and effort overrides
- **Plan Mode**: Could integrate with confidence checks (block implementation when < 70%)
- **Settings Profiles**: Could provide recommended permission/hook configs per workflow
- **Native Session Persistence**: `--continue`/`--resume` instead of custom memory files
See `docs/user-guide/claude-code-integration.md` for the full gap analysis.
## README.md
# π SuperClaude Framework
[](https://smithery.ai/skills?ns=SuperClaude-Org&utm_source=github&utm_medium=badge)
### **Transform Claude Code into a Structured Development Platform**
## π **Framework Statistics**
| **Commands** | **Agents** | **Modes** | **MCP Servers** |
|:------------:|:----------:|:---------:|:---------------:|
| **30** | **20** | **7** | **8** |
| Slash Commands | Specialized AI | Behavioral | Integrations |
30 slash commands covering the complete development lifecycle from brainstorming to deployment.
---
## π― **Overview**
SuperClaude is a **meta-programming configuration framework** that transforms Claude Code into a structured development platform through behavioral instruction injection and component orchestration. It provides systematic workflow automation with powerful tools and intelligent agents.
## Disclaimer
This project is not affiliated with or endorsed by Anthropic.
Claude Code is a product built and maintained by [Anthropic](https://www.anthropic.com/).
## π **For Developers & Contributors**
**Essential documentation for working with SuperClaude Framework:**
| Document | Purpose | When to Read |
|----------|---------|--------------|
| **[PLANNING.md](PLANNING.md)** | Architecture, design principles, absolute rules | Session start, before implementation |
| **[TASK.md](TASK.md)** | Current tasks, priorities, backlog | Daily, before starting work |
| **[KNOWLEDGE.md](KNOWLEDGE.md)** | Accumulated insights, best practices, troubleshooting | When encountering issues, learning patterns |
| **[CONTRIBUTING.md](CONTRIBUTING.md)** | Contribution guidelines, workflow | Before submitting PRs |
| **[Commands Reference](docs/user-guide/commands.md)** | Complete reference for all 30 `/sc:*` commands with syntax, examples, workflows, and decision guides | Learning SuperClaude, choosing the right command |
> **π‘ Pro Tip**: Claude Code reads these files at session start to ensure consistent, high-quality development aligned with project standards.
>
> **π New to SuperClaude?** Start with [Commands Reference](docs/user-guide/commands.md) β it contains visual decision trees, detailed command comparisons, and workflow examples to help you understand which commands to use and when.
## β‘ **Quick Installation**
> **IMPORTANT**: The TypeScript plugin system described in older documentation is
> not yet available (planned for v5.0). For current installation
> instructions, please follow the steps below for v4.x.
### **Current Stable Version (v4.3.0)**
SuperClaude currently uses slash commands.
**Option 1: pipx (Recommended)**
```bash
# Install from PyPI
pipx install superclaude
# Install commands (installs all 30 slash commands)
superclaude install
# Install MCP servers (optional, for enhanced capabilities)
superclaude mcp --list # List available MCP servers
superclaude mcp # Interactive installation
superclaude mcp --servers tavily --servers context7 # Install specific servers
# Verify installation
superclaude install --list
superclaude doctor
```
After installation, restart Claude Code to use 30 commands including:
- `/sc:research` - Deep web research (enhanced with Tavily MCP)
- `/sc:brainstorm` - Structured brainstorming
- `/sc:implement` - Code implementation
- `/sc:test` - Testing workflows
- `/sc:pm` - Project management
- `/sc` - Show all 30 available commands
**Option 2: Direct Installation from Git**
```bash
# Clone the repository
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
# Run the installation script
./install.sh
```
### **Coming in v5.0 (In Development)**
We are actively working on a new TypeScript plugin system (see issue [#419](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues/419) for details). When released, installation will be simplified to:
```bash
# This feature is not yet available
/plugin marketplace add SuperClaude-Org/superclaude-plugin-marketplace
/plugin install superclaude
```
**Status**: In development. No ETA has been set.
### **Enhanced Performance (Optional MCPs)**
For **2-3x faster** execution and **30-50% fewer tokens**, optionally install MCP servers:
```bash
# Optional MCP servers for enhanced performance (via airis-mcp-gateway):
# - Serena: Code understanding (2-3x faster)
# - Sequential: Token-efficient reasoning (30-50% fewer tokens)
# - Tavily: Web search for Deep Research
# - Context7: Official documentation lookup
# - Mindbase: Semantic search across all conversations (optional enhancement)
# Note: Error learning available via built-in ReflexionMemory (no installation required)
# Mindbase provides semantic search enhancement (requires "recommended" profile)
# Install MCP servers: https://github.com/agiletec-inc/airis-mcp-gateway
# See docs/mcp/mcp-integration-policy.md for details
```
**Performance Comparison:**
- **Without MCPs**: Fully functional, standard performance β
- **With MCPs**: 2-3x faster, 30-50% fewer tokens β‘
---
## π **Support the Project**
> Hey, let's be real - maintaining SuperClaude takes time and resources.
>
> *The Claude Max subscription alone runs $100/month for testing, and that's before counting the hours spent on documentation, bug fixes, and feature development.*
> *If you're finding value in SuperClaude for your daily work, consider supporting the project.*
> *Even a few dollars helps cover the basics and keeps development active.*
>
> Every contributor matters, whether through code, feedback, or support. Thanks for being part of this community! π
### **Your Support Enables:**
| Item | Cost/Impact |
|------|-------------|
| π¬ **Claude Max Testing** | $100/month for validation & testing |
| β‘ **Feature Development** | New capabilities & improvements |
| π **Documentation** | Comprehensive guides & examples |
| π€ **Community Support** | Quick issue responses & help |
| π§ **MCP Integration** | Testing new server connections |
| π **Infrastructure** | Hosting & deployment costs |
> **Note:** No pressure though - the framework stays open source regardless. Just knowing people use and appreciate it is motivating. Contributing code, documentation, or spreading the word helps too! π
---
## π **What's New in v4.1**
> *Version 4.1 focuses on stabilizing the slash command architecture, enhancing agent capabilities, and improving documentation.*
### π€ **Smarter Agent System**
**20 specialized agents** with domain expertise:
- PM Agent ensures continuous learning through systematic documentation
- Deep Research agent for autonomous web research
- Security engineer catches real vulnerabilities
- Frontend architect understands UI patterns
- Automatic coordination based on context
- Domain-specific expertise on demand
### β‘ **Optimized Performance**
**Smaller framework, bigger projects:**
- Reduced framework footprint
- More context for your code
- Longer conversations possible
- Complex operations enabled
### π **Documentation Overhaul**
**Complete rewrite** for developers:
- Real examples & use cases
- Common pitfalls documented
- Practical workflows included
- Better navigation structure
### π§ͺ **Enhanced Stability**
**Focus on reliability:**
- Bug fixes for core commands
- Improved test coverage
- More robust error handling
- CI/CD pipeline improvements
---
## π¬ **Deep Research Capabilities**
### **Autonomous Web Research Aligned with DR Agent Architecture**
SuperClaude v4.2 introduces comprehensive Deep Research capabilities, enabling autonomous, adaptive, and intelligent web research.
### π― **Adaptive Planning**
**Three intelligent strategies:**
- **Planning-Only**: Direct execution for clear queries
- **Intent-Planning**: Clarification for ambiguous requests
- **Unified**: Collaborative plan refinement (default)
