Back
Superpowers Tutorial Series Developer Tools

Superpowers Tutorial 1: Install & Setup (Claude Code / Cursor / Codex / OpenCode)

Step-by-step installation and setup of Superpowers on Claude Code, Cursor, Codex, and OpenCode—covering how it works, how to verify it’s active, and how to troubleshoot the most common "not working" issues.

Tutorial Overview

Series index: Superpowers Tutorial Series

This is the first article in the Superpowers tutorial series. It walks you through a from-scratch installation and setup. No matter which platform you use, you’ll find the corresponding setup path here.

What you’ll learn

  • ✅ How Superpowers works at a high level
  • ✅ How to install Superpowers on 4 mainstream platforms
  • ✅ How to verify the installation
  • ✅ How to troubleshoot common issues

What is Superpowers?

Superpowers is an agentic skills framework. In practice, it’s a curated set of prompts and workflow rules that guide AI coding assistants to follow proven engineering practices.

Key characteristics

  1. Auto-triggering — skills activate based on context; you don’t have to invoke them manually
  2. Enforced workflow — not suggestions, but required steps the assistant should follow
  3. Composable — multiple skills can work together
  4. Platform-agnostic — supports Claude Code, Cursor, Codex, and OpenCode

Workflow at a glance

flowchart TD
    A[User requests a feature] --> B{brainstorming}
    B --> C[Explore requirements and design]
    C --> D{writing-plans}
    D --> E[Create an implementation plan]
    E --> F{subagent-driven-development}
    F --> G[Execute tasks + code review]
    G --> H{verification-before-completion}
    H --> I[Verify completion]
    
    style B fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff
    style H fill:#e1f5ff

Before You Install

System requirements

Platform Requirements
Claude Code An active Claude subscription
Cursor Cursor IDE v0.40+
Codex OpenAI Codex access
OpenCode OpenCode CLI

Git configuration

Make sure Git is configured correctly:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Platform 1: Install on Claude Code

Step 1: Add the marketplace

Run this in Claude Code:

/plugin marketplace add obra/superpowers-marketplace

Step 2: Install the plugin

/plugin install superpowers@superpowers-marketplace

Step 3: Verify

Start a new session and ask:

Help me plan a new feature

If the AI starts by clarifying requirements instead of jumping straight into code, the installation worked.

Method B: Manual install

If the Marketplace isn’t available:

# Clone the repository
git clone https://github.com/obra/superpowers.git ~/.superpowers

# Load it in Claude Code
/plugin load ~/.superpowers

Update the plugin

/plugin update superpowers

Platform 2: Install on Cursor

Steps

Step 1: Open Cursor

Launch Cursor IDE and open the Agent chat panel.

Step 2: Install the plugin

In Agent chat:

/plugin-add superpowers

Step 3: Confirm

Cursor will download and install from the marketplace. When it’s done, you’ll see a confirmation message.

In Cursor settings, make sure these are enabled:

  • ✅ Agent Mode
  • ✅ Auto-accept suggestions (optional; recommended to keep OFF at first)
  • ✅ Git integration

Verify the installation

Open a project and ask in Agent chat:

I want to add a user login feature

If the Agent starts asking about:

  • authentication method (email/phone/OAuth)
  • session management strategy
  • security requirements

then the brainstorming skill is triggering correctly.

Platform 3: Install on Codex

Installation prompt

Tell Codex:

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

Detailed docs

See the official docs: docs/README.codex.md

Custom configuration

Create ~/.codex/config.yaml:

superpowers:
  enabled: true
  auto_trigger: true
  skills:
    - brainstorming
    - writing-plans
    - test-driven-development
    - systematic-debugging

Platform 4: Install on OpenCode

Installation prompt

Tell OpenCode:

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

Detailed docs

See the official docs: docs/README.opencode.md

Environment variables

# ~/.bashrc or ~/.zshrc
export SUPERPOWERS_ENABLED=true
export SUPERPOWERS_AUTO_TRIGGER=true

Verify Your Installation

Test case 1: brainstorming triggers

Input:

I want to add a comment system to my blog

Expected behavior:

  • ❌ Immediately starts writing comment UI code → Fail
  • ✅ Starts asking clarifying questions (provider choice, moderation policy, storage) → Pass

Test case 2: TDD triggers

Input:

Implement a Fibonacci function

Expected behavior:

  • ❌ Implements the function directly → Fail
  • ✅ Writes tests first → Pass

Test case 3: Git worktree triggers

Input:

Start implementing the comment feature we just designed

Expected behavior:

  • ❌ Modifies the current branch directly → Fail
  • ✅ Creates a new worktree and branch → Pass

Troubleshooting

Issue 1: Skills don’t trigger

Symptom: The AI jumps straight into code and no skills trigger.

Checklist:

  1. Confirm the plugin is loaded:

    /plugin list

  2. Confirm using-superpowers is active.

  3. Try an explicit trigger:

    Use the brainstorming skill to plan this feature

  4. Restart the session.

Issue 2: Installation fails

Symptom: The install command errors.

Fix:

# Clear cache
rm -rf ~/.cache/superpowers

# Reinstall
# Claude Code
/plugin install superpowers@superpowers-marketplace --force

# Cursor
# Remove the plugin in settings and add it again

Issue 3: Skill conflicts

Symptom: Multiple skills trigger at once and behavior becomes chaotic.

Fix: Disable unneeded skills in config:

# ~/.superpowers/config.yaml
skills:
  enabled:
    - brainstorming
    - writing-plans
    - test-driven-development
  disabled:
    - subagent-driven-development  # temporarily disable

Issue 4: Git worktree fails

Symptom: Errors when creating a worktree.

Fix:

# Check Git version (requires 2.5+)
git --version

# Clean up stale worktrees
git worktree prune

# Manually test worktrees
git worktree add ../test-worktree -b test-branch

Best Practices

1. Adopt gradually

Don’t enable everything on day one. A common progression:

Week 1: brainstorming + writing-plans
Week 2: + test-driven-development
Week 3: + systematic-debugging
Week 4: + code review skills

2. Customize configuration

Tune parameters based on project type:

# Rapid prototyping
superpowers:
  mode: rapid-prototyping
  skip_code_review: true
  
# Production projects
superpowers:
  mode: production
  require_tests: true
  require_code_review: true

3. Team adoption

For teams:

  1. Standardize a shared config
  2. Do periodic skill retros
  3. Maintain an internal best-practices doc

Performance Tuning

Limit subagents

If compute is limited, cap parallel subagents:

subagent:
  max_concurrent: 2
  timeout_minutes: 30

Cache design docs

brainstorming outputs can be cached to avoid repeating the same discussions:

brainstorming:
  cache_enabled: true
  cache_ttl_hours: 24

Next Up

After installation, continue with:

References

Running into issues? Leave a comment or ask in GitHub Issues!

Series navigation:

Last updated on Mar 26, 2026 00:00 UTC