Skip to content
/
Tier B A2 Mirror cmd+skill

SuperClaude Framework

superclaude · SuperClaude-Org/SuperClaude_Framework · ★ 23k · last commit 2026-04-27

Meta-programming configuration framework that transforms Claude Code with 30 commands, 20 domain-specialist agents, and a PDCA self-improvement loop for systematic software development.

Best whenConfidenceChecker with numeric threshold (≥90%) prevents wrong-direction work before it starts, claiming 25-250x token savings by catching misaligned executi…
Skip ifSkipping confidence check before significant actions, Assumption-based infrastructure configuration (always use WebFetch for official docs)
vs seeds
bmad-method(Archetype 1 — full lifecycle via agent personas) but SuperClaude ships 30 slash commands in addition to 20 agents (BMAD…
Primitive shape 60 total
Commands 30 Skills 1 Subagents 20 Hooks 1 MCP tools 8
00

Summary

SuperClaude Framework — Summary

SuperClaude is a meta-programming configuration framework for Claude Code that installs 30 slash commands (/sc:*), 20 domain-specialist agents, 7 behavioral modes, and 8 MCP server configurations — all delivered as a Python package (pipx install superclaude) that writes markdown files to ~/.claude/commands/sc/ and ~/.claude/agents/.

Problem it solves: Claude Code out-of-the-box has no structured commands, personas, or methodology; SuperClaude injects a comprehensive set of domain-specialist behaviors (pm-agent, system-architect, security-engineer, etc.) and lifecycle commands (plan, implement, test, review, deploy) via behavioral instruction injection.

Distinctive trait: PM Agent with PDCA cycle + Serena MCP memory integration — the @pm-agent runs at EVERY session start, restores context from Serena MCP memory, and maintains a PDCA (Plan/Do/Check/Act) loop across sessions. Combined with a ConfidenceChecker requiring ≥90% confidence before execution, this creates a self-improving system that documents mistakes to prevent recurrence.

Target audience: Individual developers and teams using Claude Code who want a comprehensive development methodology (30 commands covering the full lifecycle) without building it themselves.

Production-readiness: Active and popular (23K stars, 30 contributors, v4.3.0, last pushed April 2026, MIT license, available on PyPI and npm).

Note on "70K-token CLAUDE.md" claim: The CLAUDE.md in this repo is 12,982 bytes (~13K chars) — not 70K tokens. The 70K claim appears to refer to earlier versions or the total combined token load of all installed files.

Differs from seeds: Most similar to BMAD-METHOD (Archetype 1 — skills/agents for full lifecycle) but SuperClaude ships 30 slash commands (not just skills), installs via Python CLI rather than npm, and adds the PM Agent self-improvement PDCA pattern, ConfidenceChecker (≥90% threshold), and explicit MCP server management — all absent from BMAD.

01

Overview

SuperClaude Framework — Overview

Origin

SuperClaude-Org (community organization), started as a framework to systematically enhance Claude Code. Currently at v4.3.0. Available on PyPI (superclaude) and npm (@bifrost_inc/superclaude). 23,009 GitHub stars, 30 contributors. MIT licensed.

Philosophy

SuperClaude is a "meta-programming configuration framework" — it doesn't modify Claude Code itself, but injects behavioral instructions via markdown files that Claude Code reads. The philosophy is that consistent, high-quality AI development requires:

  1. Domain specialist personas (20 agents) to apply the right mental model
  2. Workflow commands (30 commands) to structure each phase
  3. Self-improvement (PM Agent PDCA) to prevent recurring mistakes
  4. Confidence gating (ConfidenceChecker ≥90%) to prevent wrong-direction work

The 9 Domain Personas (from agents/)

Agent Category Purpose
@pm-agent meta Self-improvement executor with PDCA cycle + Serena MCP memory
@system-architect engineering Scalable system design, component boundaries
@backend-architect engineering API design, database architecture
@frontend-architect engineering UI/UX architecture, component design
@security-engineer engineering Vulnerability assessment, security architecture
@devops-architect engineering CI/CD, infrastructure, deployment
@performance-engineer engineering Bottleneck analysis, optimization
@quality-engineer engineering Test strategy, quality gates
@refactoring-expert engineering Code improvement, technical debt
@python-expert language Python best practices
@requirements-analyst analysis Requirements clarity, stakeholder analysis
@root-cause-analyst analysis Systematic root cause investigation
@deep-research-agent research Deep web research with Tavily
@deep-research research Research methodology
@technical-writer documentation Documentation, API docs
@learning-guide education Teaching, explanation
@socratic-mentor education Socratic questioning
@self-review quality Post-implementation self-critique
@repo-index tooling Repository indexing with Serena
@business-panel-experts business Business analysis panel

The 7 Behavioral Modes (from modes/)

Mode Purpose
MODE_Orchestration Tool selection mindset, parallel execution, resource management
MODE_Task_Management Task tracking with TodoWrite
MODE_DeepResearch Research with Tavily + web sources
MODE_Brainstorming Structured ideation
MODE_Business_Panel Business analysis + decision
MODE_Introspection Self-reflection and improvement
MODE_Token_Efficiency Token budget management

Three Core Python Patterns (from src/superclaude/pm_agent/)

  1. ConfidenceChecker: Pre-execution — ≥90% required, 70-89% present alternatives, <70% ask questions. Claims ROI: 25-250x token savings by preventing wrong-direction work.

  2. SelfCheckProtocol: Post-implementation evidence-based validation. No speculation — verify with tests/docs.

  3. ReflexionPattern: Error learning across sessions. Cross-session pattern matching for mistake prevention.

Manifesto-style quotes (from README)

"SuperClaude is a meta-programming configuration framework that transforms Claude Code into a structured development platform through behavioral instruction injection and component orchestration."

"Without MCPs: Fully functional, standard performance ✅. With MCPs: 2-3x faster, 30-50% fewer tokens ⚡"

02

Architecture

SuperClaude Framework — Architecture

Distribution

Python package on PyPI (superclaude) + npm package (@bifrost_inc/superclaude). Installs via pipx install superclaude && superclaude install.

Install

# Option 1: pipx (recommended)
pipx install superclaude
superclaude install              # installs 30 commands to ~/.claude/commands/sc/
superclaude mcp                  # interactive MCP server install

# Option 2: Git + script
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
./install.sh

# Verify
superclaude doctor

Directory Tree (installed to ~/.claude/)

~/.claude/
├── settings.json
├── commands/sc/              # 30 slash commands
│   ├── pm.md
│   ├── research.md
│   ├── implement.md
│   ├── test.md
│   ├── build.md
│   ├── design.md
│   ├── analyze.md
│   ├── brainstorm.md
│   ├── workflow.md
│   └── ... (30 total)
├── agents/                   # 20 domain-specialist agents
│   ├── pm-agent.md
│   ├── system-architect.md
│   ├── security-engineer.md
│   └── ... (20 total)
└── skills/
    └── confidence-check.md

# Python source (repo)
src/superclaude/
├── 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
├── commands/          # 30 .md command definitions
├── agents/            # 20 .md agent definitions
├── modes/             # 7 .md mode definitions
├── skills/            # installable skills
├── hooks/             # hooks.json
└── mcp/               # 10 MCP server configurations

Required Runtime

  • Python >= 3.10
  • pipx or pip
  • Claude Code (for using installed commands)

Target AI Tools

Claude Code (primary). The /sc:* commands are Claude Code slash commands.

Config Files

  • ~/.claude/settings.json — Claude Code settings
  • src/superclaude/hooks/hooks.json — SessionStart hook
  • pyproject.toml — pytest plugin entry point
03

Components

SuperClaude Framework — Components

Commands (30 total, installed to ~/.claude/commands/sc/)

Command Purpose
/sc:pm PM Agent activation, context restoration, PDCA
/sc:research Deep web research (enhanced with Tavily MCP)
/sc:brainstorm Structured brainstorming
/sc:implement Code implementation with persona activation
/sc:test Testing workflows
/sc:build Build + deployment
/sc:design System design
/sc:analyze Code analysis
/sc:explain Explanation + documentation
/sc:document Documentation generation
/sc:improve Code improvement
/sc:cleanup Code cleanup
/sc:refactor Refactoring
/sc:troubleshoot Debugging + troubleshooting
/sc:reflect Self-reflection + learning
/sc:workflow Workflow orchestration
/sc:task Task management
/sc:save State saving
/sc:load State loading
/sc:agent Agent activation
/sc:spawn Sub-agent spawning
/sc:index-repo Repository indexing
/sc:index Content indexing
/sc:recommend Recommendations
/sc:estimate Effort estimation
/sc:select-tool Tool selection
/sc:business-panel Business analysis panel
/sc:spec-panel Specification panel
/sc:git Git operations
/sc Show all commands

Agents (20 total, installed to ~/.claude/agents/)

Engineering: @system-architect, @backend-architect, @frontend-architect, @security-engineer, @devops-architect, @performance-engineer, @quality-engineer, @refactoring-expert, @python-expert

Analysis/Research: @requirements-analyst, @root-cause-analyst, @deep-research-agent, @deep-research

Documentation/Education: @technical-writer, @learning-guide, @socratic-mentor

Meta/Quality: @pm-agent, @self-review, @repo-index

Business: @business-panel-experts

Behavioral Modes (7, from src/superclaude/modes/)

MODE_Orchestration, MODE_Task_Management, MODE_DeepResearch, MODE_Brainstorming, MODE_Business_Panel, MODE_Introspection, MODE_Token_Efficiency

Python Package Components

Module Purpose
ConfidenceChecker Pre-execution confidence (≥90% to proceed)
SelfCheckProtocol Post-implementation validation
ReflexionPattern Cross-session error learning
TokenBudget Token budget management
parallel.py Wave→Checkpoint→Wave parallel execution (3.5x speedup)
reflection.py Self-correction after errors
pytest plugin Auto-loaded fixtures + markers for testing

Hooks (1)

  • SessionStart → ./scripts/session-init.sh — session initialization

MCP Servers (8-10 configurable)

Tavily (web search), Context7 (official docs), Serena (code understanding + memory), Sequential (token-efficient reasoning), Magic (UI generation), Playwright (browser testing), Mindbase (semantic conversation search), AIRIS Gateway (umbrella installer)

Skills (1 installable)

confidence-check — installable via superclaude install --skill confidence-check

pytest Integration

Auto-loaded via pyproject.toml entry point: 5 fixtures, 9 markers, auto-marks tests by directory (/unit/ → @pytest.mark.unit).

05

Prompts

SuperClaude Framework — Prompts

Excerpt 1: pm-agent.md — Session Start Protocol (verbatim)

File: src/superclaude/agents/pm-agent.md Technique: Lifecycle hook persona — PM Agent auto-activates every session, restores memory from Serena MCP, reports state to user. PDCA pattern with explicit memory write operations.

## Triggers
- **Session Start (MANDATORY)**: ALWAYS activates to restore context from Serena MCP memory
- **Post-Implementation**: After any task completion requiring documentation
- **Mistake Detection**: Immediate analysis when errors or bugs occur

## Session Start Protocol (Auto-Executes Every Time)

Context Restoration:
  1. list_memories() → Check for existing PM Agent state
  2. read_memory("pm_context") → Restore overall project context
  3. read_memory("current_plan") → What are we working on
  4. read_memory("last_session") → What was done previously
  5. read_memory("next_actions") → What to do next

User Report:
  Previous: [last session summary]
  Progress: [current progress status]
  Next: [planned next actions]
  Blockers: [blockers or issues]

Excerpt 2: system-architect.md — Agent Boundary Definition (verbatim)

File: src/superclaude/agents/system-architect.md Technique: Explicit Will/Will Not boundaries prevent persona drift — the agent knows exactly what falls outside its scope.

## Boundaries
**Will:**
- Design system architectures with clear component boundaries and scalability plans
- Evaluate architectural patterns and guide technology selection decisions
- Document architectural decisions with comprehensive trade-off analysis

**Will Not:**
- Implement detailed code or handle specific framework integrations
- Make business or product decisions outside of technical architecture scope
- Design user interfaces or user experience workflows

Excerpt 3: implement.md — Persona Activation Flow (verbatim)

File: src/superclaude/commands/implement.md Technique: Context-driven persona activation — the command selects which specialist agents to activate based on detected technology context.

## Behavioral Flow
1. **Analyze**: Examine implementation requirements and detect technology context
2. **Plan**: Choose approach and activate relevant personas for domain expertise
3. **Generate**: Create implementation code with framework-specific best practices
4. **Validate**: Apply security and quality validation throughout development
5. **Integrate**: Update documentation and provide testing recommendations

Key behaviors:
- Context-based persona activation (architect, frontend, backend, security, qa)
- Framework-specific implementation via Context7 and Magic MCP integration
- Systematic multi-component coordination via Sequential MCP

Excerpt 4: MODE_Orchestration.md — Resource Management Zones (verbatim)

File: src/superclaude/modes/MODE_Orchestration.md Technique: Traffic-light resource management — explicit green/yellow/red zones for context window usage.

## Resource Management

**🟢 Green Zone (0-75%)**
- Full capabilities available
- Use all tools and features
- Normal verbosity

**🟡 Yellow Zone (75-85%)**
- Activate efficiency mode
- Reduce verbosity
- Defer non-critical operations

**🔴 Red Zone (85%+)**
- Essential operations only
- Minimal output
- Fail fast on complex requests
09

Uniqueness

SuperClaude Framework — Uniqueness

Differs from Seeds

Most similar to BMAD-METHOD (Archetype 1 — skills/agents for full development lifecycle) but SuperClaude has three major deltas: (1) 30 slash commands — BMAD is skills-only (no commands); SuperClaude ships both commands AND agents; (2) Python CLI installer (superclaude install) vs BMAD's npm install; (3) PM Agent PDCA self-improvement loop — a unique pattern where the PM Agent documents mistakes to docs/mistakes/ and promotes successful patterns to docs/patterns/, creating a project-level learning system absent from BMAD. The ConfidenceChecker (≥90% threshold, 25-250x ROI claim) is also novel. Compared to claude-flow, SuperClaude has no SQLite/vector store, no hive-mind consensus, and no MCP bundle (it configures existing MCP servers rather than bundling 305 tools). Compared to superpowers (the seeds' primary skills framework), SuperClaude has far more components (30 cmds + 20 agents + 7 modes vs 14 skills + 0 commands) and explicit PM/PDCA layer.

Positioning

SuperClaude positions as "transform Claude Code into a structured development platform" — aimed at developers who want a comprehensive methodology pre-built rather than assembling one from primitives.

Distinctive Opinion

The ConfidenceChecker's numeric threshold (≥90%) is an opinionated design choice: rather than letting the AI decide when it's confident enough, SuperClaude encodes a specific number, making the gate inspectable and debatable.

On the "70K Token CLAUDE.md" Claim

The CLAUDE.md file in the repo is ~13K bytes. The 70K figure likely refers to the combined token load of all installed components when loaded into a Claude Code session context (30 commands + 20 agents + 7 modes + skills + settings). This is an important distinction — the framework's total context injection is much larger than any single file.

Observable Failure Modes

  1. Token load: Combined 30 commands + 20 agents + 7 modes in context window is significant overhead
  2. MCP dependency for full performance: Without Serena MCP, PM Agent memory and 2-3x performance improvements are unavailable
  3. Claude Code only: Unlike BMAD or superpowers, SuperClaude's slash commands work only in Claude Code (not Cursor, Gemini CLI, etc.)
  4. Install complexity: pipx + superclaude install + MCP install is a multi-step setup
  5. Version drift: v4.3.0 notes that a TypeScript plugin system (v5.0) is "in development" — current Python approach may be superseded
04

Workflow

SuperClaude Framework — Workflow

Session Start (Auto-Triggered)

Every Claude Code session, @pm-agent auto-activates:

  1. list_memories() → check Serena MCP for existing state
  2. read_memory("pm_context") → restore project context
  3. read_memory("current_plan") → restore current plan
  4. read_memory("last_session") → restore last session summary
  5. read_memory("next_actions") → restore next actions
  6. Report to user: Previous / Progress / Next / Blockers

Development Workflow

Step Command Agent/Mode Artifact
Research /sc:research @deep-research-agent + Tavily Research report
Brainstorm /sc:brainstorm MODE_Brainstorming Ideas document
Design /sc:design @system-architect Architecture doc
Implement /sc:implement @frontend/backend-architect + Context7/Magic Source files
Test /sc:test @quality-engineer + Playwright Test suite
Review /sc:reflect + @self-review @self-review Review report
Save /sc:save @pm-agent Serena MCP memory

PDCA Cycle (PM Agent)

Phase PM Agent Action Artifacts
Plan write_memory("plan", goal), create hypothesis doc docs/temp/hypothesis-*.md
Do write_memory("checkpoint") every 30 min, TodoWrite tracking docs/temp/experiment-*.md
Check think_about_task_adherence(), evaluate success criteria docs/temp/lessons-*.md
Act Promote success patterns → docs/patterns/, document mistakes → docs/mistakes/ Updated CLAUDE.md if global pattern

Confidence Check Flow

Before any significant action:
  confidence ≥ 90% → proceed
  70-89%            → present alternatives first
  < 70%             → ask clarifying questions

Approval Gates

  1. --safe flag on /sc:implement: extra confirmation before destructive changes
  2. ConfidenceChecker: blocks execution below 70% confidence
  3. Self-review: @self-review agent flags issues for human attention

Artifacts Per Phase

Phase Artifact
Research Research report (conversation)
Design Architecture document
Implementation Source files
PM Plan docs/temp/hypothesis-*.md
PM Check docs/temp/lessons-*.md
PM Act (success) docs/patterns/*.md
PM Act (failure) docs/mistakes/mistake-*.md
State Serena MCP memory
06

Memory Context

SuperClaude Framework — Memory & Context

Primary Memory: Serena MCP

PM Agent writes and reads from Serena MCP memory at every session start. Memory keys:

  • pm_context — overall project context
  • current_plan — what is being worked on
  • last_session — previous session summary
  • next_actions — planned next steps
  • checkpoint — in-session progress (written every 30 minutes)
  • summary — end-of-session outcomes
  • plan — current hypothesis/goal statement

Secondary Memory: File-Based Docs

Path Purpose
docs/temp/hypothesis-YYYY-MM-DD.md Plan phase — what to do and why
docs/temp/experiment-YYYY-MM-DD.md Do phase — trial/error log
docs/temp/lessons-YYYY-MM-DD.md Check phase — what worked/failed
docs/patterns/*.md Act phase — successful patterns (permanent)
docs/mistakes/mistake-YYYY-MM-DD.md Act phase — failure analysis + prevention

ReflexionMemory (Built-in)

The ReflexionPattern module provides cross-session error learning without requiring Serena MCP. Stores patterns of mistakes and prevention measures.

Context Compaction

Yes — MODE_Token_Efficiency and TokenBudget module manage context window usage. MODE_Orchestration implements traffic-light resource zones (green/yellow/red) for adaptive verbosity.

Parallel Execution (3.5x speedup)

parallel.py implements Wave → Checkpoint → Wave pattern:

  1. Fan-out: multiple independent reads/operations in parallel
  2. Checkpoint: aggregate results
  3. Fan-out again: parallel edits/writes

Cross-Session Handoff

Yes — Serena MCP memory persists across sessions. @pm-agent auto-restores context.

Memory Persistence Level

Global (Serena MCP) + Project (file-based docs).

Token Cost Note

With MCPs: 2-3x faster, 30-50% fewer tokens. Without MCPs: standard performance. The README explicitly quantifies this tradeoff.

07

Orchestration

SuperClaude Framework — Orchestration

Multi-Agent

Yes. 20 domain-specialist agents + /sc:spawn for on-demand sub-agent creation.

Orchestration Pattern

Hierarchical. PM Agent coordinates; /sc:implement activates domain specialists (architect, frontend, backend, security, qa) based on context detection. /sc:workflow enables sequential pipeline orchestration.

Execution Mode

Interactive-loop (commands triggered by user). PM Agent provides continuous background context via SessionStart.

Isolation Mechanism

None (in-place edits). Optional: git branches as convention.

Multi-Model

No explicit model routing — all agents use Claude Code's configured model. However, MCP integration (Context7, Sequential, Serena) offloads specific tasks to specialized tools, creating functional task routing.

Spawn Mechanism

Claude Code Task tool via /sc:spawn command and agent markdown files in ~/.claude/agents/.

Consensus Mechanism

None.

Prompt Chaining

Yes. /sc:research output → /sc:design → /sc:implement. PM Agent maintains chain via Serena MCP memory.

Crash Recovery

Yes — PM Agent restores context from Serena MCP at every session start. ReflexionMemory captures error patterns.

Context Compaction

Yes — explicit MODE_Token_Efficiency, TokenBudget module, traffic-light resource zones.

Parallel Execution

Yes — parallel.py implements Wave→Checkpoint→Wave: 3.5x faster with automatic dependency analysis for independent operations.

Session Lifecycle

SessionStart hook: ./scripts/session-init.sh runs at every session start.

Self-Correction

self_correction.py — reflection-based error correction. @self-review agent provides post-implementation critique.

08

Ui Cli Surface

SuperClaude Framework — UI / CLI Surface

CLI Binary

Yes. Binary: superclaude (installed via pipx/pip).

Subcommands:

  • superclaude install — install commands/agents/skills to ~/.claude/
  • superclaude install --list — list installed components
  • superclaude mcp — interactive MCP server installation
  • superclaude mcp --list — list available MCP servers
  • superclaude mcp --servers tavily context7 — install specific servers
  • superclaude doctor — health check diagnostics

Is thin wrapper: No — manages installation, component tracking, MCP configuration.

Local UI

None (no web dashboard). The 30 /sc:* slash commands are the primary interface — invoked in Claude Code chat.

IDE Integration

Claude Code (primary). Not compatible with other IDEs directly.

Observability

  • superclaude doctor — health diagnostics
  • docs/mistakes/ — mistake history for PM Agent
  • docs/patterns/ — success pattern library
  • Serena MCP memory — cross-session state

Scripts (1)

scripts/session-init.sh — triggered by SessionStart hook. Initializes session context.

Test Suite

  • 136 Python tests (tests/unit/ + tests/integration/)
  • Auto-markers via pytest plugin
  • Coverage via uv run pytest --cov=superclaude

Makefile

  • make dev — install editable mode with dev deps
  • make test — full test suite
  • make lint / make format — code quality
  • make doctor — health check
  • make build-plugin / make sync-plugin-repo — plugin packaging

Website

https://superclaude.netlify.app/

Related frameworks

same archetype · same primary tool · same memory type

Spec Kit ★ 106k
A2 Mirror cmd+skill

Turns a natural-language feature description into a complete, versioned, AI-executable specification pipeline installable for 30+…

OpenSpec ★ 51k
A2 Mirror cmd+skill

Adds a lightweight spec layer so AI coding assistants and humans agree on what to build before any code is written.

ECC (Everything Claude Code) ★ 193k
A2 Mirror cmd+skill

Comprehensive harness-native operator system: 246 skills + 61 agents + continuous learning hooks + multi-model routing across 8…

Gemini CLI (Google) ★ 105k
A2 Mirror cmd+skill

Bring the full power of Gemini into the terminal with a free tier, Google Search grounding, and extensible MCP support.

OpenAI Codex CLI ★ 86k
A2 Mirror cmd+skill

Give developers a sandboxed, locally-running OpenAI coding agent with approval gates and skill orchestration.

cursorrules v5 (kinopeee) ★ 1.1k
A2 Mirror cmd+skill

Bilingual (ja/en) Cursor rule set with tricolor task classification, security-first prompt injection defense, and structured git…