Installation flaky when plugin name conflicts with claude-plugins-official (upstream Claude Code bug)

[gwpl]

Summary

This is an informational tracking issue to help users who encounter flaky plugin installation when using superpowers-marketplace.

This is NOT a bug in this repository - it's an upstream Claude Code issue. Creating this issue here because:

• No Discussions section available
• Users searching for "superpowers install" issues may find this helpful
• Can serve as a place to collect workarounds and track upstream fixes

The Problem

The superpowers plugin exists in both claude-plugins-official AND superpowers-marketplace. When Claude Code's plugin installer encounters this, it may:

1. Match on plugin name only, ignoring the marketplace qualifier
2. Report the wrong marketplace in error messages
3. Refuse to install even with fully-qualified name

Example error:

❯ /plugin install superpowers@superpowers-marketplace
  ⎿  Plugin 'superpowers@claude-plugins-official' is already installed. Use '/plugin' to manage
     existing plugins.

Note: User requested @superpowers-marketplace but error refers to @claude-plugins-official.

This particularly affects users installing plugins on a per-repository basis (project/local scope). The behavior is flaky - sometimes works, sometimes doesn't.

Upstream Issues (Claude Code)

• Problem hypothesis: [BUG] Plugin install matches wrong marketplace when same plugin name exists in multiple marketplaces anthropics/claude-code#20593
• Related scope issues: Bug: Project-scoped plugins incorrectly detected as installed globally anthropics/claude-code#14202

Verified Workaround

Manual editing of ~/.claude/plugins/installed_plugins.json + creating .claude/settings.json with enabledPlugins works:

// Add to installed_plugins.json array for the plugin
{
  "scope": "local",
  "projectPath": "/path/to/new/project",
  "installPath": "~/.claude/plugins/cache/superpowers-marketplace/superpowers/4.0.3",
  "version": "4.0.3",
  "installedAt": "2026-01-24T00:00:00.000Z",
  "lastUpdated": "2026-01-24T00:00:00.000Z"
}

// Create .claude/settings.json in project
{
  "enabledPlugins": {
    "superpowers@superpowers-marketplace": true
  }
}

After restarting Claude Code, the plugin appears correctly in the Installed tab.

Detailed workaround with code snippets: anthropics/claude-code#14202 (comment)

Resolution

Kind suggestion on closing criteria for issue:

• Upstream Claude Code issues are fixed, OR
• A TROUBLESHOOTING.md or FAQ.md is added to this repo with this information

---

Note: This issue was created to help other users who may encounter this problem. Feel free to add additional workarounds or information in comments.

[gwpl]

Workaround available:

The fix involves manually editing a couple of JSON config files. However, if you're adding the plugin per-repository on-demand, doing this manually each time is tedious and error-prone.

Automated script for convenience:
https://gist.github.com/gwpl/cd6dcd899ca0acce1b4a1bc486d56a9e

curl -fsSL 'https://gist.githubusercontent.com/gwpl/cd6dcd899ca0acce1b4a1bc486d56a9e/raw/fix-superpowers-plugin.py' -o /tmp/fix-superpowers-plugin.py && chmod +x /tmp/fix-superpowers-plugin.py && /tmp/fix-superpowers-plugin.py

Safety features built-in:

• ✅ Creates .bak.YYYY-MM-DD--HH-MM-SS backups before any modification
• ✅ Verifies marketplace registration and plugin cache exist
• ✅ Interactive mode asks for confirmation at each step
• ✅ --dry-run to preview without changes
• ✅ --verbose for debugging
• ✅ Supports scopes: project-local (default), project-shared, user

Usage options:

./fix-superpowers-plugin.py              # Interactive (default)
./fix-superpowers-plugin.py -y           # Non-interactive
./fix-superpowers-plugin.py --dry-run    # Preview only

Easy to revert from backup if needed. Convenient workaround until upstream fix arrives.

[gwpl]

Update: Seeing people using it for more plugins, turned it into a repo: https://github.com/shibuido/claude-plugin-install