opencode-swarm 6.22.3 → 6.22.5

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.
Files changed (4) hide show
  1. package/README.md +195 -90
  2. package/dist/hooks/guardrails.d.ts +19 -0
  3. package/dist/index.js +973 -819
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,131 +1,189 @@
1
- # 🐝 OpenCode Swarm
1
+ # OpenCode Swarm
2
2
 
3
3
  **Your AI writes the code. Swarm makes sure it actually works.**
4
4
 
5
5
  https://swarmai.site/
6
6
 
7
- OpenCode Swarm is a plugin for [OpenCode](https://opencode.ai) that turns a single AI coding agent into a team of nine. One agent writes the code. A different agent reviews it. Another writes and runs tests. Another catches security issues. Nothing ships until every check passes. Your project state is saved to disk, so you can close your laptop, come back tomorrow, and pick up exactly where you left off.
7
+ OpenCode Swarm is a plugin for [OpenCode](https://opencode.ai) that turns a single AI coding session into an architect-led team of specialized agents. One agent writes the code. A different agent reviews it. Another writes and runs tests. Another checks security. Nothing ships until every required gate passes.
8
+
9
+ You do **not** manually switch between Swarm's internal agents during normal use.
10
+
11
+ You must **explicitly choose a Swarm architect** in the OpenCode GUI before starting. The architect name shown in OpenCode is config-driven — you can define multiple architects with different model assignments in your configuration, and those custom names will appear in the GUI dropdown.
12
+
13
+ If you use OpenCode's default `Build` / `Plan` options instead of selecting a Swarm architect, the plugin is bypassed entirely.
14
+
15
+ Once you select a Swarm architect, that architect coordinates the internal pipeline behind the scenes, and all project state is persisted to `.swarm/` so work can resume later.
8
16
 
9
17
  ```bash
10
18
  npm install -g opencode-swarm
11
19
  ```
12
20
 
13
- That's it. Open your project with `opencode` and start building. Swarm activates automatically.
14
-
15
- ---
21
+ * * *
16
22
 
17
23
  ## What Actually Happens
18
24
 
19
- You say: *"Build me a JWT auth system."*
25
+ You say:
20
26
 
21
- Here's what Swarm does behind the scenes:
27
+ ```text
28
+ Build me a JWT auth system.
29
+ ```
22
30
 
23
- 1. **Asks you clarifying questions** (only the ones it can't figure out itself)
24
- 2. **Scans your codebase** to understand what already exists
25
- 3. **Consults domain experts** (security, API design, whatever your project needs) and caches the guidance so it never re-asks
26
- 4. **Writes a phased plan** with concrete tasks, acceptance criteria, and dependencies
27
- 5. **A separate critic agent reviews the plan** before any code is written
28
- 6. **Implements one task at a time.** For each task:
29
- - A coder agent writes the code
30
- - 7 automated checks run (syntax, imports, linting, secrets, security, build, quality)
31
- - A reviewer agent (running on a *different* AI model) checks for correctness
32
- - A test engineer agent writes tests, runs them, and checks coverage
33
- - If anything fails, it goes back to the coder with specific feedback
34
- - If it passes everything, the task is marked done and the next one starts
35
- 7. **After each phase completes**, documentation updates automatically, and a retrospective captures what worked and what didn't. Those learnings carry into the next phase.
31
+ Swarm then:
36
32
 
37
- All of this state lives in a `.swarm/` folder in your project:
33
+ 1. Clarifies only what it cannot infer.
34
+ 2. Scans the codebase to understand what already exists.
35
+ 3. Consults domain experts when needed and caches the guidance.
36
+ 4. Writes a phased implementation plan.
37
+ 5. Sends that plan through a critic gate before coding starts.
38
+ 6. Executes one task at a time through the QA pipeline:
38
39
 
39
- ```
40
+ * coder writes code
41
+ * automated checks run
42
+ * reviewer checks correctness
43
+ * test engineer writes and runs tests
44
+ * failures loop back with structured feedback
45
+
46
+ 7. After each phase, docs and retrospectives are updated.
47
+
48
+ All project state lives in `.swarm/`:
49
+
50
+ ```text
40
51
  .swarm/
41
- ├── plan.md # Your project roadmap (tasks, status, what's done, what's next)
42
- ├── context.md # Decisions made, expert guidance, established patterns
43
- ├── evidence/ # Review verdicts, test results, diffs for every completed task
44
- └── history/ # Phase retrospectives and metrics
52
+ ├── plan.md
53
+ ├── context.md
54
+ ├── evidence/
55
+ └── history/
45
56
  ```
46
57
 
47
- Close your terminal. Come back next week. Swarm reads these files and picks up exactly where it stopped.
58
+ That means Swarm is resumable by design. If you come back later and `.swarm/` already exists, the architect may go straight into **RESUME** or **EXECUTE** instead of replaying the full first-run discovery flow.
48
59
 
49
60
  ---
50
61
 
51
62
  ## Why This Exists
52
63
 
53
- Most AI coding tools let one model write code and then ask *that same model* if the code is good. That's like asking someone to proofread their own essay. They'll miss the same things they missed while writing it.
54
-
55
- Swarm fixes this by splitting the work across specialized agents and requiring that different models handle writing vs. reviewing. The coder writes. A different model reviews. Another model tests. Different training data, different blind spots, different failure modes.
64
+ Most AI coding tools let one model write code and then ask that same model whether the code is good. That misses too much.
56
65
 
57
- The other thing most tools get wrong: they try to do everything in parallel. That sounds fast, but in practice you get three agents writing conflicting code at the same time with no coordination. Swarm runs one task at a time through a fixed pipeline. Slower per-task, but you don't redo work.
66
+ Swarm separates planning, implementation, review, testing, and documentation into specialized internal roles, and it enforces gated execution instead of letting multiple agents mutate the codebase in parallel.
58
67
 
59
68
  ---
60
69
 
61
70
  ## Quick Start
62
71
 
63
- ### Install
72
+ ### 1. Install
64
73
 
65
74
  ```bash
66
75
  npm install -g opencode-swarm
67
76
  ```
68
77
 
69
- ### Verify
70
-
71
- Open a project with `opencode` and run:
78
+ ### 2. Open your project in OpenCode
72
79
 
80
+ ```bash
81
+ opencode
73
82
  ```
83
+
84
+ ### 3. Verify Swarm is loaded
85
+
86
+ Run these once in a project:
87
+
88
+ ```text
74
89
  /swarm diagnose
90
+ /swarm agents
91
+ /swarm config
92
+ ```
93
+
94
+ What they tell you:
95
+
96
+ * `/swarm diagnose` verifies Swarm health and setup
97
+ * `/swarm agents` shows the registered internal agents and model assignments
98
+ * `/swarm config` shows the resolved configuration currently in effect
99
+
100
+ ### 4. Select a Swarm architect and start
101
+
102
+ 1. **Choose a Swarm architect** in the OpenCode GUI (the exact name depends on your configuration — you can define multiple architects with different model assignments)
103
+ 2. Then describe what you want to build.
104
+
105
+ ```text
106
+ Build a REST API with user registration, login, and JWT auth.
75
107
  ```
76
108
 
77
- This checks that everything is wired up correctly.
109
+ You do **not** manually choose `coder`, `reviewer`, `critic`, or other internal agents. The **architect** coordinates them automatically after you select it.
78
110
 
79
- ### Configure Models (Optional)
111
+ ### 5. Understand first run vs later runs
80
112
 
81
- By default, Swarm v6.14+ uses free OpenCode Zen models (no API key required). You can override any agent's model by creating `.opencode/opencode-swarm.json` in your project. See the [LLM Provider Guide](#llm-provider-guide) for all options.
113
+ On a brand-new project with no `.swarm/` state, Swarm usually starts by clarifying, discovering, consulting, and planning.
114
+
115
+ On a project that already has `.swarm/plan.md`, Swarm may resume immediately. That is expected.
116
+
117
+ Use these commands any time:
118
+
119
+ ```text
120
+ /swarm status
121
+ /swarm plan
122
+ /swarm history
123
+ ```
124
+
125
+ ### 6. Start over when needed
126
+
127
+ If you want a completely fresh Swarm run for the current project:
128
+
129
+ ```text
130
+ /swarm reset --confirm
131
+ ```
132
+
133
+ Use this only when you intentionally want to discard current Swarm state.
134
+
135
+ ### 7. Configure models (optional)
136
+
137
+ By default, Swarm works with its default model setup. If you want to override agent models, create:
138
+
139
+ ```text
140
+ .opencode/opencode-swarm.json
141
+ ```
142
+
143
+ Example:
82
144
 
83
145
  ```json
84
146
  {
85
147
  "agents": {
86
- "architect": { "model": "anthropic/claude-opus-4-6" },
87
- "coder": { "model": "minimax-coding-plan/MiniMax-M2.5" },
88
- "reviewer": { "model": "zai-coding-plan/glm-5" }
89
- },
90
- "guardrails": {
91
- "max_tool_calls": 200,
92
- "max_duration_minutes": 30,
93
- "profiles": {
94
- "coder": { "max_tool_calls": 500 }
95
- }
96
- },
97
- "tool_filter": {
98
- "enabled": true,
99
- "overrides": {}
100
- },
101
- "review_passes": {
102
- "always_security_review": false,
103
- "security_globs": ["**/*auth*", "**/*crypto*", "**/*session*"]
104
- },
105
- "automation": {
106
- "mode": "manual",
107
- "capabilities": {
108
- "plan_sync": false,
109
- "phase_preflight": false,
110
- "config_doctor_on_startup": false,
111
- "evidence_auto_summaries": false,
112
- "decision_drift_detection": false
113
- }
148
+ "coder": { "model": "opencode/minimax-m2.5-free" },
149
+ "reviewer": { "model": "opencode/big-pickle" }
114
150
  }
115
151
  }
116
152
  ```
117
153
 
118
- You only need to specify the agents you want to override. The rest use the default.
154
+ You only need to specify the agents you want to override.
119
155
 
120
- ### Start Building
156
+ > Note: if `architect` is not set explicitly, it inherits the current model selected in the OpenCode UI.
121
157
 
122
- Just tell OpenCode what you want to build. Swarm handles the rest.
158
+ ## Common First-Run Questions
123
159
 
160
+ ### "Do I need to select a Swarm architect?"
161
+
162
+ **Yes.** You must explicitly choose a Swarm architect agent in the OpenCode GUI before starting your session. The architect name shown in OpenCode is config-driven — you can define multiple architects with different model assignments in your configuration.
163
+
164
+ If you use the default OpenCode `Build` / `Plan` options without selecting a Swarm architect, the plugin is bypassed entirely.
165
+
166
+ ### "Why did the second run start coding immediately?"
167
+
168
+ Because Swarm persists state in `.swarm/` and resumes from where it left off. Check `/swarm status` or `/swarm plan`.
169
+
170
+ ### "How do I know Swarm is really active?"
171
+
172
+ Run:
173
+
174
+ ```text
175
+ /swarm diagnose
176
+ /swarm agents
177
+ /swarm config
124
178
  ```
125
- > Build a REST API with user registration, login, and JWT auth
126
- ```
127
179
 
128
- Use `/swarm status` at any time to see where things stand.
180
+ ### "How do I force a clean restart?"
181
+
182
+ Run:
183
+
184
+ ```text
185
+ /swarm reset --confirm
186
+ ```
129
187
 
130
188
  ---
131
189
 
@@ -198,19 +256,37 @@ For production use, mix providers to maximize quality across writing vs. reviewi
198
256
 
199
257
  ## The Agents
200
258
 
201
- Swarm has nine agents. You don't interact with them directly. The architect orchestrates everything.
259
+ Swarm has specialized internal agents, but you do **not** manually switch into them during normal use.
260
+
261
+ The **architect** is the coordinator. It decides when to invoke the other agents and what they should do.
262
+
263
+ That means the normal user workflow is:
264
+
265
+ 1. open the project in OpenCode
266
+ 2. describe what you want built or changed
267
+ 3. let Swarm coordinate the internal pipeline
268
+ 4. inspect progress with `/swarm status`, `/swarm plan`, and `/swarm evidence`
269
+
270
+ Agent roles:
202
271
 
203
272
  | Agent | Role | When It Runs |
204
- |-------|------|-------------|
205
- | **architect** | Plans the project, delegates tasks, enforces quality gates | Always (it's the coordinator) |
206
- | **explorer** | Scans your codebase to understand what exists | Before planning, after each phase |
207
- | **sme** | Domain expert (security, APIs, databases, whatever is needed) | During planning, guidance is cached |
208
- | **critic** | Reviews the plan before any code is written | After planning, before execution |
209
- | **coder** | Writes code, one task at a time | During execution |
210
- | **reviewer** | Reviews code for correctness and security issues | After every task |
211
- | **test_engineer** | Writes and runs tests, including adversarial edge cases | After every task |
212
- | **designer** | Generates UI scaffolds and design tokens (opt-in) | Before UI tasks |
213
- | **docs** | Updates documentation to match what was actually built | After each phase |
273
+ |---|---|---|
274
+ | `architect` | Coordinates the workflow, writes plans, enforces gates | Always |
275
+ | `explorer` | Scans the codebase and gathers context | Before planning, after phase wrap |
276
+ | `sme` | Provides domain guidance | During planning / consultation |
277
+ | `critic` | Reviews the plan before execution | Before coding starts |
278
+ | `coder` | Implements one task at a time | During execution |
279
+ | `reviewer` | Reviews correctness and security | After each task |
280
+ | `test_engineer` | Writes and runs tests | After each task |
281
+ | `designer` | Generates UI scaffolds and design tokens when needed | UI-specific work |
282
+ | `docs` | Updates docs to match what was actually built | After each phase |
283
+
284
+ If you want to see what is active right now, run:
285
+
286
+ ```text
287
+ /swarm status
288
+ /swarm agents
289
+ ```
214
290
 
215
291
  ---
216
292
 
@@ -259,16 +335,24 @@ If any step fails, the coder gets structured feedback and retries. After 5 failu
259
335
 
260
336
  The architect moves through these modes automatically:
261
337
 
262
- | Mode | What Happens |
263
- |------|-------------|
264
- | `RESUME` | Checks if `.swarm/plan.md` exists, picks up where it left off |
265
- | `CLARIFY` | Asks you questions (only what it can't infer) |
338
+ | Mode | What It Means |
339
+ |---|---|
340
+ | `RESUME` | Existing `.swarm/` state was found, so Swarm continues where it left off |
341
+ | `CLARIFY` | Swarm asks for missing information it cannot infer |
266
342
  | `DISCOVER` | Explorer scans the codebase |
267
343
  | `CONSULT` | SME agents provide domain guidance |
268
- | `PLAN` | Architect writes the phased plan |
269
- | `CRITIC-GATE` | Critic reviews the plan (max 2 revision cycles) |
344
+ | `PLAN` | Architect writes or updates the phased plan |
345
+ | `CRITIC-GATE` | Critic reviews the plan before execution |
270
346
  | `EXECUTE` | Tasks are implemented one at a time through the QA pipeline |
271
- | `PHASE-WRAP` | Phase completes, docs update, retrospective written |
347
+ | `PHASE-WRAP` | A phase closes out, docs are updated, and a retrospective is written |
348
+
349
+ ### Important
350
+
351
+ A second or later run does **not** necessarily look like a first run.
352
+
353
+ If `.swarm/plan.md` already exists, the architect may enter `RESUME` and then go directly into `EXECUTE`. That is expected and does **not** mean Swarm stopped using agents.
354
+
355
+ Use `/swarm status` if you are unsure what Swarm is doing.
272
356
 
273
357
  </details>
274
358
 
@@ -1077,8 +1161,28 @@ Upcoming: v6.22 focuses on further context optimization and agent coordination i
1077
1161
 
1078
1162
  ---
1079
1163
 
1164
+ ## FAQ
1165
+
1166
+ ### Do I need to select a Swarm architect?
1167
+
1168
+ **Yes.** You must explicitly choose a Swarm architect agent in the OpenCode GUI before starting your session. The architect name shown in OpenCode is config-driven — you can define multiple architects with different model assignments in your configuration.
1169
+
1170
+ If you use the default OpenCode `Build` / `Plan` options without selecting a Swarm architect, the plugin is bypassed entirely.
1171
+
1172
+ ### Why did Swarm start coding immediately on my second run?
1173
+ Because Swarm resumes from `.swarm/` state when it exists. Check `/swarm status` to see the current mode.
1174
+
1175
+ ### How do I know which agents and models are active?
1176
+ Run `/swarm agents` and `/swarm config`.
1177
+
1178
+ ### How do I start over?
1179
+ Run `/swarm reset --confirm`.
1180
+
1181
+ ---
1182
+
1080
1183
  ## Documentation
1081
1184
 
1185
+ - [Getting Started](docs/getting-started.md)
1082
1186
  - [Architecture Deep Dive](docs/architecture.md)
1083
1187
  - [Design Rationale](docs/design-rationale.md)
1084
1188
  - [Installation Guide](docs/installation.md)
@@ -1086,6 +1190,7 @@ Upcoming: v6.22 focuses on further context optimization and agent coordination i
1086
1190
  - [LLM Operator Installation Guide](docs/installation-llm-operator.md)
1087
1191
  - [Pre-Swarm Planning Guide](docs/planning.md)
1088
1192
  - [Swarm Briefing for LLMs](docs/swarm-briefing.md)
1193
+ - [Configuration](docs/configuration.md)
1089
1194
 
1090
1195
  ---
1091
1196
 
package/dist/hooks/guardrails.d.ts CHANGED
@@ -7,6 +7,25 @@
7
7
  * - Layer 2 (Hard Block @ 100%): Throws error in toolBefore to block further calls, injects STOP message
8
8
  */
9
9
  import { type GuardrailsConfig } from '../config/schema';
10
+ /**
11
+ * Retrieves stored input args for a given callID.
12
+ * Used by other hooks (e.g., delegation-gate) to access tool input args.
13
+ * @param callID The callID to look up
14
+ * @returns The stored args or undefined if not found
15
+ */
16
+ export declare function getStoredInputArgs(callID: string): unknown | undefined;
17
+ /**
18
+ * Stores input args for a given callID.
19
+ * Used by guardrails toolBefore hook; may be used by other hooks if needed.
20
+ * @param callID The callID to store args under
21
+ * @param args The tool input args to store
22
+ */
23
+ export declare function setStoredInputArgs(callID: string, args: unknown): void;
24
+ /**
25
+ * Deletes stored input args for a given callID (cleanup after retrieval).
26
+ * @param callID The callID to delete
27
+ */
28
+ export declare function deleteStoredInputArgs(callID: string): void;
10
29
  /**
11
30
  * Creates guardrails hooks for circuit breaker protection
12
31
  * @param directoryOrConfig Working directory (from plugin init context) OR legacy config object for backward compatibility