superpowers/docs/README.opencode.md

Superpowers for OpenCode

Complete guide for using Superpowers with OpenCode.ai.

Quick Install

Tell OpenCode:

Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugin, then symlink ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js to ~/.config/opencode/plugin/superpowers.js, then restart opencode.

Manual Installation

Prerequisites

• OpenCode.ai installed
• Node.js installed
• Git installed

Installation Steps

1. Install Superpowers

mkdir -p ~/.config/opencode/superpowers
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

2. Register the Plugin

OpenCode discovers plugins from ~/.config/opencode/plugin/. Create a symlink:

mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js

Alternatively, for project-local installation:

# In your OpenCode project
mkdir -p .opencode/plugin
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js .opencode/plugin/superpowers.js

3. Restart OpenCode

Restart OpenCode to load the plugin. Superpowers will automatically activate.

Usage

Finding Skills

Use the find_skills tool to list all available skills:

use find_skills tool

Loading a Skill

Use the use_skill tool to load a specific skill:

use use_skill tool with skill_name: "superpowers:brainstorming"

Skills are automatically inserted into the conversation and persist across context compaction.

Personal Skills

Create your own skills in ~/.config/opencode/skills/:

mkdir -p ~/.config/opencode/skills/my-skill

Create ~/.config/opencode/skills/my-skill/SKILL.md:

---
name: my-skill
description: Use when [condition] - [what it does]
---

# My Skill

[Your skill content here]

Project Skills

Create project-specific skills in your OpenCode project:

# In your OpenCode project
mkdir -p .opencode/skills/my-project-skill

Create .opencode/skills/my-project-skill/SKILL.md:

---
name: my-project-skill
description: Use when [condition] - [what it does]
---

# My Project Skill

[Your skill content here]

Skill Priority

Skills are resolved with this priority order:

1. Project skills (.opencode/skills/) - Highest priority
2. Personal skills (~/.config/opencode/skills/)
3. Superpowers skills (~/.config/opencode/superpowers/skills/)

You can force resolution to a specific level:

• project:skill-name - Force project skill
• skill-name - Search project → personal → superpowers
• superpowers:skill-name - Force superpowers skill

Features

Automatic Context Injection

The plugin automatically injects superpowers context via the chat.message hook on every session. No manual configuration needed.

Message Insertion Pattern

When you load a skill with use_skill, it's inserted as a user message with noReply: true. This ensures skills persist throughout long conversations, even when OpenCode compacts context.

Compaction Resilience

The plugin listens for session.compacted events and automatically re-injects the core superpowers bootstrap to maintain functionality after context compaction.

Tool Mapping

Skills written for Claude Code are automatically adapted for OpenCode. The plugin provides mapping instructions:

• TodoWrite → update_plan
• Task with subagents → OpenCode's @mention system
• Skill tool → use_skill custom tool
• File operations → Native OpenCode tools

Architecture

Plugin Structure

Location: ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js

Components:

• Two custom tools: use_skill, find_skills
• chat.message hook for initial context injection
• event handler for session.compacted re-injection
• Uses shared lib/skills-core.js module (also used by Codex)

Shared Core Module

Location: ~/.config/opencode/superpowers/lib/skills-core.js

Functions:

• extractFrontmatter() - Parse skill metadata
• stripFrontmatter() - Remove metadata from content
• findSkillsInDir() - Recursive skill discovery
• resolveSkillPath() - Skill resolution with shadowing
• checkForUpdates() - Git update detection

This module is shared between OpenCode and Codex implementations for code reuse.

Updating

cd ~/.config/opencode/superpowers
git pull

Restart OpenCode to load the updates.

Troubleshooting

Plugin not loading

1. Check plugin file exists: ls ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js
2. Check symlink: ls -l ~/.config/opencode/plugin/superpowers.js
3. Check OpenCode logs: opencode run "test" --print-logs --log-level DEBUG
4. Look for: service=plugin path=file:///.../superpowers.js loading plugin

Skills not found

1. Verify skills directory: ls ~/.config/opencode/superpowers/skills
2. Use find_skills tool to see what's discovered
3. Check skill structure: each skill needs a SKILL.md file

Tools not working

1. Verify plugin loaded: Check OpenCode logs for plugin loading message
2. Check Node.js version: The plugin requires Node.js for ES modules
3. Test plugin manually: node --input-type=module -e "import('file://~/.config/opencode/plugin/superpowers.js').then(m => console.log(Object.keys(m)))"

Context not injecting

1. Check if chat.message hook is working
2. Verify using-superpowers skill exists
3. Check OpenCode version (requires recent version with plugin support)

Getting Help

• Report issues: https://github.com/obra/superpowers/issues
• Main documentation: https://github.com/obra/superpowers
• OpenCode docs: https://opencode.ai/docs/

Testing

The implementation includes an automated test suite at tests/opencode/:

# Run all tests
./tests/opencode/run-tests.sh --integration --verbose

# Run specific test
./tests/opencode/run-tests.sh --test test-tools.sh

Tests verify:

• Plugin loading
• Skills-core library functionality
• Tool execution (use_skill, find_skills)
• Skill priority resolution
• Proper isolation with temp HOME