opencode-swarm-plugin 0.9.0 → 0.11.0
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/.beads/issues.jsonl +44 -0
- package/README.md +184 -105
- package/bin/swarm.ts +549 -26
- package/dist/index.js +232 -26
- package/dist/plugin.js +232 -26
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,7 +3,21 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/opencode-swarm-plugin)
|
|
4
4
|
[](https://opensource.org/licenses/MIT)
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
```
|
|
7
|
+
███████╗██╗ ██╗ █████╗ ██████╗ ███╗ ███╗
|
|
8
|
+
██╔════╝██║ ██║██╔══██╗██╔══██╗████╗ ████║
|
|
9
|
+
███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
|
|
10
|
+
╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
|
|
11
|
+
███████║╚███╔███╔╝██║ ██║██║ ██║██║ ╚═╝ ██║
|
|
12
|
+
╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝
|
|
13
|
+
|
|
14
|
+
\ ` - ' /
|
|
15
|
+
- .(o o). -
|
|
16
|
+
( >.< ) Multi-agent coordination for OpenCode
|
|
17
|
+
/| |\ Break complex tasks into parallel subtasks,
|
|
18
|
+
(_| |_) spawn agents, coordinate via messaging.
|
|
19
|
+
bzzzz... The plugin learns from outcomes.
|
|
20
|
+
```
|
|
7
21
|
|
|
8
22
|
## Install
|
|
9
23
|
|
|
@@ -12,10 +26,10 @@ npm install -g opencode-swarm-plugin
|
|
|
12
26
|
swarm setup
|
|
13
27
|
```
|
|
14
28
|
|
|
15
|
-
|
|
29
|
+
The setup wizard handles everything:
|
|
16
30
|
|
|
17
31
|
```
|
|
18
|
-
┌ opencode-swarm-plugin v0.
|
|
32
|
+
┌ opencode-swarm-plugin v0.10.0
|
|
19
33
|
│
|
|
20
34
|
◇ Checking dependencies...
|
|
21
35
|
│
|
|
@@ -51,72 +65,138 @@ swarm init
|
|
|
51
65
|
swarm setup Interactive installer - checks and installs all dependencies
|
|
52
66
|
swarm doctor Health check - shows status of all dependencies
|
|
53
67
|
swarm init Initialize beads in current project
|
|
54
|
-
swarm
|
|
68
|
+
swarm config Show paths to generated config files
|
|
69
|
+
swarm version Show version and banner
|
|
55
70
|
swarm help Show help
|
|
56
71
|
```
|
|
57
72
|
|
|
58
|
-
|
|
73
|
+
## Usage
|
|
74
|
+
|
|
75
|
+
In OpenCode:
|
|
59
76
|
|
|
60
77
|
```
|
|
61
|
-
|
|
62
|
-
│
|
|
63
|
-
◇ Required dependencies:
|
|
64
|
-
│
|
|
65
|
-
◆ OpenCode v1.0.134
|
|
66
|
-
◆ Beads v0.29.0
|
|
67
|
-
│
|
|
68
|
-
◇ Optional dependencies:
|
|
69
|
-
│
|
|
70
|
-
◆ Go v1.25.2 - Required for Agent Mail
|
|
71
|
-
▲ Agent Mail - not found
|
|
72
|
-
◆ Redis - Rate limiting
|
|
73
|
-
│
|
|
74
|
-
└ All required dependencies installed. 1 optional missing.
|
|
78
|
+
/swarm "Add user authentication with OAuth"
|
|
75
79
|
```
|
|
76
80
|
|
|
77
|
-
|
|
81
|
+
Or invoke the planner directly:
|
|
78
82
|
|
|
79
83
|
```
|
|
80
|
-
|
|
81
|
-
│
|
|
82
|
-
◇ Initializing beads...
|
|
83
|
-
◆ Created .beads/ directory
|
|
84
|
-
│
|
|
85
|
-
◆ Create your first bead?
|
|
86
|
-
│ ● Yes / ○ No
|
|
87
|
-
│
|
|
88
|
-
◇ Bead title: Implement user authentication
|
|
89
|
-
◇ Type: Feature
|
|
90
|
-
│
|
|
91
|
-
└ Project initialized!
|
|
84
|
+
@swarm-planner "Refactor all components to use hooks"
|
|
92
85
|
```
|
|
93
86
|
|
|
94
|
-
##
|
|
87
|
+
## Customization
|
|
95
88
|
|
|
96
|
-
|
|
89
|
+
Run `swarm config` to see your config file paths:
|
|
97
90
|
|
|
98
91
|
```
|
|
99
|
-
|
|
92
|
+
🔌 Plugin loader
|
|
93
|
+
~/.config/opencode/plugins/swarm.ts
|
|
94
|
+
|
|
95
|
+
📜 /swarm command prompt
|
|
96
|
+
~/.config/opencode/commands/swarm.md
|
|
97
|
+
|
|
98
|
+
🤖 @swarm-planner agent
|
|
99
|
+
~/.config/opencode/agents/swarm-planner.md
|
|
100
100
|
```
|
|
101
101
|
|
|
102
|
-
|
|
102
|
+
### /swarm Command
|
|
103
|
+
|
|
104
|
+
The `/swarm` command is defined in `~/.config/opencode/commands/swarm.md`:
|
|
105
|
+
|
|
106
|
+
```markdown
|
|
107
|
+
---
|
|
108
|
+
description: Decompose task into parallel subtasks and coordinate agents
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
You are a swarm coordinator. Take a complex task, break it into beads,
|
|
112
|
+
and unleash parallel agents.
|
|
113
|
+
|
|
114
|
+
## Usage
|
|
115
|
+
|
|
116
|
+
/swarm <task description or bead-id>
|
|
117
|
+
|
|
118
|
+
## Workflow
|
|
103
119
|
|
|
120
|
+
1. **Initialize**: `agentmail_init` with project_path and task_description
|
|
121
|
+
2. **Decompose**: Use `swarm_select_strategy` then `swarm_plan_prompt`
|
|
122
|
+
3. **Create beads**: `beads_create_epic` with subtasks and file assignments
|
|
123
|
+
4. **Reserve files**: `agentmail_reserve` for each subtask's files
|
|
124
|
+
5. **Spawn agents**: Use Task tool with `swarm_spawn_subtask` prompts
|
|
125
|
+
6. **Monitor**: Check `agentmail_inbox` for progress
|
|
126
|
+
7. **Complete**: `swarm_complete` when done, then `beads_sync` to push
|
|
127
|
+
|
|
128
|
+
## Strategy Selection
|
|
129
|
+
|
|
130
|
+
| Strategy | Best For | Keywords |
|
|
131
|
+
| ------------- | ----------------------- | ------------------------------------- |
|
|
132
|
+
| file-based | Refactoring, migrations | refactor, migrate, rename, update all |
|
|
133
|
+
| feature-based | New features | add, implement, build, create |
|
|
134
|
+
| risk-based | Bug fixes, security | fix, bug, security, critical, urgent |
|
|
135
|
+
|
|
136
|
+
Begin decomposition now.
|
|
104
137
|
```
|
|
105
|
-
|
|
138
|
+
|
|
139
|
+
### @swarm-planner Agent
|
|
140
|
+
|
|
141
|
+
The `@swarm-planner` agent is defined in `~/.config/opencode/agents/swarm-planner.md`:
|
|
142
|
+
|
|
143
|
+
````markdown
|
|
144
|
+
---
|
|
145
|
+
name: swarm-planner
|
|
146
|
+
description: Strategic task decomposition for swarm coordination
|
|
147
|
+
model: claude-sonnet-4-5
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
You are a swarm planner. Decompose tasks into optimal parallel subtasks.
|
|
151
|
+
|
|
152
|
+
## Workflow
|
|
153
|
+
|
|
154
|
+
1. Call `swarm_select_strategy` to analyze the task
|
|
155
|
+
2. Call `swarm_plan_prompt` to get strategy-specific guidance
|
|
156
|
+
3. Create a BeadTree following the guidelines
|
|
157
|
+
4. Return ONLY valid JSON - no markdown, no explanation
|
|
158
|
+
|
|
159
|
+
## Output Format
|
|
160
|
+
|
|
161
|
+
```json
|
|
162
|
+
{
|
|
163
|
+
"epic": { "title": "...", "description": "..." },
|
|
164
|
+
"subtasks": [
|
|
165
|
+
{
|
|
166
|
+
"title": "...",
|
|
167
|
+
"description": "...",
|
|
168
|
+
"files": ["src/..."],
|
|
169
|
+
"dependencies": [],
|
|
170
|
+
"estimated_complexity": 2
|
|
171
|
+
}
|
|
172
|
+
]
|
|
173
|
+
}
|
|
106
174
|
```
|
|
175
|
+
````
|
|
176
|
+
|
|
177
|
+
## Rules
|
|
178
|
+
|
|
179
|
+
- 2-7 subtasks (too few = not parallel, too many = overhead)
|
|
180
|
+
- No file overlap between subtasks
|
|
181
|
+
- Include tests with the code they test
|
|
182
|
+
- Order by dependency (if B needs A, A comes first)
|
|
183
|
+
|
|
184
|
+
````
|
|
185
|
+
|
|
186
|
+
Edit these files to customize behavior. Run `swarm setup` to regenerate defaults.
|
|
107
187
|
|
|
108
188
|
## Dependencies
|
|
109
189
|
|
|
110
|
-
| Dependency
|
|
111
|
-
|
|
112
|
-
| [OpenCode](https://opencode.ai)
|
|
113
|
-
| [Beads](https://github.com/steveyegge/beads)
|
|
114
|
-
| [Go](https://go.dev)
|
|
115
|
-
| [Agent Mail](https://github.com/joelhooks/agent-mail)
|
|
116
|
-
| [CASS](https://github.com/Dicklesworthstone/cass)
|
|
117
|
-
| [UBS](https://github.com/joelhooks/ubs)
|
|
118
|
-
| [semantic-memory](https://github.com/joelhooks/semantic-memory) | Learning persistence
|
|
119
|
-
| [Redis](https://redis.io)
|
|
190
|
+
| Dependency | Purpose | Required |
|
|
191
|
+
|------------|---------|----------|
|
|
192
|
+
| [OpenCode](https://opencode.ai) | Plugin host | Yes |
|
|
193
|
+
| [Beads](https://github.com/steveyegge/beads) | Git-backed issue tracking | Yes |
|
|
194
|
+
| [Go](https://go.dev) | Required for Agent Mail | No |
|
|
195
|
+
| [Agent Mail](https://github.com/joelhooks/agent-mail) | Multi-agent coordination, file reservations | No |
|
|
196
|
+
| [CASS](https://github.com/Dicklesworthstone/cass) | Historical context from past sessions | No |
|
|
197
|
+
| [UBS](https://github.com/joelhooks/ubs) | Pre-completion bug scanning | No |
|
|
198
|
+
| [semantic-memory](https://github.com/joelhooks/semantic-memory) | Learning persistence | No |
|
|
199
|
+
| [Redis](https://redis.io) | Rate limiting (SQLite fallback available) | No |
|
|
120
200
|
|
|
121
201
|
All dependencies are checked and can be installed via `swarm setup`.
|
|
122
202
|
|
|
@@ -124,58 +204,57 @@ All dependencies are checked and can be installed via `swarm setup`.
|
|
|
124
204
|
|
|
125
205
|
### Swarm
|
|
126
206
|
|
|
127
|
-
| Tool
|
|
128
|
-
|
|
129
|
-
| `swarm_init`
|
|
130
|
-
| `swarm_select_strategy`
|
|
131
|
-
| `swarm_plan_prompt`
|
|
132
|
-
| `swarm_decompose`
|
|
133
|
-
| `swarm_validate_decomposition` | Validate response, detect file conflicts
|
|
134
|
-
| `swarm_spawn_subtask`
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `swarm_record_outcome` | Record outcome for learning (duration, errors, retries) |
|
|
207
|
+
| Tool | Description |
|
|
208
|
+
|------|-------------|
|
|
209
|
+
| `swarm_init` | Initialize swarm session |
|
|
210
|
+
| `swarm_select_strategy` | Analyze task, recommend decomposition strategy (file/feature/risk-based) |
|
|
211
|
+
| `swarm_plan_prompt` | Generate strategy-specific planning prompt with CASS history |
|
|
212
|
+
| `swarm_decompose` | Generate decomposition prompt |
|
|
213
|
+
| `swarm_validate_decomposition` | Validate response, detect file conflicts |
|
|
214
|
+
| `swarm_spawn_subtask` | Generate worker agent prompt with Agent Mail/beads instructions |
|
|
215
|
+
| `swarm_status` | Get swarm progress by epic ID |
|
|
216
|
+
| `swarm_progress` | Report subtask progress to coordinator |
|
|
217
|
+
| `swarm_complete` | Complete subtask - runs UBS scan, releases reservations |
|
|
218
|
+
| `swarm_record_outcome` | Record outcome for learning (duration, errors, retries) |
|
|
140
219
|
|
|
141
220
|
### Beads
|
|
142
221
|
|
|
143
|
-
| Tool
|
|
144
|
-
|
|
145
|
-
| `beads_create`
|
|
146
|
-
| `beads_create_epic` | Create epic + subtasks atomically
|
|
147
|
-
| `beads_query`
|
|
148
|
-
| `beads_update`
|
|
149
|
-
| `beads_close`
|
|
150
|
-
| `beads_start`
|
|
151
|
-
| `beads_ready`
|
|
152
|
-
| `beads_sync`
|
|
153
|
-
| `beads_link_thread` | Link bead to Agent Mail thread
|
|
222
|
+
| Tool | Description |
|
|
223
|
+
|------|-------------|
|
|
224
|
+
| `beads_create` | Create bead with type-safe validation |
|
|
225
|
+
| `beads_create_epic` | Create epic + subtasks atomically |
|
|
226
|
+
| `beads_query` | Query beads with filters (status, type, ready) |
|
|
227
|
+
| `beads_update` | Update status/description/priority |
|
|
228
|
+
| `beads_close` | Close bead with reason |
|
|
229
|
+
| `beads_start` | Mark bead as in-progress |
|
|
230
|
+
| `beads_ready` | Get next unblocked bead |
|
|
231
|
+
| `beads_sync` | Sync to git and push |
|
|
232
|
+
| `beads_link_thread` | Link bead to Agent Mail thread |
|
|
154
233
|
|
|
155
234
|
### Agent Mail
|
|
156
235
|
|
|
157
|
-
| Tool
|
|
158
|
-
|
|
159
|
-
| `agentmail_init`
|
|
160
|
-
| `agentmail_send`
|
|
161
|
-
| `agentmail_inbox`
|
|
162
|
-
| `agentmail_read_message`
|
|
236
|
+
| Tool | Description |
|
|
237
|
+
|------|-------------|
|
|
238
|
+
| `agentmail_init` | Initialize session, register agent |
|
|
239
|
+
| `agentmail_send` | Send message to agents |
|
|
240
|
+
| `agentmail_inbox` | Fetch inbox (max 5, no bodies - context safe) |
|
|
241
|
+
| `agentmail_read_message` | Fetch single message body by ID |
|
|
163
242
|
| `agentmail_summarize_thread` | Summarize thread (preferred over fetching all) |
|
|
164
|
-
| `agentmail_reserve`
|
|
165
|
-
| `agentmail_release`
|
|
166
|
-
| `agentmail_ack`
|
|
167
|
-
| `agentmail_search`
|
|
168
|
-
| `agentmail_health`
|
|
243
|
+
| `agentmail_reserve` | Reserve file paths for exclusive editing |
|
|
244
|
+
| `agentmail_release` | Release file reservations |
|
|
245
|
+
| `agentmail_ack` | Acknowledge message |
|
|
246
|
+
| `agentmail_search` | Search messages by keyword |
|
|
247
|
+
| `agentmail_health` | Check if Agent Mail server is running |
|
|
169
248
|
|
|
170
249
|
### Structured Output
|
|
171
250
|
|
|
172
|
-
| Tool
|
|
173
|
-
|
|
174
|
-
| `structured_extract_json`
|
|
175
|
-
| `structured_validate`
|
|
176
|
-
| `structured_parse_evaluation`
|
|
177
|
-
| `structured_parse_decomposition` | Parse task decomposition response
|
|
178
|
-
| `structured_parse_bead_tree`
|
|
251
|
+
| Tool | Description |
|
|
252
|
+
|------|-------------|
|
|
253
|
+
| `structured_extract_json` | Extract JSON from markdown/text (multiple strategies) |
|
|
254
|
+
| `structured_validate` | Validate response against schema |
|
|
255
|
+
| `structured_parse_evaluation` | Parse self-evaluation response |
|
|
256
|
+
| `structured_parse_decomposition` | Parse task decomposition response |
|
|
257
|
+
| `structured_parse_bead_tree` | Parse bead tree for epic creation |
|
|
179
258
|
|
|
180
259
|
## Decomposition Strategies
|
|
181
260
|
|
|
@@ -213,32 +292,32 @@ Best for: bug fixes, security issues
|
|
|
213
292
|
|
|
214
293
|
The plugin learns from outcomes:
|
|
215
294
|
|
|
216
|
-
| Mechanism
|
|
217
|
-
|
|
218
|
-
| Confidence decay
|
|
219
|
-
| Implicit feedback | Fast + success = helpful signal, slow + errors = harmful
|
|
220
|
-
| Pattern maturity
|
|
221
|
-
| Anti-patterns
|
|
295
|
+
| Mechanism | How It Works |
|
|
296
|
+
|-----------|--------------|
|
|
297
|
+
| Confidence decay | Criteria weights fade unless revalidated (90-day half-life) |
|
|
298
|
+
| Implicit feedback | Fast + success = helpful signal, slow + errors = harmful |
|
|
299
|
+
| Pattern maturity | candidate → established → proven (or deprecated) |
|
|
300
|
+
| Anti-patterns | Patterns with >60% failure rate auto-invert |
|
|
222
301
|
|
|
223
302
|
## Context Preservation
|
|
224
303
|
|
|
225
304
|
Hard limits to prevent context exhaustion:
|
|
226
305
|
|
|
227
|
-
| Constraint
|
|
228
|
-
|
|
229
|
-
| Inbox limit
|
|
230
|
-
| Bodies excluded
|
|
231
|
-
| Summarize preferred | Yes
|
|
306
|
+
| Constraint | Default | Reason |
|
|
307
|
+
|------------|---------|--------|
|
|
308
|
+
| Inbox limit | 5 messages | Prevents token burn |
|
|
309
|
+
| Bodies excluded | Always | Fetch individually when needed |
|
|
310
|
+
| Summarize preferred | Yes | Key points, not raw dump |
|
|
232
311
|
|
|
233
312
|
## Rate Limiting
|
|
234
313
|
|
|
235
314
|
Client-side limits (Redis primary, SQLite fallback):
|
|
236
315
|
|
|
237
316
|
| Endpoint | Per Minute | Per Hour |
|
|
238
|
-
|
|
239
|
-
| send
|
|
240
|
-
| reserve
|
|
241
|
-
| inbox
|
|
317
|
+
|----------|------------|----------|
|
|
318
|
+
| send | 20 | 200 |
|
|
319
|
+
| reserve | 10 | 100 |
|
|
320
|
+
| inbox | 60 | 600 |
|
|
242
321
|
|
|
243
322
|
Configure via `OPENCODE_RATE_LIMIT_{ENDPOINT}_PER_MIN` env vars.
|
|
244
323
|
|
|
@@ -249,7 +328,7 @@ bun install
|
|
|
249
328
|
bun run typecheck
|
|
250
329
|
bun test
|
|
251
330
|
bun run build
|
|
252
|
-
|
|
331
|
+
````
|
|
253
332
|
|
|
254
333
|
## License
|
|
255
334
|
|