summaryrefslogtreecommitdiff
path: root/docs/README.opencode.md
diff options
context:
space:
mode:
authorJesse Vincent <jesse@fsck.com>2026-09-18 18:38:59 +0000
committerJesse Vincent <jesse@fsck.com>2026-09-18 18:38:59 +0000
commit8412aaf0385cbfd850675093f01b16c88052f268 (patch)
tree88ae48d06c4d104d65e35d345e65f7c210189564 /docs/README.opencode.md
parentb36e0829c6d0140e93cfef2ca599b1b07d4a7797 (diff)
Release v6.4.0: diagnosing-superpowers and movie skills, Native execution, OpenCode 2.0, Muse, and Qwen Code supportrelease/v6.4.0
Everything on dev since the v6.3.0 merge-back (777ceb5), as one commit. Full notes: RELEASE-NOTES.md, v6.4.0 section. Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B
Diffstat (limited to 'docs/README.opencode.md')
-rw-r--r--docs/README.opencode.md125
1 files changed, 103 insertions, 22 deletions
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 11da854..419a8a6 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -4,7 +4,11 @@ Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
## Installation
-Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
+OpenCode V2 requires version 2.0.4 or later.
+
+### OpenCode V1
+
+Use the existing V1 plugin configuration:
```json
{
@@ -12,15 +16,27 @@ Add superpowers to the `plugin` array in your `opencode.json` (global or project
}
```
-Restart OpenCode. The plugin installs through OpenCode's plugin manager and
+### OpenCode V2 (2.0.4 or later)
+
+Use the V2 plugin configuration:
+
+```json
+{
+ "plugins": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
+```
+
+For a local V2 installation, configure the repository directory containing
+`index.js`. OpenCode 2.0.4 and 2.0.7 reject a configured direct JavaScript-file
+path. Discovered plugin symlinks remain supported.
+
+Restart OpenCode. V2 uses the `opencode` command; `opencode2` may be available
+as an alias. The plugin installs through OpenCode's plugin manager and
registers all skills.
Verify by asking: "Tell me about your superpowers"
-OpenCode uses its own plugin install. If you also use Claude Code, Codex, or
-another harness, install Superpowers separately for each one.
-
-### Migrating from the old symlink-based install
+### Migrating from the old symlink-based install (V1)
If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
@@ -78,7 +94,10 @@ description: Use when [condition] - [what it does]
Create project-specific skills in `.opencode/skills/` within your project.
-**Skill Priority:** Project skills > Personal skills > Superpowers skills
+**V2 Skill Priority:** Project skills > Personal skills > Superpowers skills. On
+tested V1 1.18.31, bundled Superpowers skills take precedence when a personal
+or project skill has the same name; use distinct names for personal and project
+skills. This behavior is unchanged by the migration.
## Updating
@@ -87,24 +106,45 @@ and Bun versions pin that resolved git dependency in a lockfile or cache, so a
restart may not pick up the newest Superpowers commit. If updates do not appear,
clear OpenCode's package cache or reinstall the plugin.
-To pin a specific version, use a branch or tag:
+To pin a specific version, add a tag or commit to the spec (same form for the
+V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.4.0"]
}
```
+On V2, pin `v6.4.0` or later; `v6.3.0` and earlier releases load only on V1.
+
## How It Works
-The plugin does two things:
+The plugin does two things, using host-flavor-specific APIs:
+
+1. **Registers the skills directory** so OpenCode discovers all superpowers skills without symlinks or manual config.
+ - **V1:** via the `config` hook, injecting into `config.skills.paths`
+ - **V2:** via the `setup()` function using `ctx.skill.transform()` (V2 native API, confirmed active at runtime)
+2. **Injects bootstrap context** with a flavor-specific tool mapping: V1 sessions get the V1 tool names below, and V2 sessions get the V2 names.
+ - **V1:** via `experimental.chat.messages.transform` hook
+ - **V2:** via `ctx.session.hook("context")` — the V2 equivalent (confirmed active at runtime)
-1. **Injects bootstrap context** via the `experimental.chat.messages.transform` hook, adding superpowers awareness to every conversation.
-2. **Registers the skills directory** via the `config` hook, so OpenCode discovers all superpowers skills without symlinks or manual config.
+Controller sessions receive the using-superpowers bootstrap in transient model
+context. Delegated child sessions keep access to native skills but do not receive
+the controller bootstrap. A manual fork without a parent session keeps controller
+behavior. When V2 native compaction retains earlier user messages (the default
+`compaction.keep.tokens` budget), the bootstrap goes into the first retained user
+message ahead of the checkpoint, as in an uncompacted session. When compaction
+removes all user messages, the plugin appends a transient bootstrap message after
+the checkpoint. Saved history is unchanged either way.
+
+If session lookup fails, the plugin keeps bootstrap for that request and retries
+on the next request. Failed lookups are not cached as controller decisions.
### Tool Mapping
-Skills speak in actions rather than naming any one runtime's tools. On OpenCode these resolve to:
+Skills speak in actions rather than naming any one runtime's tools. The bootstrap maps them to the tools your OpenCode flavor actually exposes.
+
+**V1 (`opencode` 1.x):**
- "Create a todo" / "mark complete in todo list" → `todowrite`
- `Subagent (general-purpose):` template → OpenCode's `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
@@ -115,15 +155,43 @@ Skills speak in actions rather than naming any one runtime's tools. On OpenCode
- "Search file contents" / "find files by name" → `grep`, `glob`
- "Fetch a URL" → `webfetch`
-(Verified against the installed OpenCode CLI's tool inventory.)
+**V2 (`opencode` 2.0.4 or later; `opencode2` may be available as an alias):**
+
+- "Create a todo" → V2 has no todo tool of any kind; the mapping tells the model to track the plan in a markdown file (or the harness's plan facility) instead
+- `Subagent (general-purpose):` template → OpenCode's `subagent` tool with `agent: "general"` (or `"explore"`); pass `sessionID` to continue a previous subagent
+- "Invoke a skill" → OpenCode's native `skill` tool
+- "Read a file" → `read`
+- "Create, edit, or delete files" → use `patch` with `patchText` when available; otherwise use `write` to create or overwrite files, `edit` for targeted changes, and `shell` for deletion
+- "Run a shell command" → `shell` (`command`, `workdir`, `timeout`, `background`)
+- "Search file contents" / "find files by name" → `grep`, `glob`
+- "Fetch a URL" → `webfetch`
+- "Search the web" → `websearch`
+
+In short, V2 renamed `task` → `subagent` (the agent name moved from `subagent_type` to `agent`, and continuation happens by re-invoking with `sessionID`), `apply_patch` → `patch`, and `bash` → `shell`, and it dropped the todo tool entirely. The available mutation tools depend on the selected model: `patch` is available for selected GPT model IDs, while other models use `write` and `edit`.
+
+(V1 list verified against the installed OpenCode 1.18.x CLI's tool inventory; V2 list verified against the OpenCode 2.0.4 and 2.0.7 host contracts.)
## Troubleshooting
### Plugin not loading
-1. Check OpenCode logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
-2. Verify the plugin line in your `opencode.json` is correct
-3. Make sure you're running a recent version of OpenCode
+**V1:** Check OpenCode logs:
+
+```
+opencode run --print-logs "hello" 2>&1 | grep -i superpowers
+```
+
+**V2:** Plugins load in the background server, whose logs `--print-logs` only
+shows with `--standalone`:
+
+```
+opencode run --standalone --print-logs "hello" 2>&1 | grep -i superpowers
+```
+
+Or inspect `~/.local/share/opencode/log/opencode.log`, filtering for `role=server`.
+
+Also verify the plugin path in your `opencode.json` is correct and that you're
+running a recent version of OpenCode.
### Windows install issues
@@ -137,11 +205,23 @@ package:
npm install superpowers@git+https://github.com/obra/superpowers.git --prefix "$HOME\.config\opencode"
```
-Then use the installed package path in `opencode.json`:
+Then use the absolute path of the installed package in `opencode.json` for your
+OpenCode version. OpenCode does not expand `~`; a `~/...` entry is treated as a
+package name, not a local directory.
+
+**V1:**
+
+```json
+{
+ "plugin": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
+}
+```
+
+**V2 (2.0.4 or later):**
```json
{
- "plugin": ["~/.config/opencode/node_modules/superpowers"]
+ "plugins": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
}
```
@@ -153,11 +233,12 @@ Then use the installed package path in `opencode.json`:
### Bootstrap not appearing
-1. Check OpenCode version supports `experimental.chat.messages.transform` hook
-2. Restart OpenCode after config changes
+- **V1:** Check OpenCode version supports `experimental.chat.messages.transform` hook. Restart OpenCode after config changes.
+- **V2:** The plugin uses `ctx.session.hook("context")` for bootstrap injection. Verify the plugin loaded via `opencode api get /api/plugin`. Restart with `opencode service restart` after config changes. The `opencode2` command may be available as an alias.
## Getting Help
- Report issues: https://github.com/obra/superpowers/issues
- Main documentation: https://github.com/obra/superpowers
-- OpenCode docs: https://opencode.ai/docs/
+- OpenCode V2 docs: https://opencode.ai/v2/docs/
+- OpenCode V1 docs: https://opencode.ai/docs/