Superpowers for Claude Code: what it changes

What the Superpowers plugin for Claude Code changes

The Superpowers plugin for Claude Code stops Claude from going straight to code. Instead, it follows a fixed loop. It brainstorms the design and opens a git worktree. Then it writes a plan in tasks of 2 to 5 minutes, carries out the plan with test-driven development (TDD), and finishes the branch. The plugin is a set of agent skills plus one startup hook. Jesse Vincent wrote it, and it is published as obra/superpowers under the MIT license.

The loop produces code that has been reviewed more carefully. It also uses more of your plan allowance, because planning and review are extra model turns. This guide shows how to install the plugin and what each step does. It also shows how to measure the cost on your own Pro or Max plan before you turn it on for every session.

How Superpowers works inside a session

Superpowers is a plugin. A plugin is a package that can add skills, subagents, hooks and MCP (Model Context Protocol) servers to Claude Code. If these terms are new, read how Claude Code plugins are packaged and loaded first.

Most of Superpowers is skills. A skill is a folder that holds a SKILL.md file. At the start of a session, Claude Code loads only the skill's short description. It reads the full file only when a task matches that description. What agent skills are and how they load on demand explains this model.

One part is not a skill: a SessionStart hook. The hook runs on the startup, clear and compact events and adds the using-superpowers instructions to the conversation. Those instructions tell Claude to look for a matching skill before it does anything. This is why the plugin changes Claude's behaviour without you typing a command. The hook runs again after every /clear and every compaction, so the instructions come back each time.

Install Superpowers from the official marketplace

Start Claude Code in a project and run:

/plugin install superpowers@claude-plugins-official

Inside a session, this command does not install the plugin straight away. It opens the /plugin panel on the plugin's details page. Read the Will install list, then choose a scope. User scope turns the plugin on in every project on this machine. Local scope turns it on in the current repository only. Local scope is the safer first choice while you decide whether you want the plugin.

Claude Code adds the official marketplace for you the first time you start an interactive session. On a fresh machine where you install from a setup script, add the marketplace first. Then install from the shell:

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install superpowers@claude-plugins-official --scope local

When the shell install works, it prints Successfully installed plugin: superpowers@claude-plugins-official. The plugin loads the next time a session starts.

Check the version and the always-on cost

The repository does not publish tagged releases. The version string in your plugin list is the only reliable record of what you ran, so write it down next to any result you keep.

claude plugin list
claude plugin details superpowers

For each plugin, claude plugin list prints a Version line, a Scope line and a Status line. claude plugin details prints an Always-on line. This is the number of tokens the plugin adds to every session where it is enabled. Rows for each component follow. The Always-on figure is your fixed cost per session before any skill runs.

To check that the hook works, start a fresh session and send Let's make a react todo list. The project README says that a working install starts the brainstorming skill before Claude writes any code. If Claude starts writing components at once, the plugin is not loaded. Open the Errors tab in /plugin to see why.

The loop it enforces, step by step

Brainstorm. Claude asks you questions about what you want to build. Then it shows the design in short sections, and you approve each one. Claude saves the approved design as a document. Expect several turns before any file changes.

Worktree. After you approve the design, the using-git-worktrees skill creates a new branch in a separate working directory. It uses .worktrees/ at the project root unless you have named another location. Before it creates the worktree, it must check that git ignores the directory:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees

If git does not ignore the directory, the skill adds it to .gitignore and commits that change. Next it installs dependencies and runs the test suite, to prove that the starting point is clean. If the baseline tests fail, the skill stops and asks whether to continue.

Plan. The writing-plans skill splits the work into tasks of 2 to 5 minutes. Each task lists exact file paths, the code to write, and a step that checks the result. Read this plan carefully. It is the cheapest place to fix a wrong direction, because nothing has been built yet.

Execute. Here you choose between two skills, and this choice decides most of the cost. subagent-driven-development gives each task to a fresh implementer subagent. A reviewer subagent then checks the result against the plan and checks the code quality. After the last task, one final review covers the whole branch. executing-plans does every task inline, in your current session, followed by one fresh review of the whole branch. The README calls inline mode the cheapest.

TDD. While the plan runs, the test-driven-development skill enforces red, green, refactor. Claude writes a test, runs it and watches it fail. Then it writes the smallest piece of code that makes the test pass. Code that was written before its test is deleted.

Finish. The finishing-a-development-branch skill runs the full test suite. If the tests pass, Claude offers three choices. It can merge into the base branch locally, push the branch and open a pull request, or keep the branch for later. A local merge runs the tests again on the merged result. If they pass, it removes the worktree and deletes the branch.

What subagent mode costs against a Pro or Max allowance

On a Pro or Max plan you do not pay per token. Instead, you use up a five-hour allowance and a weekly allowance. Every subagent sends its own requests, and each subagent starts with a fresh context. In subagent mode, every task therefore runs at least twice: once to build it and once to review it. Each round of fixes adds more requests. How Claude Code token usage adds up explains why starting a fresh context is expensive.

The skill states the trade-off itself. Subagent mode gives "a fresh context per task and per review". Inline mode gives "one context plus one final reviewer". The skill also tells Claude to choose a model for each subagent. A cheap, fast model handles simple tasks that touch one file. The most capable model does the final branch review. Which models it picks changes the cost as much as which mode you choose.

Online you will find figures that claim large savings or large extra costs. Treat any such figure as one person's result on one codebase. If you quote it, name its source. The only figure that answers the question for your plan is one you measure yourself.

Measure inline against subagent mode on one task

Pick one small, real task that has clear tests, for example "add input validation to one function". Run it twice from the same commit, once in each mode. Keep the model and the effort level the same for both runs. Record the plugin version from claude plugin list.

1. Run /clear, then /usage. Write down the plan usage bars before you start.
2. Go through the brainstorm and the plan. Approve the same plan text in both runs.
3. At the execute step, tell Claude to use executing-plans for the first run and subagent-driven-development for the second.
4. When the branch is finished, run /usage again. Write down how much the bars moved. Also read the Attribution rows, which show the share of usage that went to skills, subagents, plugins and MCP servers.
5. Write the date next to the result. Plan limits and models change, so a result without a date is not useful later.

The attribution figures are approximate. They cover only sessions on this machine, so usage from claude.ai or from another device is not included. For an exact token count on one run, sign in with an API key and read the Session block at the top of /usage. It lists input, output and cache tokens for each model.

When to leave Superpowers off

A one-line fix does not need a design document, a worktree and a review subagent. With the plugin on, Claude still starts the loop. You then spend several turns brainstorming a change you could check by reading it. The same is true for throwaway spikes, where you only want to learn whether an idea works before you delete the code.

For that kind of work, disable the plugin, then enable it again afterwards:

claude plugin disable superpowers@claude-plugins-official
claude plugin enable superpowers@claude-plugins-official

Changing plugins inside a running session can invalidate the prompt cache, so Claude Code warns you before it reloads. Make the change between sessions. For a contrasting approach that favours doing less, see the Ponytail lazy senior dev agent.

Run a long unattended session under tmux on a VPS

The README says it is "not uncommon" for an agent to work for a couple of hours on an approved plan. On a laptop, that run stops when you close the lid. On a VPS it keeps going inside tmux, a terminal multiplexer that keeps your session alive after you disconnect. Running Claude Code on a VPS with tmux covers the full server setup.

tmux new -s superpowers
cd ~/projects/myapp
claude

Stay attached for the brainstorm and the plan, because those steps need your answers. When execution starts, press Ctrl-b and then d to detach. To reattach later, run:

tmux attach -t superpowers

An unattended run stops and waits at every permission prompt, so decide in advance what Claude may do without asking. Auto mode and Claude Code permission settings covers those choices. A long run in subagent mode can also reach the five-hour limit before it finishes. What to do when you reach the Claude usage limit explains how to wait for the reset and then continue.

Superpowers in Codex, Cursor and Gemini CLI

The same skills also install in other coding agents. In the Codex app, open Plugins in the sidebar and add Superpowers from the Coding section. In Cursor, run /add-plugin superpowers. In Gemini CLI, run:

gemini extensions install https://github.com/obra/superpowers

Each agent runs subagents and counts usage in its own way. A cost you measure in Claude Code does not apply to the other agents.

FAQ

How do I know the Superpowers plugin is actually active?

Start a fresh session and ask for a small app, such as Let's make a react todo list. With a working install, Claude starts the brainstorming skill and asks you questions before it writes any code. If Claude writes code at once, run claude plugin list and check the Status line. Then open the Errors tab in /plugin.

Does Superpowers use more of my Claude Pro or Max usage?

In most cases, yes. It adds a fixed always-on cost to every session, which claude plugin details superpowers reports. It also adds turns for planning and for review. Subagent mode costs more than inline mode, because each task gets a fresh context for the implementer and another for the reviewer. Measure both modes on one task with /usage before you choose a default.

Which execution mode should I pick, inline or subagent-driven?

Pick inline execution (executing-plans) when the tasks depend on each other, or when you are close to your usage limit. The project README calls inline mode the cheapest. Pick subagent-driven-development when the tasks are mostly independent and you want each one reviewed before the next one starts.

How do I turn Superpowers off for a quick fix?

Before you start the session, run claude plugin disable superpowers@claude-plugins-official in your shell. When you want the plugin back, run claude plugin enable superpowers@claude-plugins-official. Disabling it inside a running session can invalidate the prompt cache, so it is cheaper to switch between sessions.