SuperClaude — Workflow Framework for Claude Code

What SuperClaude Adds to Claude Code

SuperClaude is a community configuration framework that bolts a full opinionated workflow onto Anthropic's Claude Code CLI. According to the official SuperClaude_Framework repository, one pipx install plus SuperClaude install writes 16+ slash commands, 9 cognitive personas, an MCP server bundle, and a smart-flag system into your ~/.claude/ directory in under 60 seconds. The framework adds zero runtime daemons; every command and persona is plain Markdown that Claude Code reads natively.

Claude Code itself is a terminal-based agentic coding tool released by Anthropic in February 2025 (see Anthropic's Claude Code overview). Out of the box, Claude Code ships with a handful of built-in slash commands and no opinionated workflow scaffolding. SuperClaude fills that exact gap: it ships curated commands like /build, /troubleshoot, /improve, /document, /explain, and /test, each tuned for real engineering tasks rather than toy demos. The result is a consistent surface across machines, projects, and teammates.

The install is idempotent. Re-running SuperClaude install will refresh the bundled commands without nuking your local edits, because the updater performs a 3-way merge against the existing ~/.claude/ tree. That property matters: it lets you fork any persona file, tweak a system prompt, and still pull upstream changes without hand-resolving every conflict.

Quick Install: pipx in Two Commands

The canonical install path uses pipx, the Python tool installer recommended by the Python Packaging Authority for isolating CLI applications. The README documents exactly two commands:

pipx install SuperClaude
SuperClaude install
# or upgrade later
SuperClaude install --update

That is the entire setup. The first command pulls SuperClaude into its own pipx-managed virtualenv so it cannot collide with system Python packages. The second command writes the framework's Markdown command definitions, persona files, MCP wiring, and a top-level CLAUDE.md profile into ~/.claude/. According to the official README, a clean install completes in well under one minute on a typical broadband connection.

If you want to refresh the framework without losing local customisations, run SuperClaude install --update. The 3-way merge logic is documented in the project README and follows the same pattern used by tools like dotbot and chezmoi: upstream additions land, your local edits survive, and conflicts are flagged interactively.

16+ Slash Commands, Tuned for Real Engineering

Slash commands in Claude Code are a documented extension surface. As Anthropic's Claude Code documentation explains, any Markdown file under ~/.claude/commands/ automatically becomes a callable /<name> slash command inside the CLI. SuperClaude leverages exactly that mechanism — the installer writes 16+ Markdown files into that directory, no plugin loader required.

The shipped command set includes:

• /build — opinionated build, lint, and bundle pipeline runner.
• /troubleshoot — structured root-cause analysis with hypothesis tracking.
• /improve — refactor pass focused on readability and dead-code removal.
• /document — generates docstrings, README sections, and architecture notes.
• /explain — line-by-line walkthrough mode for unfamiliar code.
• /test — scaffolds unit tests and runs the existing suite with focused output.

Because every command is plain Markdown, you can fork the file, tighten the system prompt to your team's conventions, and check the result into your dotfiles. That is dramatically lighter than authoring a custom plugin and re-publishing to a registry.

9 Cognitive Personas: Same Model, Different Behavior

The most distinctive feature is the persona pack. SuperClaude ships 9 swappable personas — architect, frontend, backend, security, mentor, refactorer, qa, performance, and analyzer — that change how Claude approaches your task. Each persona is a separate file under ~/.claude/personas/; deleting a file removes that persona, editing it changes behavior, and forking lets you ship internal variants.

Personas are conceptually similar to the agent definitions described in Anthropic's Building Effective Agents post — they constrain tool use, response style, and decision boundaries without changing the underlying model. The architect persona, for example, biases toward upfront design discussion and ADR-style outputs, while the refactorer persona biases toward minimal-diff edits and dead-code detection.

This pattern composes well with the flag system: --think enables more deliberative chain-of-thought scaffolding, --plan forces an explicit step list before execution, and --uc (ultra-compressed) trims response verbosity for token-budget-sensitive sessions. Flags are orthogonal to commands, so /build --think and /troubleshoot --plan --uc are both valid combinations. The flag layer is what makes the 16+ commands behave like a small DSL rather than a flat catalog.

Architecture: Plain Markdown, No Daemon

SuperClaude is intentionally boring at the architecture layer. As the README states, it is a Python CLI distributed via pipx that writes static Markdown into ~/.claude/. There is no background daemon, no service to babysit, no secondary process tree. Claude Code reads the directory at startup and treats every file as a first-class extension.

This design has three concrete benefits:

1. Auditability — every persona and command is human-readable Markdown you can git diff and code review. There is no compiled artifact to reverse-engineer.
2. Portability — the entire framework state lives in one directory. You can rsync ~/.claude/ to another machine and have an identical environment in seconds.
3. Resilience — because there is no runtime daemon, there is nothing to crash, nothing to restart, and nothing to debug at the process layer.

MCP wiring is the one piece that touches external services. SuperClaude pre-configures a set of Model Context Protocol servers — sequential thinking, context retrieval, and search — that the bundled commands expect. MCP is Anthropic's open protocol for connecting LLMs to external tools and data, formally described in the MCP specification. SuperClaude does not author MCP servers itself; it simply wires the commonly-needed ones into your ~/.claude/ config so the shipped commands work out of the box.

Step-by-Step: From Zero to First Command

The following ordered procedure takes you from a fresh machine to running your first SuperClaude command. Every step references the official prompt template shipped with this skill.

1. Install pipx if you do not already have it. On macOS, brew install pipx followed by pipx ensurepath is the standard route. On Linux, use your distribution's package manager or python3 -m pip install --user pipx.
2. Install SuperClaude with pipx install SuperClaude. This creates an isolated virtualenv and exposes the SuperClaude command on your $PATH.
3. Run the installer: SuperClaude install. The installer writes Markdown command definitions, persona files, and a top-level CLAUDE.md profile into ~/.claude/. On clean directories this completes silently; on directories with existing customisations the installer prompts before merging.
4. Verify the install with ls ~/.claude/commands/ — you should see 16+ Markdown files, one per slash command.
5. Launch Claude Code in any project directory and type /build or /troubleshoot to confirm the new commands appear in the slash-command palette.
6. Layer flags by appending --think, --plan, or --uc to any shipped command, e.g. /improve --plan.
7. Update later with SuperClaude install --update. The 3-way merge preserves your edits while pulling new commands and personas.

Comparison: SuperClaude vs Alternatives

The key differentiator is that SuperClaude lives inside Claude Code rather than replacing it. Aider is an alternative CLI; AutoGen and CrewAI are multi-agent orchestration frameworks (different problem space); Cursor Rules are tied to the Cursor IDE. SuperClaude is the only option that curates and versions a complete persona-and-command pack for the official Anthropic CLI.

Self-Hosting, Updates, and Uninstall

The self-hosting story is deliberately minimal. SuperClaude has a single hard dependency: a working claude CLI installation. The framework itself adds no servers, no databases, and no background processes. Configuration lives entirely under ~/.claude/.

Three operational properties matter:

• Idempotent install — SuperClaude install is safe to re-run. It refreshes commands without trampling your customisations.
• In-place edits — every command and persona is Markdown. Open the file, change the prompt, save. The change takes effect on the next Claude Code invocation.
• Clean uninstall — SuperClaude uninstall removes only the files the installer placed. Anything you authored by hand stays put.

Forking the framework is intentionally easy. Because all command and persona definitions are open Markdown, teams routinely fork the GitHub repo, replace the prompts with internal conventions, and re-publish their own flavor under a different pipx package name. The 3-way merge update path means downstream forks can still pull upstream changes without resolving every conflict by hand.

When to Pair SuperClaude with Other Workflows

SuperClaude is a productivity layer, not a multi-agent orchestrator. For multi-agent fan-out, pair it with Claude Flow. For continuous PR review automation, layer it on top of the babysit auto-respond workflow. For real-time token cost tracking, run ccusage alongside it. Each of these workflows is curated on TokRepo and links cleanly into the same ~/.claude/ directory that SuperClaude manages.

In day-to-day use, the most common pattern is: SuperClaude provides the command surface and personas, ccusage watches token spend, Claude Flow handles parallel sub-agent execution, and Ralph Wiggum-style autonomous loops handle long-running iterative tasks. None of these tools conflict; they each occupy a different layer of the ~/.claude/ extension surface.

Why a Configuration Framework Beats Hand-Rolled Dotfiles

You can technically replicate SuperClaude by hand-authoring 16+ Markdown files and 9 persona definitions yourself. Many engineers start there. The reasons most converge on a curated framework are familiar from the broader dotfiles community:

• Versioning — SuperClaude tags releases on GitHub; hand-rolled configs drift.
• Discovery — new commands and personas appear in upstream releases; hand-rolled configs require you to write everything yourself.
• Update mechanics — the 3-way merge is non-trivial to implement; rolling your own update path is a project of its own.
• Community review — every shipped prompt has been read and critiqued by the SuperClaude community; your private prompts have not.

The trade-off is opinionation. SuperClaude has views on how slash commands should be structured, how personas should constrain behavior, and which MCP servers belong in the default bundle. If those views match yours, the framework saves weeks of authoring work. If they do not, the Markdown-first design makes forking trivial.