Skip to content
Get packs

Guide · Open source

How to use Superpowers: install it and run your first coding agent workflow

Updated · written with AI from the project's own documentation and checked against our catalogue data

Superpowers is an open-source software development methodology for AI coding agents, built from reusable skills and instructions that make the agent use them. It runs as a plugin inside a supported coding agent tool, not as a standalone app. This guide shows you how to install it, what the basic workflow looks like, and when it fits your work.

Superpowersobra/superpowers · ★ 311k · MIT

Quick start

  1. 1Confirm your coding agent is supported. Superpowers only works as a plugin for a listed harness such as Claude Code, Codex, Cursor or Gemini CLI. Check the README list before you start.
  2. 2Install the plugin for your agent. Run the install command from the README for your tool, such as the /plugin install line for Claude Code.
  3. 3Restart active sessions. Restart any open sessions so the plugin and its hooks take effect.
  4. 4Start a fresh session. Open a new session in your coding agent so the bootstrap loads from the start.
  5. 5Describe what you want to build. Explain the goal in plain language. The agent will ask questions before writing code.
  6. 6Approve the design. Read the spec in the short chunks the agent shows you and correct anything that is wrong.
  7. 7Review the implementation. After you say go, the agent works through the plan task by task. Check its progress and review its work.

What Superpowers does before it writes code

When you start building something, Superpowers makes the agent stop and ask what you are trying to do instead of jumping straight into code. Once the agent has worked out a spec from the conversation, it shows you the design in short chunks you can read and correct.

After you approve the design, the agent writes an implementation plan and works through each task, inspecting and reviewing its own work as it goes. The README says the plan emphasizes red/green TDD, YAGNI and DRY, and that the agent can sometimes work autonomously for a couple of hours without deviating from the plan.

  • brainstorming: activates before building anything and draws out what you want and why.
  • using-git-worktrees: activates after design approval and creates an isolated workspace on a new branch.
  • Skills trigger automatically, so you do not need to invoke them by hand.

Install Superpowers for your coding agent

Installation differs by harness, and you install Superpowers separately for each tool you use. The README lists commands for many agents; the examples below are the ones given for Claude Code, Gemini CLI and Hermes Agent.

Use the README's install instructions for your specific agent, since the commands are not the same across tools.

  • Claude Code (official marketplace): run /plugin install superpowers@claude-plugins-official inside Claude Code.
  • Gemini CLI: run gemini extensions install https://github.com/obra/superpowers and update later with gemini extensions update superpowers.
  • Hermes Agent: run hermes plugins install obra/superpowers --enable, then restart any active Hermes sessions.
  • Other listed harnesses include Antigravity, Codex App, Codex CLI, Cursor, Devin CLI, Factory Droid, GitHub Copilot CLI, Grok Build CLI, Kimi Code, OpenCode, Pi, Qwen Code and Muse.
/plugin install superpowers@claude-plugins-official

Run your first workflow

Start a session in your coding agent and describe the thing you want to build. Superpowers is designed so you do not need to do anything special: the skills trigger on their own once the agent sees you are building something.

The Muse section of the README gives a simple check: start a fresh session and send a request such as a React todo list. With a working install, the brainstorming skill should run before any code is written.

  • Describe what you want in plain language.
  • Answer the agent's questions about the goal.
  • Review the design in the short chunks it shows you.
  • Say go once you approve the design, then review the agent's progress.

Keep Superpowers up to date

Update commands depend on the harness. The README gives update commands for some tools, for example Devin CLI, Gemini CLI, Qwen Code and Muse. For Antigravity, reinstalling with the same command updates the plugin.

Restart active sessions after installing or updating so hooks take effect.

  • Gemini CLI: gemini extensions update superpowers
  • Qwen Code: qwen extensions update superpowers
  • Devin CLI: devin plugins update superpowers
gemini extensions update superpowers

Troubleshoot when skills stop triggering

The README notes a limitation for Hermes Agent: it has no post-compaction hook, so a very long session that compacts over its first turn can lose the bootstrap. The fix it suggests is to start a fresh session.

If skills stop triggering in another harness, first check that you installed Superpowers for that specific tool, since installs are separate per harness.

  • Hermes: start a fresh session if skills stop triggering after a long session.
  • Restart active sessions after installing so the hooks take effect.
  • Install separately for each harness you use.

What people use it for

  • Planning a multi-task feature so the agent designs and writes an implementation plan before coding.
  • Having an agent follow test-driven development steps on a multi-step project.
  • Letting an agent work through an approved plan for a long stretch with less supervision.
  • Using the same skills across more than one supported coding agent, installed separately for each.

Frequently asked questions

Is Superpowers free to use?

Superpowers is released under the MIT licence, according to the project's listing. The README also mentions optional commercial services for enterprises, contacted by email, which are separate from the open-source project.

What do I need to install Superpowers?

You need a supported coding agent, such as Claude Code, Codex, Cursor, Gemini CLI or another listed harness. Superpowers is a plugin for those tools and does not run on its own.

How do I install Superpowers in Claude Code?

Run /plugin install superpowers@claude-plugins-official inside Claude Code. The README also lists a separate Superpowers marketplace that you can add with /plugin marketplace add obra/superpowers-marketplace.

Can I use Superpowers without a coding agent?

No. The project describes Superpowers as a plugin for coding agent tools rather than a standalone app, so you need one of the supported harnesses.

Why isn't my Superpowers skill triggering in a long Hermes session?

Hermes has no post-compaction hook, so a long session that compacts can lose the bootstrap. The README suggests starting a fresh session if skills stop triggering.

How does Superpowers compare to Aider, Cline or Continue?

The source does not compare these tools directly. Superpowers focuses on a methodology of design, planning, TDD and review skills inside a supported agent, so check each project's own documentation to compare features.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Superpowers suits developers who already use a supported coding agent and want it to design and plan before coding, then carry out multi-task work with reviews. It is a poor fit if you prefer writing code yourself step by step, or if you need a tool with a guaranteed outcome, since the README describes methodology and skills rather than measured results.

Install options & downloads