This page documents the installation process for Superpowers on OpenCode.ai. It covers the modern one-line configuration method, the underlying plugin implementation, and the automatic skill discovery mechanism.
Superpowers integrates with OpenCode via a JavaScript plugin that automates environment setup. Unlike previous versions that required manual symlinks, the current installation is handled by adding a single entry to your opencode.json configuration file. The plugin auto-installs via OpenCode's plugin manager and registers all skills automatically upon restart.
Sources: .opencode/INSTALL.md1-18 docs/README.opencode.md1-17
To install Superpowers, add the repository URL to the plugin array in your global or project-level opencode.json file.
To use a specific release or branch, append a fragment to the URL:
After modifying the file, restart OpenCode. The system will automatically fetch the repository and register the plugin hooks.
Sources: .opencode/INSTALL.md9-15 docs/README.opencode.md7-13 .opencode/INSTALL.md58-64
If you previously installed Superpowers using the manual git clone and symlink method, you must remove the old files to avoid conflicts with the new automated plugin.
Sources: .opencode/INSTALL.md25-38 docs/README.opencode.md24-36
The OpenCode integration is powered by .opencode/plugins/superpowers.js. This plugin performs two primary functions:
experimental.chat.messages.transform hook to inject the using-superpowers meta-skill into the first user message of every session [.opencode/plugins/superpowers.js124-138].config hook to dynamically add the plugin's skills/ directory to OpenCode's discovery path [.opencode/plugins/superpowers.js107-113].The following diagram maps the Natural Language requirements of the plugin to the specific code entities in the SuperpowersPlugin.
Title: "OpenCode Plugin Architecture and Entity Mapping"
Sources: .opencode/plugins/superpowers.js55-139 docs/README.opencode.md98-104
When a session starts, the plugin ensures the AI is aware of its "Superpowers" by reading the core meta-skill and prepending it to the first user message. This avoids token bloat associated with repeating system messages and prevents breaking models that only support a single system message [.opencode/plugins/superpowers.js115-123]. The plugin uses a module-level cache _bootstrapCache to eliminate redundant disk I/O on every agent step [.opencode/plugins/superpowers.js49-53].
Title: "Session Initialization and Bootstrap Injection Flow"
Sources: .opencode/plugins/superpowers.js49-138 docs/README.opencode.md98-104
OpenCode users should be aware that skills written for Claude Code use specific tool names. The OpenCode plugin provides a mapping layer to ensure compatibility with native OpenCode tools.
| Claude Code Action | OpenCode Tool | Implementation Detail |
|---|---|---|
| Invoke a skill | skill | Uses OpenCode's native skill tool [.opencode/INSTALL.md105] |
| Create/update todos | todowrite | Direct mapping [.opencode/INSTALL.md103] |
| Subagent (general) | task | Uses subagent_type: "general" [.opencode/INSTALL.md104] |
| Read files | read | Standard filesystem tool [.opencode/plugins/superpowers.js81] |
| Edit/Create/Delete | apply_patch | Standard file modification tool [.opencode/plugins/superpowers.js82] |
| Run shell command | bash | Standard shell tool [.opencode/plugins/superpowers.js83] |
| Search files | grep, glob | Standard search tools [.opencode/plugins/superpowers.js84] |
Sources: .opencode/INSTALL.md99-110 docs/README.opencode.md105-113 .opencode/plugins/superpowers.js76-87
After installation and restart, verify the setup by interacting with the agent:
using-superpowers content is injected into the session via getBootstrapContent [.opencode/plugins/superpowers.js62-97].use skill tool to list skills. You should see superpowers/brainstorming and other library skills in the list [docs/README.opencode.md42-49].opencode run --print-logs "hello" 2>&1 | grep -i superpowers [.opencode/INSTALL.md70]Sources: .opencode/INSTALL.md20 .opencode/INSTALL.md44-49 docs/README.opencode.md120-127
OpenCode resolves skills using a tiered priority system. If a skill name exists in multiple locations, the higher priority one is used:
.opencode/skills/ (Highest Priority) [docs/README.opencode.md79-81]~/.config/opencode/skills/ [docs/README.opencode.md58-62]This allows users to "shadow" or override standard Superpowers skills by placing a modified SKILL.md in their project or personal config directory.
Sources: docs/README.opencode.md56-81 .opencode/plugins/superpowers.js107-113