@snarkipus/opencode-beads 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -33
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
# opencode-beads
|
|
2
2
|
|
|
3
|
+
[](https://github.com/snarkipus/opencode-beads/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/snarkipus/opencode-beads/actions/workflows/release.yml)
|
|
5
|
+
[](https://www.npmjs.com/package/@snarkipus/opencode-beads)
|
|
6
|
+
[](https://zizmor.sh/)
|
|
7
|
+
|
|
3
8
|
[Beads](https://github.com/gastownhall/beads) issue tracker integration for [OpenCode](https://opencode.ai).
|
|
4
9
|
|
|
5
|
-
`@snarkipus/opencode-beads` is a maintained OpenCode adapter that
|
|
10
|
+
`@snarkipus/opencode-beads` is a maintained OpenCode adapter that gives OpenCode 2 the integration `bd setup claude` gives Claude Code: `bd prime` workflow context on every request, refreshed after compaction and when a session resumes, plus a bounded task agent that completes one Bead per invocation. It does not replace Beads: the installed `bd` CLI remains authoritative for issues, project initialization, skills, migrations, backups, and Dolt synchronization.
|
|
6
11
|
|
|
7
|
-
The project originated as [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads) and continues under the MIT license. This fork is maintained by Matt Jackson
|
|
12
|
+
The project originated as [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads) and continues under the MIT license. This fork is maintained by Matt Jackson. It vendors nothing from upstream Beads; instead, every Beads release is checked against the `bd` behavior the plugin relies on (see [Tracking upstream Beads](#tracking-upstream-beads)).
|
|
8
13
|
|
|
9
14
|
## Design
|
|
10
15
|
|
|
@@ -17,36 +22,30 @@ The plugin's primary design is **context-preserving atomic delegation**:
|
|
|
17
22
|
|
|
18
23
|
## Installation
|
|
19
24
|
|
|
20
|
-
|
|
25
|
+
This plugin requires OpenCode 2 and `bd` 1.3.0 or later.
|
|
21
26
|
|
|
22
|
-
|
|
23
|
-
git init # only when the directory is not already a Git worktree
|
|
24
|
-
bd init
|
|
25
|
-
```
|
|
27
|
+
1. Install the [`bd` CLI](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md) once on the host, then initialize each project:
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
```bash
|
|
30
|
+
git init # only when the directory is not already a Git worktree
|
|
31
|
+
bd init
|
|
32
|
+
```
|
|
28
33
|
|
|
29
|
-
|
|
34
|
+
`bd init` owns project initialization and creates the canonical shared Beads skill at `.agents/skills/beads`, which OpenCode discovers. It also writes a minimal Beads section to `AGENTS.md` that points to `bd prime`, the same pointer Beads gives Claude Code in `CLAUDE.md`. This plugin has no separate skill lifecycle and does not write startup files.
|
|
30
35
|
|
|
31
|
-
|
|
36
|
+
2. Add the version-pinned plugin to `~/.config/opencode/opencode.json` for every project, or to a project's `.opencode/opencode.json`:
|
|
32
37
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
| `--remove` | Remove the `plugins` entry |
|
|
39
|
-
| `--check` | `opencode debug agents` lists `beads-task-agent`; a session's agent sees a `<beads-context>` block |
|
|
38
|
+
```json
|
|
39
|
+
{
|
|
40
|
+
"plugins": ["@snarkipus/opencode-beads@1.0.1"]
|
|
41
|
+
}
|
|
42
|
+
```
|
|
40
43
|
|
|
41
|
-
|
|
44
|
+
OpenCode loads configuration changes automatically. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible. OpenCode 1.x plugins are not supported; use 0.10.x or earlier there.
|
|
42
45
|
|
|
43
|
-
|
|
46
|
+
3. Check the install: `opencode debug agents` lists `beads-task-agent`.
|
|
44
47
|
|
|
45
|
-
|
|
46
|
-
{
|
|
47
|
-
"plugins": ["@snarkipus/opencode-beads@1.0.0"]
|
|
48
|
-
}
|
|
49
|
-
```
|
|
48
|
+
### Plugin options
|
|
50
49
|
|
|
51
50
|
Plugin options use the object form:
|
|
52
51
|
|
|
@@ -54,7 +53,7 @@ Plugin options use the object form:
|
|
|
54
53
|
{
|
|
55
54
|
"plugins": [
|
|
56
55
|
{
|
|
57
|
-
"package": "@snarkipus/opencode-beads@1.0.
|
|
56
|
+
"package": "@snarkipus/opencode-beads@1.0.1",
|
|
58
57
|
"options": { "luna": true, "autoMigrate": false }
|
|
59
58
|
}
|
|
60
59
|
]
|
|
@@ -69,17 +68,30 @@ Plugin options use the object form:
|
|
|
69
68
|
| `refreshAfterIdleMinutes` | `30` | Re-run `bd prime` when a session resumes after this much inactivity, as Claude Code does on resume. `0` disables idle refresh. |
|
|
70
69
|
| `autoMigrate` | `false` | Let automatic `bd prime` open a store that may need a schema migration. See [Schema migration guard](#schema-migration-guard). |
|
|
71
70
|
|
|
72
|
-
|
|
71
|
+
### Why not `bd setup opencode`
|
|
73
72
|
|
|
74
|
-
|
|
73
|
+
**Do not run `bd setup opencode`.** That recipe is for OpenCode without this plugin. Beads assumes OpenCode has no hooks, so it replaces `bd init`'s minimal pointer with the full command reference, about 2 kB more on every request. With this plugin, `bd prime` arrives through OpenCode's hooks instead, as it does for Claude Code. If you already ran it, `bd setup opencode --remove` deletes the Beads section from `AGENTS.md` (prime still arrives through the plugin), or simply leave it: while prime is attached, the plugin replaces it in the request with a one-line pointer.
|
|
75
74
|
|
|
76
|
-
|
|
75
|
+
### Parity with `bd setup claude`
|
|
76
|
+
|
|
77
|
+
Installing the plugin gives OpenCode the same integration that `bd setup claude` gives Claude Code:
|
|
78
|
+
|
|
79
|
+
| `bd setup claude` (Claude Code) | This plugin (OpenCode 2) |
|
|
80
|
+
| --- | --- |
|
|
81
|
+
| `SessionStart` hook runs `bd prime --hook-json`, also on resume and after compaction | The session context hook attaches `bd prime` to each request; it is refreshed after compaction and on resume after an idle gap |
|
|
82
|
+
| Minimal `CLAUDE.md` pointer to `bd prime` | `bd init`'s minimal `AGENTS.md` pointer; bd's full or Codex sections are reduced to a pointer while prime is attached |
|
|
83
|
+
| `--global` or project install | Global `~/.config/opencode/opencode.json` or project `.opencode/opencode.json` `plugins` entry |
|
|
84
|
+
| `--stealth` | `stealth` plugin option |
|
|
85
|
+
| `--remove` | Remove the `plugins` entry |
|
|
86
|
+
| `--check` | `opencode debug agents` lists `beads-task-agent`; a session's agent sees a `<beads-context>` block |
|
|
87
|
+
|
|
88
|
+
The [Claude Code parity matrix](docs/claude-code-parity.md) records every `bd setup claude` behavior, its OpenCode equivalent and live evidence, the OpenCode-only capabilities, and the deliberate divergences.
|
|
77
89
|
|
|
78
90
|
## Context injection
|
|
79
91
|
|
|
80
92
|
The plugin runs full `bd prime` in the project directory and attaches its output to each model request through OpenCode's session context hook. The output is cached per session, so prime runs once per session rather than per request. It runs again after compaction (automatic or manual), when a session resumes after `refreshAfterIdleMinutes` of inactivity, and when the plugin reloads, mirroring the `startup`, `resume`, `clear`, and `compact` sources of Claude Code's `SessionStart` hook. Steady work keeps the same text, which keeps provider prompt caches warm. Attached context is not stored in the conversation, so compaction cannot drop it. Prime supplies the canonical current workflow, command guidance, and persistent memories; the plugin adds only compact OpenCode-specific safety and delegation guidance.
|
|
81
93
|
|
|
82
|
-
While prime is attached, bd
|
|
94
|
+
While prime is attached, two bd-managed `AGENTS.md` blocks only repeat it: the full-profile section `bd setup opencode` writes, and the Codex section `bd init` writes. The plugin replaces those marked blocks in the outgoing request with a one-line pointer, matching the minimal `CLAUDE.md` pointer Beads uses for Claude Code. `bd init`'s minimal section is left as is. Your `AGENTS.md` file and any text outside those markers are not changed, and nothing is replaced when prime is withheld or unavailable.
|
|
83
95
|
|
|
84
96
|
Known regular subagents remain excluded, including `explore` and `general`, while `beads-task-agent` and `beads-task-agent-luna` remain eligible. If agent lookup fails, context injection fails open to preserve compatibility with unknown custom primary agents.
|
|
85
97
|
|
|
@@ -95,17 +107,17 @@ Before running prime, the plugin checks `bd version` and `bd where --json`, whic
|
|
|
95
107
|
|
|
96
108
|
## Beads workflows
|
|
97
109
|
|
|
98
|
-
The plugin registers no
|
|
110
|
+
The plugin registers no slash commands; `bd setup claude` installs none either. Ask the agent to work with Beads, have it load the canonical `beads` skill that `bd init` installs at `.agents/skills/beads` (OpenCode lists it and loads it with its `skill` tool), or use the `bd` CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) directly. Versions before 1.0.0 shipped `/beads:*` commands adapted from upstream's Claude Code plugin; they duplicated `bd prime` and the skill.
|
|
99
111
|
|
|
100
112
|
## Agent configuration
|
|
101
113
|
|
|
102
|
-
Entries under `agents` in OpenCode configuration override the plugin's task-agent fields one by one, so a partial override (for example only `description`) keeps the bounded `system` prompt and subagent `mode`. Fields you set explicitly, such as `system`, `model`, or `permissions`, win. OpenCode V2 does not expose configuration-only agents to plugins, so the plugin
|
|
114
|
+
Entries under `agents` in OpenCode configuration override the plugin's task-agent fields one by one, so a partial override (for example only `description`) keeps the bounded `system` prompt and subagent `mode`. Fields you set explicitly, such as `system`, `model`, or `permissions`, win. OpenCode V2 does not expose configuration-only agents to plugins, so the plugin cannot detect or warn about overrides.
|
|
103
115
|
|
|
104
116
|
## Task agent
|
|
105
117
|
|
|
106
118
|
`beads-task-agent` supports read-only status and graph analysis or one-Bead completion. Analysis requests never mutate Beads. Completion requests inspect and process one caller-selected or highest-priority ready Bead, quarantine work discovered during that invocation, validate before closure, and return after closing or blocking the selected Bead.
|
|
107
119
|
|
|
108
|
-
Its prompt and description are
|
|
120
|
+
Its prompt and description are owned by this project. Upstream Beads ships a task agent only in its Claude Code marketplace plugin, as an autonomous multi-task loop; this adapter deliberately keeps the bounded one-Bead contract instead.
|
|
109
121
|
|
|
110
122
|
OpenCode lets the plugin enforce parts of that contract, beyond what Claude Code's hooks can do:
|
|
111
123
|
|
|
@@ -116,7 +128,7 @@ OpenCode lets the plugin enforce parts of that contract, beyond what Claude Code
|
|
|
116
128
|
|
|
117
129
|
### Opt-in Luna Max profile
|
|
118
130
|
|
|
119
|
-
The default `beads-task-agent` leaves its model unset, so a subagent inherits the parent session's model. Set the plugin option `"luna": true` to also register `beads-task-agent-luna`, which uses `openai/gpt-6-luna#max` with exactly the same prompt, subagent mode, and
|
|
131
|
+
The default `beads-task-agent` leaves its model unset, so a subagent inherits the parent session's model. Set the plugin option `"luna": true` to also register `beads-task-agent-luna`, which uses `openai/gpt-6-luna#max` with exactly the same prompt, subagent mode, step cap, and permissions. Per-agent overrides remain independent: customizations to `beads-task-agent` are not copied to Luna. Both profiles receive full prime context and retain the same exact-one-Bead workflow.
|
|
120
132
|
|
|
121
133
|
Ask the primary agent to delegate to `beads-task-agent-luna` by name through the `subagent` tool. Default delegation guidance still names `beads-task-agent`; enabling Luna does not reroute existing calls or change the primary agent's model. Remove the option to unregister the profile.
|
|
122
134
|
|
|
@@ -144,10 +156,17 @@ The adapter type-checks against `@opencode/plugin` 2.0.26 and declares it as an
|
|
|
144
156
|
- **Agent reports that `bd prime` failed or timed out:** Run `bd prime` in the project to see the error; the plugin retries every 30 seconds.
|
|
145
157
|
- **Agent reports a Beads notice instead of context:** The schema migration guard withheld prime. Back up `.beads`, run `bd migrate schema`, and continue; or upgrade `bd` if the notice says it is older than 1.3.0.
|
|
146
158
|
- **Canonical skill missing:** For a new workspace, run `bd init`. For an existing workspace, follow current upstream Beads guidance; this plugin does not install or repair skills.
|
|
159
|
+
- **Task agent asks before committing or pushing:** This is intentional; see [Task agent](#task-agent). Approve the command, or set the agent's `permissions` in OpenCode configuration.
|
|
147
160
|
- **Unexpected definition:** Check OpenCode configuration for a colliding `beads-task-agent` definition. Explicit configuration wins.
|
|
148
161
|
- **Regular subagent has no context:** This is intentional. Delegate Beads work to `beads-task-agent` or run the required `bd` command explicitly.
|
|
149
162
|
- **Behavior changed after upgrade:** Compare `opencode --version`, `bd version`, and `bun --version` with the compatibility table, then inspect [Beads releases](https://github.com/gastownhall/beads/releases) and this project's changelog.
|
|
150
163
|
|
|
164
|
+
## Earlier releases
|
|
165
|
+
|
|
166
|
+
### 0.9.3 recovery notice
|
|
167
|
+
|
|
168
|
+
Version 0.9.3 contained command guidance from the withdrawn upstream Beads v1.2.1 release. This plugin did not bundle the `bd` binary or implement database migrations, but it could invoke a consumer-installed v1.2.1 binary through `bd prime`. Even one v1.2.1 execution could migrate the database. Upgrade the plugin package to 0.9.4 or later; if v1.2.1 was installed and may have run, also follow the [upstream database recovery guidance](https://github.com/gastownhall/beads/blob/v1.2.2/docs/RECOVERY-1.2.1.md).
|
|
169
|
+
|
|
151
170
|
## License
|
|
152
171
|
|
|
153
172
|
opencode-beads is licensed under the MIT license. See [`LICENSE`](LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@snarkipus/opencode-beads",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "A maintained OpenCode V2 integration for the Beads issue tracker: bd prime context injection with a schema-migration guard, and a bounded task agent.",
|
|
6
6
|
"author": "Matt Jackson",
|