/troubleshooting

Troubleshooting

Common issues with Superpowers and how to resolve them.

This page lists common issues with Superpowers and their solutions. If you don’t find your issue here, check the GitHub issues or Discord community.

Installation issues

Plugin not found in marketplace

Symptom: Searching for “superpowers” returns no results.

Solution: Ensure you’ve added the correct marketplace:

/plugin marketplace add obra/superpowers-marketplace

Then search again. If using Claude Code’s official marketplace, try:

/plugin install superpowers@claude-plugins-official

Install fails with permission error

Symptom: Installation fails with EPERM or permission denied.

Solution: Check that your coding agent has permission to write to its plugin directory. For Claude Code:

ls -la ~/.claude/plugins/

If the directory doesn’t exist or isn’t writable, create it:

mkdir -p ~/.claude/plugins/
chmod 755 ~/.claude/plugins/

Skills not triggering

Agent writes code immediately

Symptom: You ask for a feature and the agent starts coding without brainstorming.

Causes and solutions:

1. Plugin not active: Verify installation with /plugin list
2. Existing design document: Check if design.md or similar exists in your project
3. Session not fresh: Some platforms require a new session after plugin install
4. Other plugins interfering: Disable other plugins temporarily

Worktree not created

Symptom: Implementation happens on main branch instead of isolated worktree.

Solution: Check that your project is a git repository:

git status

Superpowers requires git to create worktrees. If not in a git repo, initialize one:

git init
git add .
git commit -m "Initial commit"

Test-driven development issues

Agent skips writing tests

Symptom: The agent writes feature code without a failing test first.

Solution: The TDD skill should prevent this. If it doesn’t:

1. Verify the skill is loaded: Ask the agent “What skills do you have loaded?”
2. Check that you’re in the implementation phase (after planning)
3. Explicitly say: “Follow TDD: write the test first”

Tests pass on first run

Symptom: The test passes immediately, suggesting it doesn’t actually test the feature.

Solution: This is a common TDD anti-pattern. The agent should verify the test fails first. If it doesn’t:

1. Ask the agent to confirm the test actually exercises the feature
2. Request that the test fail before implementation
3. Check the test for false positives (empty asserts, wrong setup)

Subagent issues

Subagents not spawning

Symptom: The agent executes all tasks itself instead of dispatching subagents.

Solution: Not all platforms support subagents. Check your platform:

If your platform has limited support, the agent will use executing-plans instead.

Subagents deviate from plan

Symptom: Subagents do work not specified in the plan.

Solution: The subagent-driven-development skill includes context isolation to prevent this. If it happens:

1. Check the plan was specific enough (exact file paths, clear tasks)
2. Verify the skill is current: /plugin update superpowers
3. Report the deviation in a GitHub issue with the plan and what happened

Platform-specific issues

OpenCode: Bootstrap not injecting

Symptom: Skills don’t trigger in OpenCode sessions.

Solution: The OpenCode install requires fetching from a remote URL. Verify:

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

If issues persist, check that OpenCode is version 1.3.2 or later (required for the bootstrap fix).

Cursor: Plugin commands not recognized

Symptom: /add-plugin superpowers doesn’t work.

Solution: Ensure you’re in Agent chat mode, not regular chat. The plugin system only works in Agent mode.

Copilot CLI: Tool mapping issues

Symptom: Copilot CLI doesn’t recognize Superpowers tools.

Solution: Copilot CLI uses different tool names. The skill includes a tool mapping table in references/copilot-tools.md. Ensure you’re on Copilot CLI v1.0.11 or later.

Hook issues

SessionStart hook not firing

Symptom: New sessions don’t inject Superpowers context.

Solution: Check hook installation:

ls -la ~/.claude/hooks/
# or for your platform's hook directory

You should see session-start or similar. If missing, reinstall the plugin.

Windows: Console window appears on SessionStart

Symptom: On Windows, a terminal window briefly appears when starting/resuming sessions.

Solution: This was a known issue with the polyglot wrapper. It was fixed in v5.0.7. Update your plugin:

/plugin update superpowers

If the issue persists on Git Bash/MSYS2, ensure you’re on the latest version.

Performance issues

Slow skill loading

Symptom: Commands take a long time to execute.

Solution: Skills are Markdown files loaded into context. If you have many skills or large files:

1. Check skills/ directory size: du -sh skills/
2. Remove any custom skills you’re not using
3. Ensure you’re not loading unrelated documentation as skills

Subagent timeouts

Symptom: Subagents timeout or hang.

Solution: Subagents inherit timeouts from the parent platform. If tasks consistently timeout:

1. Make plans with smaller tasks (2-5 minutes each)
2. Check for infinite loops in test suites
3. Verify network access for external API calls

Where to get help

If your issue isn’t covered here:

1. GitHub Issues: https://github.com/obra/superpowers/issues
2. Discord: https://discord.gg/35wsABTejz for community support
3. Release notes: Check RELEASE-NOTES.md for known issues in recent versions

When reporting issues, include:

• Platform (Claude Code, Cursor, etc.)
• Superpowers version
• Steps to reproduce
• Expected vs actual behavior
• Any error messages