This page documents the technical implementation of Superpowers integration with OpenCode.ai. It covers the plugin architecture, bootstrap injection mechanism via experimental.chat.system.transform hook, native skill tool integration, and directory structure.
For installation instructions, see Installing on OpenCode. For the shared skill resolution logic used across platforms, see skills-core.js Shared Module. For general multi-platform architecture concepts, see Multi-Platform Integration.
The OpenCode integration consists of a single plugin file that hooks into OpenCode's system prompt transformation pipeline. Unlike Claude Code which uses a separate hooks system, OpenCode provides a native plugin API with hook support.
| Component | Location | Purpose |
|---|---|---|
| Plugin Module | .opencode/plugins/superpowers.js | Exports SuperpowersPlugin function with hook implementations |
| Bootstrap Content | skills/using-superpowers/SKILL.md | Meta-skill injected at session start |
| Skills Directory | skills/ | Symlinked to ~/.config/opencode/skills/superpowers/ |
| Core Library | lib/skills-core.js | Shared skill resolution functions (not used in bootstrap) |
Key Architecture Decision: The plugin injects bootstrap context via system prompt transformation rather than relying on OpenCode to discover and load the using-superpowers skill. This ensures the meta-skill is active before the agent's first response.
Sources: .opencode/plugins/superpowers.js1-96
OpenCode provides the experimental.chat.system.transform hook, which allows plugins to modify the system prompt before each request. Superpowers uses this to inject the using-superpowers skill content.
Diagram: Bootstrap Injection Flow
Sources: .opencode/plugins/superpowers.js86-94
The getBootstrapContent() function .opencode/plugins/superpowers.js56-84 performs the following steps:
skills/using-superpowers/SKILL.md relative to plugin location<EXTREMELY_IMPORTANT> tags to signal priorityInline Frontmatter Parser:
The plugin includes a minimal frontmatter parser .opencode/plugins/superpowers.js16-34 to avoid dependency on skills-core.js during bootstrap:
This parser handles basic YAML frontmatter without external dependencies, ensuring bootstrap always succeeds.
Sources: .opencode/plugins/superpowers.js56-84 .opencode/plugins/superpowers.js16-34
OpenCode provides a native skill tool for skill discovery and loading. Superpowers leverages this by symlinking skills into OpenCode's discovery path.
Diagram: Skill Discovery Architecture
Sources: docs/README.opencode.md230-236
OpenCode's native skill tool provides two primary operations:
| Command | Purpose | Example |
|---|---|---|
| List Skills | Discover all available skills across all priority levels | use skill tool to list skills |
| Load Skill | Read specific skill content for use in current context | use skill tool to load superpowers/brainstorming |
The agent can invoke these commands naturally through the skill tool, and OpenCode handles the directory scanning and content retrieval.
Sources: docs/README.opencode.md171-186 .opencode/INSTALL.md44-58
Diagram: OpenCode Installation Structure
Sources: docs/README.opencode.md20-42 .opencode/INSTALL.md10-34
The installation process creates symlinks in two strategic locations:
~/.config/opencode/plugins/superpowers.js → ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js~/.config/opencode/skills/superpowers → ~/.config/opencode/superpowers/skillsThis dual-symlink approach allows:
cd ~/.config/opencode/superpowers && git pullConfiguration Directory Resolution:
The plugin respects the OPENCODE_CONFIG_DIR environment variable .opencode/plugins/superpowers.js52-53:
This allows testing with isolated environments (used extensively in test suite).
Sources: .opencode/plugins/superpowers.js49-53 docs/README.opencode.md20-42
The normalizePath() helper .opencode/plugins/superpowers.js37-47 handles various path formats:
~ and ~/ to home directoryThis ensures consistent path handling across different invocation contexts.
Sources: .opencode/plugins/superpowers.js37-47
Skills written for Claude Code reference tools that don't exist in OpenCode. The bootstrap content includes explicit mapping instructions to translate these references.
| Claude Code Tool | OpenCode Equivalent | Purpose |
|---|---|---|
TodoWrite | update_plan | Updating implementation plans |
Task (with subagents) | @mention system | Dispatching work to fresh agent instances |
Skill | Native skill tool | Loading skill content |
Read, Write, Edit, Bash | Native tools | File operations and shell commands |
Implementation:
The tool mapping is injected as part of bootstrap .opencode/plugins/superpowers.js64-73:
This mapping is appended to the using-superpowers skill content, ensuring the agent understands how to translate tool references contextually.
Sources: .opencode/plugins/superpowers.js64-73 docs/README.opencode.md248-256
The OpenCode test suite creates isolated environments to verify plugin functionality without affecting the user's actual installation.
Diagram: Test Environment Isolation
Sources: tests/opencode/setup.sh1-74
setup.sh Key Functions:
Environment Isolation tests/opencode/setup.sh10-13:
$TEST_HOMEHOME, XDG_CONFIG_HOME, OPENCODE_CONFIG_DIRPlugin Installation tests/opencode/setup.sh16-27:
lib/, skills/, .opencode/plugins/ to test locationTest Fixtures tests/opencode/setup.sh32-57:
personal-test skill with marker textproject-test skill in isolated project directoryCleanup Function tests/opencode/setup.sh65-69:
cleanup_test_env() removes test directoryThe test-plugin-loading.sh script tests/opencode/test-plugin-loading.sh1-82 verifies:
| Test | Verification | Pass Criteria |
|---|---|---|
| Plugin Registration | Symlink exists and points to valid target | [ -L ~/.config/opencode/plugins/superpowers.js ] |
| Skills Core Library | lib/skills-core.js is in place | File exists at expected location |
| Skills Directory | Skills are populated | find ... -name SKILL.md | wc -l > 0 |
| Bootstrap Skill | using-superpowers/SKILL.md exists | Required for bootstrap injection |
| JavaScript Syntax | Plugin code is valid | node --check superpowers.js succeeds |
| Test Fixtures | Personal test skill created | Fixture file exists with marker |
Sources: tests/opencode/test-plugin-loading.sh1-82 tests/opencode/setup.sh1-74
| Variable | Purpose | Default |
|---|---|---|
OPENCODE_CONFIG_DIR | Override config directory location | ~/.config/opencode |
HOME | User home directory (used for ~ expansion) | System home |
XDG_CONFIG_HOME | XDG config directory (not currently used) | ~/.config |
The plugin reads OPENCODE_CONFIG_DIR to determine where skills are located .opencode/plugins/superpowers.js52-53 This is primarily used for testing but can be used for custom installations.
Sources: .opencode/plugins/superpowers.js49-53 tests/opencode/setup.sh10-13
The plugin exports a factory function that OpenCode calls at initialization:
Parameters:
client: OpenCode client instance (not currently used)directory: Plugin directory path (not currently used; we derive paths from __dirname)Returns:
Sources: .opencode/plugins/superpowers.js49-95
Plugin Not Loading:
ls -l ~/.config/opencode/plugins/superpowers.jsls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.jsopencode run "test" --print-logs --log-level DEBUGSkills Not Found:
ls -l ~/.config/opencode/skills/superpowers~/.config/opencode/superpowers/skillsuse skill tool to list skillsWindows Symlink Issues:
Git Bash's ln command copies files instead of creating symlinks. Use cmd //c mklink or mklink /J for directory junctions docs/README.opencode.md115-135
Bootstrap Not Appearing:
using-superpowers skill exists: ls ~/.config/opencode/superpowers/skills/using-superpowers/SKILL.mdexperimental.chat.system.transformSources: docs/README.opencode.md283-308
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.