Origin & relationship to upstream.
superclaudestarted as a fork of SuperClaude_Framework (Kazuki Nakai, NomenAK, Mithun Gowda B). It has since diverged β different MCP set, insight pipeline, scope-explicit install, tightened workflow gates β and is no longer a downstream of upstream. The two projects share neither roadmap nor maintainers.
| Commands | Agents | Modes | MCP Servers |
|---|---|---|---|
| 36 | 23 | 8 | 4 |
| Slash | Domain-expert | Behavioral | Integrations |
36 slash commands cover the development lifecycle from brainstorming to deployment. 8 behavioral modes auto-load on matching flags and keywords.
superclaude is a content framework for Claude Code: a directory of markdown (commands, agents, modes, MCP docs, core rules) plus a small CLI / pytest plugin that installs that content into Claude Code's content directories β ~/.claude/ (user), ./.claude/ (project, committed), or ./.claude/ (local, personal β kept out of git through the clone's .git/info/exclude).
Claude Code reads those files at session start, which is how the framework changes its behavior. There is no runtime engine, no daemon, no proxy.
Disclaimer. This project is not affiliated with or endorsed by Anthropic, nor by the upstream SuperClaude Framework. Claude Code is built and maintained by Anthropic.
Essential reading when working in this repo:
| File | Purpose |
|---|---|
CLAUDE.md |
Project-specific rules: env (UV), make targets, how to run the tests, git workflow |
src/superclaude/ARCHITECTURE.md |
Content-framework taxonomy β directory roles, delivery pipelines, content types |
src/superclaude/CLAUDE_SC.md |
The always-loaded import chain β core/FLAGS.md, PRINCIPLES.md, RULES.md |
.claude/rules/ |
Authoring specs for agents/commands/modes |
.claude/rules/gotchas/ |
Project-specific traps (e.g. do not Read sub-agent *.output files) |
SECURITY.md |
Security disclosure policy |
Claude Code auto-loads
CLAUDE.mdand thecore/import chain at session start, so the rules apply to every interaction inside this repo.
superclaude ships markdown content (commands, agents, modes, MCP docs, core rules, hooks) plus a small CLI that copies it into Claude Code's content directories.
git clone https://github.com/ajitta/superclaude.git
cd superclaude
# Editable uv tool install β `superclaude` becomes available globally.
make deploy
# Equivalent without make:
# uv tool install --force --editable .superclaude install # default: --scope user (~/.claude/, global)
superclaude install --scope project # team-shared, committed to ./.claude/
superclaude install --scope local # personal-in-team-repo (./.claude/, kept out of git via
# .git/info/exclude; settings.local.json + CLAUDE.local.md)
superclaude install --force # overwrite an existing install
superclaude install -i # interactive wizard (scope β preview β confirm)
superclaude install --list # show available components, install nothing
superclaude install --list-all # show every component + its install statusWhat gets installed (per scope):
<scope>/
βββ commands/sc/ # 36 slash commands (/sc:plan, /sc:implement, β¦)
βββ agents/ # 23 agent definitions
βββ superclaude/ # core rules, modes, mcp docs
βββ hooks/hooks.json # SessionStart / PreCompact / SessionEnd / etc.
βββ settings(.local).json # framework hooks merged in (your existing hooks preserved)
Every hook command is superclaude hook <name> β no interpreter path, no script copy β so a project-scope settings.json is the same bytes on every machine and can be committed. A reinstall over an older release rewrites its <python> β¦/<script>.py registrations to that form. Runtime state (.claude/.superclaude_hooks/, pending insights) stays out of git through the clone's .git/info/exclude, never your .gitignore.
Serena prerequisite. Serena's CLI is not installed by
superclaudeβ install it yourself first per upstream's installation guide (uvx/pipx).superclaude mcponly handles MCP registration + recommended hooks.
superclaude mcp # interactive picker (default scope: user)
superclaude mcp --list # list available servers
superclaude mcp --servers tavily playwright
superclaude mcp --servers serena # register Serena (CLI must already be installed)
superclaude mcp --scope project # write to ./.mcp.json (team-shared)
superclaude mcp --scope local # per-project block inside ~/.claude.jsonSerena init/stale-entry issues? See
docs/troubleshooting/serena-installation.md.
superclaude install --list-all # component-by-component status
superclaude doctor # pytest plugin, hooks, CLAUDE_SC import, `superclaude` on PATH
superclaude verify-drift # detect drift between source and installed copy
superclaude versionRestart Claude Code, then try a few:
/sc:brainstormβ Socratic discovery for vague requests/sc:planβ Detailed TDD implementation plans/sc:implementβ Code implementation/sc:reviewβ Multi-dimensional review (code/plan/design)/sc:researchβ Deep web research (Tavily-enhanced)/sc:insightβ Capture structured session insights to JSONL/sc:helpβ List all 36 commands
superclaude update # default: --scope user
superclaude update --scope project # (update takes --scope only; use `install --force` to re-copy everything)superclaude uninstall --dry-run # preview, no changes
superclaude uninstall # default: --scope user, asks to confirm
superclaude uninstall -y # skip confirmation
superclaude uninstall --scope project # remove from ./.claude/
superclaude uninstall --scope local # also removes CLAUDE.local.md + its .git/info/exclude block
superclaude uninstall --keep-settings # leave settings.json hooks alone
superclaude uninstall --remove-mcp # also unregister framework-installed MCP servers
# (default keeps them β they're shared with other tools)The uninstall is marker-based: it removes only the hooks and the @superclaude/CLAUDE_SC.md import that the installer wrote. User-added hooks, MCP servers, and CLAUDE.md content are preserved unless you explicitly opt out.
| Command | Scopes | Default |
|---|---|---|
superclaude install / update / uninstall |
user, project, local |
user |
superclaude mcp |
user, project, local |
user |
| Scope | Path | When to use |
|---|---|---|
user |
~/.claude/ |
Personal global install (default β daily use) |
project |
./.claude/ (committed) |
Team-shared, checked into git |
local |
./.claude/ (kept out of git via .git/info/exclude) |
Personal install inside a team repo (uses settings.local.json, CLAUDE.local.md) |
For contributors/developers:
# Initial setup (editable mode for development)
uv pip install -e ".[dev]"
# Development cycle
uv run superclaude install --list-all # Test changes immediately
uv run pytest tests/ -v # Run tests
# Deploy CLI as a global uv tool (editable). Content sync is a separate step.
make deploy
# Sync framework content to a scope (force-sync β for headless `claude -p`)
make sync-user # β ~/.claude/ (global, recommended for daily use)
make sync-project # β ./.claude/ (team-shared, committed)
make sync-local # β ./.claude/ (local-only, excluded from git per clone)
# Verify installation
uv tool list # List installed tools
which superclaude # Check install path (Linux/Mac)
where superclaude # Check install path (Windows)| Stage | Command | Description |
|---|---|---|
| Dev/Test | uv run superclaude ... |
Test in repo (editable) |
| Deploy CLI | make deploy |
uv tool install --force --editable . |
| Sync content | make sync-user / sync-project / sync-local |
Force-sync markdown/scripts to chosen scope |
| Use | superclaude ... |
Run from anywhere |
| Uninstall | make uninstall-user / uninstall-project / uninstall-local |
Scope-explicit removal |
The framework is fully functional without any MCP server. Each one adds a capability its flag switches on:
- Serena β symbol-level code navigation and edits, plus cross-session project memory (
--serena,/sc:load,/sc:save) - Tavily β web search / extract / crawl / research. Recommended as Agent Skills (
npx skills add tavily-ai/skills); the MCP server is the optional in-conversation alternative (--tavily) - Context7 β official documentation lookup, enabled as a claude.ai connector rather than through
superclaude mcp(--c7) - Playwright, Chrome DevTools β browser automation and performance audits (
--play,--perf)
Source of truth for each server's usage: src/superclaude/mcp/MCP_*.md and src/superclaude/mcp/README.md.
rtk-ai/rtk is a single Rust binary that transparently rewrites common Bash commands (git status, pnpm install, pytest, β¦) into compact, LLM-friendly output β typically 60β90% token reduction on routine ops. Independent project; not bundled with superclaude.
# Install (pick one)
brew install rtk # macOS / Linux (Homebrew)
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh # Linux / macOS
cargo install --git https://github.com/rtk-ai/rtk # Cargo
# Windows: download from https://github.com/rtk-ai/rtk/releases (WSL recommended)
# Verify
rtk --version
rtk gain # token-savings stats
# Enable Claude Code auto-rewrite hook (transparent β no prompt changes needed)
rtk init -g # restart Claude Code after running thisOnce the hook is active, Claude's
git statuscalls run asrtk git statusautomatically. Without the hook, prefix manually (rtk <cmd>).
thedotmack/claude-mem is a memory-compression layer for Claude Code that automatically captures and recalls context across sessions. Independent project; complements superclaude's /sc:load + insight pipeline by storing observations queryable via the mem-search skill. Requires Node.js β₯18.
# Install (pick one)
npx claude-mem install # standard CLI install
# Or via Claude Code plugin marketplace:
# /plugin marketplace add thedotmack/claude-mem
# /plugin install claude-mem
# After install: restart Claude Code
# Web viewer: http://localhost:37777
# Settings: ~/.claude-mem/settings.json (auto-created)Past observations show up at session start (
# $CMEMblock). Query with themem-searchskill orget_observations([IDs]).
The framework's value comes from chaining commands. Each chain has gates: a step's output must be committed (or explicitly approved) before the next step runs. Pick the chain that matches the task's blast radius β don't pay brainstorm-level overhead for a typo, and don't skip design for a system rewrite.
| Tier | Trigger | Recommended chain |
|---|---|---|
| Trivial | Typo Β· 1-line fix Β· rename Β· obvious bug with known fix | Direct edit. No /sc:* needed. |
| Small | Single file Β· β€ 50 added lines Β· clear scope | /sc:implement (or /sc:improve) --plan β /sc:test |
| Medium | 3β10 files Β· multi-purpose Β· clear requirements | /sc:plan β /sc:implement --plan β /sc:test β /sc:reflect |
| Large | > 10 files Β· cross-cutting Β· ambiguous scope Β· new system | /sc:brainstorm β /sc:design β /sc:review β /sc:plan β /sc:implement --plan β /sc:test β /sc:reflect |
/sc:brainstorm β /sc:design β /sc:review β /sc:plan β /sc:implement --plan β /sc:test β /sc:reflect
discover specify gate decompose build (TDD) verify learn
(Socratic) (architecture) (multi-lens) (phases) (per task) (baseline) (capture)
| Step | Output | Hard gate before next step |
|---|---|---|
/sc:brainstorm |
docs/features/<slug>/01-discovery.md (one-off: docs/specs/<slug>-discovery-<user>-<date>.md) |
User approves discovery spec |
/sc:design |
docs/features/<slug>/04-design.md (one-off: docs/specs/β¦-design-β¦md) |
Design committed (components pass the [R18] necessity test) |
/sc:review |
Multi-dimensional review of design/plan | Required β /sc:brainstorm hard-blocks /sc:plan until this runs |
/sc:plan |
docs/features/<slug>/05-plan.md (one-off: docs/plans/β¦md) β phased TDD tasks, file paths, verify cmds |
Plan committed |
/sc:implement --plan |
Code + per-phase commits | Implementation complete |
/sc:test |
Test pass evidence (42/42 pass, baseline 40) |
Real output, not predictions |
/sc:reflect |
Retrospective + insights captured to .claude/insights.jsonl |
β |
| Goal | Chain |
|---|---|
| Investigate a bug | /sc:troubleshoot β /sc:analyze --focus <domain> β /sc:implement --plan β /sc:test |
| Performance work | /sc:analyze --focus perf --scope module β /sc:improve --loop --focus perf β /sc:test |
| Security audit | /sc:analyze --focus security β /sc:review β /sc:improve --focus security |
| Refactor | /sc:analyze --focus quality β /sc:plan β /sc:improve --loop β /sc:test |
| External research | /sc:research --depth deep --tavily --c7 β /sc:reflect |
| Codebase onboarding | /sc:load β /sc:index-repo β /sc:explain |
| Strategy / market | /sc:business-panel β /sc:reflect |
| End of branch | /sc:review β /sc:test β /sc:git (commit + PR) |
- Skip steps when the input already exists. If you already have a written spec, jump straight to
/sc:plan. The gates exist to prevent skipping unfinished work, not to force ceremony. --planflag on/sc:implementmakes it consume a committed plan document. Without--plan, it works from the latest message./sc:reviewscores two dimensions β fidelity to the spec and quality of the artifact β and groups findings as Critical / Important / Suggestion. Treat its output as a checklist, not a verdict.--audit-delegatedre-examines only the decisions the model made on your behalf./sc:reflectwrites insights to.claude/insights.jsonlwhich/sc:loadlater reads β over time the framework remembers what worked.
superclaude builds on the original SuperClaude_Framework by Kazuki Nakai, NomenAK, and Mithun Gowda B. To support that upstream project's authors directly, see their channels on the upstream repo β sponsorship goes to them, not to this fork.
This fork is a personal, opinionated reshape of the framework: different MCP set, insight pipeline, scope-explicit deploy, tightened workflow gates. It is not maintained by the upstream authors.
An insight pipeline, scope-explicit deployment, and tightened brainstorm β plan β implement β review workflow gates.
|
Rules that must hold are enforced by hooks, not prose:
Every hook runs as |
23 specialized agents with domain expertise:
|
|
Curated and lean by default (no token bloat): # List available MCP servers
superclaude mcp --list
# Install specific servers
superclaude mcp --servers tavily playwright
# Interactive installation
superclaude mcpAvailable servers:
|
8 adaptive modes for different contexts:
|
|
|
Brainstorm β Plan β Implement β Review:
|
|
Separate CLI deploy from content sync:
|
Settings-merge install + targeted hooks:
|
Autonomous web research aligned with the DR agent architecture β adaptive planning, multi-hop reasoning, confidence-scored synthesis.
|
Three intelligent strategies:
|
Up to 5 iterative searches:
|
|
Confidence-based validation:
|
Research memory through Serena:
|
# Basic research with automatic depth
/sc:research "latest AI developments 2026"
# Controlled depth β pass flags after the query
/sc:research "quantum computing breakthroughs" --depth exhaustive
# Strategy selection: planning | intent | unified (default)
/sc:research "market analysis" --strategy planning
# Pick the sources explicitly
/sc:research "React patterns" --tavily --c7| Depth | Sources | Hops | Time | Confidence target | Best For |
|---|---|---|---|---|---|
| Quick | 10 | 1 | ~2min | 0.6 | Quick facts, simple queries |
| Standard | 20 | 3 | ~5min | 0.7 | General research (default) |
| Deep | 40 | 4 | ~8min | 0.8 | Comprehensive analysis |
| Exhaustive | 50+ | 5 | ~10min | 0.9 | Academic-level research |
Profiles are defined in modes/RESEARCH_CONFIG.md.
The Deep Research system intelligently coordinates multiple tools:
- Tavily (Agent Skills; MCP optional): Primary web search and discovery
- Playwright MCP: Complex content extraction
- Serena MCP: Memory and learning persistence
- Context7 (claude.ai connector): Technical documentation lookup
docs/archive/holds the upstream-derived legacy tree and is not maintained. The rest ofdocs/βfeatures/,adr/,research/,agents/β is this project's own. The table below names the source of truth per topic.
| Topic | Source of truth |
|---|---|
| Architecture & directory roles | src/superclaude/ARCHITECTURE.md |
| Project rules, build & test loop | CLAUDE.md |
| Project-specific gotchas | .claude/rules/gotchas/ |
| Serena MCP troubleshooting | docs/troubleshooting/serena-installation.md |
| Slash commands (36) | src/superclaude/commands/ Β· superclaude install --list-all |
| Agents (23) | src/superclaude/agents/ |
| Modes (8) | src/superclaude/modes/ |
| MCP servers (4) | src/superclaude/mcp/ |
| Hooks (registry + scripts) | src/superclaude/cli/hook_dispatch.py Β· src/superclaude/hooks/hooks.json Β· src/superclaude/scripts/ |
| Architecture decisions | docs/adr/ |
| Feature work (discovery β plan β retrospective) | docs/features/ |
| Agent conventions (issue tracker, triage labels, domain docs) | docs/agents/ |
| Core rules (always-loaded) | FLAGS.md Β· PRINCIPLES.md Β· RULES.md |
| Authoring specs for new content | .claude/rules/ |
| Health & drift checks | superclaude doctor Β· superclaude verify-drift Β· superclaude audit Β· superclaude context explain / reset |
Flags are behavioral hints that any /sc:* prompt accepts. The model reads them inline β no setup, no separate config. SSOT: src/superclaude/core/FLAGS.md.
| Flag | When to use | Effect |
|---|---|---|
--brainstorm |
Vague request, "maybe", unclear scope | Collaborative discovery, probing questions before code |
--research |
Need evidence, citations, external knowledge | Systematic investigation, evidence-based reasoning |
--business-panel |
Strategy/market/competitive analysis | Multi-expert business analysis & synthesis |
--introspect |
Stuck, error recovery, "why is it doing X?" | Surfaces decision logic, assumptions and alternatives (π―β‘ππ‘ markers) |
--task-manage |
>3 steps Β· >2 dirs Β· >3 files | Hierarchical task organization + persistent memory checkpoints |
--orchestrate |
Multi-tool, parallel, perf-sensitive | Tool-matrix optimization |
--token-efficient / --uc |
Context β₯ 60 % or large ops (auto with --safe-mode) |
Selective omission β drop what does not change the next action; never compress what stays |
--vs [standard|cot|multi] |
"Multiple perspectives", brainstorm options | Verbalized sampling β probability-weighted candidates. Sub-params: [k:3-7] [tau:0.01-0.20] [turns:2-5] [no-synthesis] |
| Flag | Server | Use for |
|---|---|---|
--c7 / --context7 |
Context7 | Imports, frameworks, official docs |
--serena |
Serena | Symbol ops, project memory, semantic exploration |
--play / --playwright |
Playwright | Browser testing, E2E, visual diffs |
--perf / --devtools |
Chrome DevTools | Perf audit, CLS, LCP, metrics |
--tavily |
Tavily | Web search, real-time info, parallel queries |
--frontend-verify |
Combined | Playwright + DevTools + Serena (UI debug) |
--all-mcp / --no-mcp |
β | Enable all / disable all (perf priority) |
| Flag | Effect |
|---|---|
--delegate [auto|files|folders] |
Sub-agent parallel delegation. Decision matrix: RULES_DELEGATION.md <sub_agent_decision> |
--concurrency [n] |
Batch independent tool calls (1β15) into a single message |
--loop |
Iterative improvement β repeat until no meaningful improvement found |
--iterations [n] |
Fixed iteration count β exactly N cycles, with per-iteration delta report |
--plan |
5-line plan (goal Β· approach Β· files Β· risks Β· verification) before execution |
--validate |
Pre-execution risk assessment (risk > 0.7, prod) |
--safe-mode |
Max validation, conservative behavior, auto --uc |
--verbose-context |
Force full .md injection (bypass short-instruction map) |
| Flag | Values |
|---|---|
--scope |
file Β· module Β· project Β· system |
--focus |
perf Β· security Β· quality Β· arch Β· a11y Β· testing |
Priority when flags conflict:
--safe-mode>--validate> optimization Β· explicit user flags > auto-detection Β·--no-mcpoverrides individual MCP flags.
Retired flags (
--think*,--parallel,--seq/--sequential) get a redirect notice rather than a rewrite. An unrecognized flag is matched by difflib similarity β not edit distance β first against retired names (cutoff 0.8), then against valid ones (cutoff 0.6), and the closest become a suggestion comment. Nothing is silently rewritten:context_loader.pyships an empty alias table.
/sc:research "Rust async runtime tradeoffs" --depth deep --tavily --c7
/sc:implement "user export endpoint" --plan --validate --delegate auto
/sc:analyze src/auth/ --focus security --scope module
/sc:improve src/api/handlers.py --loop --iterations 3 --serena
/sc:brainstorm "should we migrate to gRPC?" --vs multiMIT β see LICENSE.
Click to expand full command list
/sc:brainstormβ Structured brainstorming through Socratic dialogue/sc:designβ System architecture, APIs, component interfaces/sc:planβ Detailed implementation plans with TDD tasks/sc:estimateβ Time/effort estimation/sc:spec-panelβ Multi-expert specification review/sc:roadmapβ Phased implementation workflow from a PRD or feature doc
/sc:implementβ Code implementation/sc:buildβ Build workflows/sc:improveβ Code improvements/sc:cleanupβ Refactoring & dead-code removal/sc:explainβ Code explanation
/sc:testβ Run tests with coverage and quality reporting/sc:analyzeβ Code analysis (quality, security, perf, arch)/sc:troubleshootβ Diagnose & resolve issues/sc:reflectβ Task retrospectives/sc:reviewβ Multi-dimensional review of work products
/sc:documentβ Doc generation/sc:promote-featureβ Consolidate standalone docs into a feature folder/sc:helpβ Command help
/sc:gitβ Git operations with intelligent commits
/sc:pmβ Project management & sub-agent orchestration/sc:taskβ Task tracking/sc:auto-improveβ Autonomous metric-driven improvement loop
/sc:researchβ Deep web research/sc:business-panelβ Multi-expert business analysis
/sc:loadβ Load session context (Serena + auto memory)/sc:saveβ Save session context/sc:insightβ Capture structured insights to JSONL
/sc:agentβ Session controller: investigate β implement β review orchestration/sc:initβ Interactive project environment setup/sc:index//sc:index-repoβ Repository indexing (94% token reduction)/sc:recommendβ Command recommendation engine/sc:promptβ Rewrite a prompt for Claude Opus 5 / Fable 5.1/sc:select-toolβ Intelligent MCP tool selection/sc:scβ Command dispatcher (routes to the other/sc:*commands)
Source files: src/superclaude/commands/ β each command is a single markdown file with frontmatter. After install, run superclaude install --list-all for a full inventory.