@mdsohail99/opencode-agent-teams 2.0.0 โ 2.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/AGENTS.md +64 -120
- package/CHANGELOG.md +158 -137
- package/README.md +165 -348
- package/agents/orchestrators/agent-teams.md +198 -198
- package/bin/cli.js +351 -351
- package/package.json +9 -4
- package/src/index.ts +115 -115
- package/src/state/tracker.ts +102 -102
- package/src/tools/broadcast.ts +58 -58
- package/src/tools/delegate.ts +154 -154
- package/src/tools/status.ts +25 -25
- package/src/tools/terminate.ts +70 -70
- package/src/tui.ts +9 -9
- package/src/worktree/manager.ts +142 -142
- package/agents/orchestrators-fork/orchestrator-agent-teams.md +0 -203
- package/bin/install.mjs +0 -418
- package/bin/lib/config-root.mjs +0 -51
- package/bin/lib/merge-commands.mjs +0 -138
- package/bin/lib/merge-env-flags.mjs +0 -92
- package/bin/lib/merge-schema.mjs +0 -77
- package/bin/lib/merge-subagent-depth.mjs +0 -133
- package/bin/lib/plugin-park.mjs +0 -48
- package/bin/lib/relay-process.mjs +0 -116
- package/bin/lib/runtime-state.mjs +0 -118
- package/bin/menu.mjs +0 -582
- package/bin/uninstall.mjs +0 -360
package/README.md
CHANGED
|
@@ -1,351 +1,168 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
<h1
|
|
3
|
-
<p><strong>
|
|
4
|
-
|
|
5
|
-
<p>
|
|
6
|
-
<img src="https://img.shields.io/npm/v/opencode-agent-teams
|
|
7
|
-
<img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License"/>
|
|
8
|
-
<img src="https://img.shields.io/
|
|
9
|
-
<img src="https://img.shields.io/badge/
|
|
10
|
-
<img src="https://img.shields.io/badge/
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
##
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
### Counterfactual: the same task as a single agent (modeled estimate)
|
|
71
|
-
|
|
72
|
-
A single agent doing all four departments must work serially and hold one monolithic context:
|
|
73
|
-
|
|
74
|
-
1. **Wall-clock โ 4ร slower.** Four department passes in sequence (~11โ15 min each) โ **45โ60 min total**. No LLM parallelism โ one brain, one token stream at a time; nothing is "background-computed."
|
|
75
|
-
2. **Context exhaustion risk.** One agent accumulates the entire task across all four domains. Past a point, truncation/eviction risk โ incomplete deliverables โ re-runs, which multiply effective time *and* tokens.
|
|
76
|
-
3. **Worse token profile per useful unit.** A single agent re-reads shared files, holds cross-domain working notes, and emits extra tokens just to keep state coherent in one window โ the "same budget, worse signal-to-noise" failure mode.
|
|
77
|
-
|
|
78
|
-
### Side-by-side
|
|
79
|
-
|
|
80
|
-
| Metric | Team (measured) | Single agent (modeled) |
|
|
81
|
-
|---|---|---|
|
|
82
|
-
| Wall-clock to complete run | **โ15 min** | โ45โ60 min |
|
|
83
|
-
| Concurrent work-streams | **18** | 1 |
|
|
84
|
-
| Context per unit of work | Small, focused per agent | Monolithic, grows to overflow |
|
|
85
|
-
| Blocker breakdown | Escalated & fixed in parallel | Run stalls |
|
|
86
|
-
| Risk of context overflow / truncation | **~0 sessions lost** | High (everything at risk near the end) |
|
|
87
|
-
| Total raw LLM tokens | Higher (more sessions, duplicated groundwork) | Baseline (fewer, but less reliable) |
|
|
88
|
-
|
|
89
|
-
### The honest trade-off
|
|
90
|
-
|
|
91
|
-
Team orchestration is **not** "faster *and* cheaper on tokens" โ that's the part elevator pitches get wrong. The real exchange is:
|
|
92
|
-
|
|
93
|
-
> **You trade total tokens produced for elapsed wall-clock time, fault isolation, and a focused context per responsibility.**
|
|
94
|
-
|
|
95
|
-
- **More total tokens** โ 18 sessions each reason independently (duplicated groundwork, shared-file reads) vs. one session.
|
|
96
|
-
- **Far less wall-clock (~4ร)** and **far lower truncation risk** โ work advances in parallel and each context stays small.
|
|
97
|
-
|
|
98
|
-
The coordination "tax" is real: orchestrator handoff, re-briefing each agent, collecting results โ non-trivial per-turn overhead. **It pays off only when a task is big enough to amortize that tax** โ i.e., decomposable into independent tracks.
|
|
99
|
-
|
|
100
|
-
### Bottom line
|
|
101
|
-
|
|
102
|
-
> โฑ **~15 min vs ~1 hr** (measured vs modeled) ยท ๐ **18 parallel sessions vs 1** ยท ๐ **~4ร wall-clock reduction** via parallel fan-out ยท ๐ก **escalations recover concurrently, not serially**. The team made the run **~4ร faster and dramatically safer at the tail end**, at the explicit cost of **higher total LLM tokens** โ the classic tokens-for-throughput swap.
|
|
103
|
-
|
|
104
|
-
---
|
|
105
|
-
|
|
106
|
-
## ๐๏ธ Architecture
|
|
107
|
-
|
|
108
|
-
```mermaid
|
|
109
|
-
flowchart TD
|
|
110
|
-
User(["๐ค User"]) --> Main1["๐ค Agent-Teams (Depth 0)"] --> Relay["๐ก Relay & Swarm Control\n(/tree โข /ask โข Worktrees)"]
|
|
111
|
-
|
|
112
|
-
subgraph "โก Parallel Hierarchy (subagent_depth = 2)"
|
|
113
|
-
Relay --> L_A["๐ข Frontend Lead"] & L_B["๐ข Backend Lead"] & L_C["๐ข QA Lead"]
|
|
114
|
-
|
|
115
|
-
L_A --> S_A1["๐ ๏ธ UI Specialist"] & S_A2["๐ ๏ธ CSS Specialist"]
|
|
116
|
-
L_B --> S_B1["๐ ๏ธ API Specialist"] & S_B2["โ ๏ธ DB Specialist (Block)"]
|
|
117
|
-
L_C --> S_C1["๐ ๏ธ E2E Tester"] & S_C2["๐ ๏ธ Perf Specialist"]
|
|
118
|
-
end
|
|
119
|
-
|
|
120
|
-
Main2["๐ค Agent-Teams (Escalate)"]
|
|
121
|
-
Fixer["๐ง Fixer Lead"]
|
|
122
|
-
S_B2_F["๐ ๏ธ DB Specialist (Fixed)"]
|
|
123
|
-
Report["๐ Consolidated Report"]
|
|
124
|
-
|
|
125
|
-
%% Error Flow
|
|
126
|
-
S_B2 -->|Escalates| Main2 -.->|Fixes| Fixer -.-> S_B2_F
|
|
127
|
-
|
|
128
|
-
%% Success Flow
|
|
129
|
-
S_A1 & S_A2 & S_B1 & S_C1 & S_C2 --> Report
|
|
130
|
-
S_B2_F --> Report
|
|
131
|
-
|
|
132
|
-
%% Final Return
|
|
133
|
-
Report --> Main3["๐ค Agent-Teams"] --> User2(["๐ค User"])
|
|
134
|
-
|
|
135
|
-
%% Styling
|
|
136
|
-
classDef user fill:#34495e,color:#fff,stroke:#2c3e50,stroke-width:1px
|
|
137
|
-
classDef main fill:#e74c3c,color:#fff,stroke:#c0392b,stroke-width:1px
|
|
138
|
-
classDef relay fill:#9b59b6,color:#fff,stroke:#8e44ad,stroke-width:1px
|
|
139
|
-
classDef team fill:#8e44ad,color:#fff,stroke:#8e44ad,stroke-width:1px
|
|
140
|
-
classDef spec fill:#3498db,color:#fff,stroke:#2980b9,stroke-width:1px
|
|
141
|
-
classDef blocked fill:#e67e22,color:#fff,stroke:#d35400,stroke-width:1px
|
|
142
|
-
classDef fixer fill:#27ae60,color:#fff,stroke:#2ecc71,stroke-width:1px
|
|
143
|
-
classDef report fill:#16a085,color:#fff,stroke:#1abc9c,stroke-width:1px
|
|
144
|
-
|
|
145
|
-
class User,User2 user
|
|
146
|
-
class Main1,Main2,Main3 main
|
|
147
|
-
class Relay relay
|
|
148
|
-
class L_A,L_B,L_C team
|
|
149
|
-
class S_A1,S_A2,S_B1,S_C1,S_C2,S_B2_F spec
|
|
150
|
-
class S_B2 blocked
|
|
151
|
-
class Fixer fixer
|
|
152
|
-
class Report report
|
|
153
|
-
```
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>โก OpenCode Agent-Teams v2</h1>
|
|
3
|
+
<p><strong>Native Hierarchical Multi-Agent Swarms & Automated Git Worktree Sandboxing for OpenCode v2</strong></p>
|
|
4
|
+
|
|
5
|
+
<p>
|
|
6
|
+
<a href="https://www.npmjs.com/package/@mdsohail99/opencode-agent-teams"><img src="https://img.shields.io/npm/v/@mdsohail99/opencode-agent-teams?style=flat-square&color=blue" alt="NPM Version"/></a>
|
|
7
|
+
<img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License"/>
|
|
8
|
+
<img src="https://img.shields.io/badge/OpenCode-v2.1.1-FF6B6B?style=flat-square&logo=opencode&logoColor=white" alt="OpenCode v2"/>
|
|
9
|
+
<img src="https://img.shields.io/badge/Node.js-%3E%3D20.19-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js"/>
|
|
10
|
+
<img src="https://img.shields.io/badge/TypeScript-5.0-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"/>
|
|
11
|
+
</p>
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## ๐ Overview
|
|
17
|
+
|
|
18
|
+
**`@mdsohail99/opencode-agent-teams`** is the official **native multi-agent orchestration plugin** for [OpenCode v2](https://github.com/sst/opencode) (`@opencode/cli@2.1.1`).
|
|
19
|
+
|
|
20
|
+
In v1, running multi-agent swarms required external Node.js relay daemons, port tokens, and background socket connections.
|
|
21
|
+
**In v2, the relay is completely eliminated.**
|
|
22
|
+
|
|
23
|
+
Agent-Teams v2 runs **100% in-process** using OpenCode's native `@opencode/plugin` and `@opencode/client` architecture. It enables high-performance **2-level hierarchical swarms** (`subagent_depth = 2`), **isolated Git worktree sandboxing**, and real-time swarm steering with **zero background processes, zero localhost ports, and zero configuration bloat**.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## ๐๏ธ v2 Swarm Architecture
|
|
28
|
+
|
|
29
|
+
```mermaid
|
|
30
|
+
flowchart TD
|
|
31
|
+
User(["๐งโ๐ป Developer"]) -->|opencode| OC["OpenCode v2 Engine"]
|
|
32
|
+
|
|
33
|
+
subgraph Plugin["Agent-Teams v2 Plugin (In-Process)"]
|
|
34
|
+
OC --> Root["Depth 0: agent-teams (Root Orchestrator)"]
|
|
35
|
+
|
|
36
|
+
Root -->|Fan-Out / Escalate| Dept1["Depth 1: Backend Lead"]
|
|
37
|
+
Root -->|Fan-Out / Escalate| Dept2["Depth 1: Frontend Lead"]
|
|
38
|
+
Root -->|Fan-Out / Escalate| Dept3["Depth 1: Security Lead"]
|
|
39
|
+
Root -->|Fan-Out / Escalate| Dept4["Depth 1: QA Lead"]
|
|
40
|
+
|
|
41
|
+
Dept1 -->|team_delegate\nworktree: true| Spec1["Depth 2: Backend Architect\n(Git Worktree: swarm/backend-...)"]
|
|
42
|
+
Dept2 -->|team_delegate\nworktree: true| Spec2["Depth 2: Frontend Developer\n(Git Worktree: swarm/frontend-...)"]
|
|
43
|
+
Dept3 -->|team_delegate\nworktree: false| Spec3["Depth 2: AppSec Engineer\n(In-Place Read-Only Audit)"]
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
Spec1 -->|Verified & Tested| Merge1["Auto-Commit & Auto-Merge\ninto Active Branch"]
|
|
47
|
+
Spec2 -->|Verified & Tested| Merge2["Auto-Commit & Auto-Merge\ninto Active Branch"]
|
|
48
|
+
|
|
49
|
+
Merge1 --> Summary["Consolidated Executive Report\nto User"]
|
|
50
|
+
Merge2 --> Summary
|
|
51
|
+
Spec3 --> Summary
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
### ๐ Hub-and-Spoke: The Delegating Agent as Escalation Resolver
|
|
57
|
+
|
|
58
|
+
In multi-agent swarms, letting specialists or leads call arbitrary peer agents causes unbounded circular recursion and write collisions. Agent-Teams enforces a strict **Hub-and-Spoke Management by Exception** protocol:
|
|
59
|
+
|
|
60
|
+
1. **Strict Department Scoping:** Department Leads (`backend`, `frontend`, `qa`, etc.) can only dispatch their own subagent specialists. A lead *never* launches a peer department lead directly.
|
|
61
|
+
2. **Management by Exception (`ESCALATE`):** If a lead encounters a cross-cutting blocker (e.g., `qa` detects an unhandled backend endpoint, or `frontend` requires a new authentication schema), the lead immediately returns:
|
|
62
|
+
```text
|
|
63
|
+
ESCALATE: <dept> | WHAT: <need> | WHERE: <file/module> | CONTEXT: <work done + blocker details>
|
|
64
|
+
```
|
|
65
|
+
3. **The Delegating Agent Resolves:** The root orchestrator (`agent-teams`) acts as the central **Escalation Resolver**:
|
|
66
|
+
- It intercepts the escalation without terminating the caller.
|
|
67
|
+
- It checks whether the target department lead is already running (to reuse active session memory) or spawns it inside an isolated Git worktree (`swarm/...`).
|
|
68
|
+
- Once the fix is verified and merged, `agent-teams` hands the context back to the originating lead, allowing it to complete its remaining work seamlessly.
|
|
154
69
|
|
|
155
70
|
---
|
|
156
71
|
|
|
157
|
-
##
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
For CI/CD scripts or automated deployment, use non-interactive binary commands:
|
|
255
|
-
|
|
256
|
-
| Command | Description |
|
|
257
|
-
|---|---|
|
|
258
|
-
| `npx opencode-agent-teams-relay` | Interactive TUI menu (install, upgrade, revert, status) |
|
|
259
|
-
| `npx opencode-agent-teams-relay-install` | Direct, non-interactive installation script (full mode) |
|
|
260
|
-
| `npx opencode-agent-teams-relay-install --agents-only` | Agents-only install (no plugin/relay/npm โ native fork) |
|
|
261
|
-
| `npx opencode-agent-teams-relay-uninstall` | Non-interactive uninstaller & revert utility |
|
|
262
|
-
|
|
263
|
-
### Non-Interactive Flag Examples
|
|
264
|
-
|
|
265
|
-
```powershell
|
|
266
|
-
# Direct silent installation (full mode)
|
|
267
|
-
npx opencode-agent-teams-relay-install
|
|
268
|
-
|
|
269
|
-
# Agents-only installation (native fork โ no plugin/relay/npm)
|
|
270
|
-
npx opencode-agent-teams-relay-install --agents-only
|
|
271
|
-
|
|
272
|
-
# Check current installation, installed mode & available backups
|
|
273
|
-
npx opencode-agent-teams-relay-uninstall status
|
|
274
|
-
|
|
275
|
-
# Revert to most recent automatic backup
|
|
276
|
-
npx opencode-agent-teams-relay-uninstall revert
|
|
277
|
-
|
|
278
|
-
# Revert to a specific backup version
|
|
279
|
-
npx opencode-agent-teams-relay-uninstall revert v0.1.0
|
|
280
|
-
|
|
281
|
-
# Complete clean uninstall (preserves custom AGENTS.md rules; agents-only mode
|
|
282
|
-
# also preserves any other user plugins)
|
|
283
|
-
npx opencode-agent-teams-relay-uninstall uninstall
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
### Local PowerShell Installation
|
|
287
|
-
|
|
288
|
-
```powershell
|
|
289
|
-
cd c:\Dev\opencode\orchestration
|
|
290
|
-
.\install.ps1 # full mode (default)
|
|
291
|
-
.\install.ps1 -AgentsOnly # agents-only mode (native fork)
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
---
|
|
295
|
-
|
|
296
|
-
## ๐ Department Leads & Agents
|
|
297
|
-
|
|
298
|
-
This package provisions **7 Orchestrators** and **67 Specialist Agents** into your `~/.config/opencode/agents/` directory:
|
|
299
|
-
|
|
300
|
-
| Department | Orchestrator Agent | Specialized Domain Agents |
|
|
301
|
-
|---|---|---|
|
|
302
|
-
| โก **Async Fan-Out** | **`Agent-Teams`** | Multi-agent parallel routing (`running_agents`, `next_agent`, `agents_status`) |
|
|
303
|
-
| ๐จ **Frontend** | `Frontend` | `Frontend Developer`, `UI Designer`, `UX Architect`, `Accessibility Auditor`, `USWDS Developer` |
|
|
304
|
-
| โ๏ธ **Backend** | `Backend` | `Backend Architect`, `Database Optimizer`, `API Platform Engineer`, `Payments Billing Engineer`, `Rust Refactoring Specialist` |
|
|
305
|
-
| ๐ก๏ธ **Security** | `Security` | `Security Architect`, `Penetration Tester`, `Cloud Security Architect`, `Secrets Credential Hygiene Engineer`, `Privacy Engineer` |
|
|
306
|
-
| ๐ **DevOps** | `DevOps` | `DevOps Automator`, `SRE (Site Reliability Engineer)`, `FinOps Engineer`, `IoT Fleet Engineer`, `Incident Response Commander` |
|
|
307
|
-
| ๐ง **AI & Data** | `AI & Data` | `AI Engineer`, `RAG Pipeline Engineer`, `Prompt Engineer`, `Data Engineer`, `Search Relevance Engineer` |
|
|
308
|
-
| ๐งช **QA** | `QA` | `Test Automation Engineer`, `API Tester`, `Performance Benchmarker`, `Reality Checker`, `Test Results Analyzer` |
|
|
309
|
-
|
|
310
|
-
---
|
|
311
|
-
|
|
312
|
-
## ๐ Upgrade & Automatic Backup System
|
|
313
|
-
|
|
314
|
-
Every installation automatically creates a full, timestamped backup before modifying your configuration:
|
|
315
|
-
|
|
316
|
-
1. **Detection:** Reads `.installed-version` in your OpenCode config folder.
|
|
317
|
-
2. **Full Backup:** Copies entire config state to `~/.config/opencode/.backups/<version>-<timestamp>/`.
|
|
318
|
-
3. **Smart Merge:** Injects or updates the `AGENTS.md` orchestration block using start/end markers (`<!-- agent-teams-orchestration:start -->`), **preserving all existing user rules**.
|
|
319
|
-
4. **Pruning:** Automatically keeps the last 5 backups and prunes older entries to conserve space.
|
|
320
|
-
|
|
321
|
-
### Backup Storage Directory
|
|
322
|
-
|
|
323
|
-
```text
|
|
324
|
-
~/.config/opencode/.backups/
|
|
325
|
-
โโโ v0.1.0-2026-08-05T20-45-00/
|
|
326
|
-
โ โโโ agents/
|
|
327
|
-
โ โโโ plugins/
|
|
328
|
-
โ โโโ relay/
|
|
329
|
-
โ โโโ .installed-version
|
|
330
|
-
โโโ .backup-version
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
---
|
|
334
|
-
|
|
335
|
-
## ๐ Security & Context Isolation
|
|
336
|
-
|
|
337
|
-
- **Token Protection:** The background relay generates a cryptographically secure 32-byte hex token on startup. All IPC requests require a matching `Authorization: Bearer <token>` header.
|
|
338
|
-
- **Port Isolation:** Every OpenCode server URL gets a unique, hash-derived relay port (20000โ50000). Multiple terminal windows and projects remain completely isolated.
|
|
339
|
-
- **Context Preservation:** Sub-agent completions return **only final assistant text summaries** to parent sessions, preventing transcript inflation.
|
|
340
|
-
|
|
341
|
-
---
|
|
342
|
-
|
|
343
|
-
## ๐ค Contributing
|
|
344
|
-
|
|
345
|
-
Contributions of new specialized agents, workflow patterns, and relay optimizations are welcome! Please feel free to open an issue or submit a pull request.
|
|
346
|
-
|
|
347
|
-
---
|
|
348
|
-
|
|
349
|
-
## ๐ License
|
|
350
|
-
|
|
351
|
-
Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for details.
|
|
72
|
+
## โจ Key Features in v2
|
|
73
|
+
|
|
74
|
+
* **๐ 100% In-Process Native Plugin**: Built directly on `@opencode/plugin@2.1.1` and `@opencode/client@2.1.1`. No external relay daemons, no background servers, no socket tokens, and zero orphaned processes.
|
|
75
|
+
* **๐ณ 2-Level Hierarchical Swarms (`subagent_depth = 2`)**: Out-of-the-box support for nested multi-agent trees:
|
|
76
|
+
* **Depth 0**: Root Orchestrator (`agent-teams`)
|
|
77
|
+
* **Depth 1**: Department Leads (`backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`)
|
|
78
|
+
* **Depth 2**: 68 Curated Domain Specialists (`backend-architect`, `api-tester`, `a11y-auditor`, `threat-detection-engineer`, etc.)
|
|
79
|
+
* **๐ก๏ธ Automated Git Worktree Sandboxing**: Never suffer from file collisions when parallel agents write code. `team_delegate(worktree: true)` creates dedicated branches (`swarm/...`), allows the agent to build and test in isolation, auto-commits verified changes, and merges back to your working branch cleanly.
|
|
80
|
+
* **๐ ๏ธ Swarm Control Tooling**:
|
|
81
|
+
* `team_delegate`: Dispatch tasks with optional Git worktree sandboxing.
|
|
82
|
+
* `team_status`: Inspect live progress, deliverables, and active Git worktrees.
|
|
83
|
+
* `team_broadcast`: Steer running teammates with instructions simultaneously.
|
|
84
|
+
* `team_terminate`: Gracefully halt workers and discard unneeded worktrees.
|
|
85
|
+
* **โจ๏ธ Dynamic In-Memory Slash Commands**: `/team`, `/team-status`, and `/team-stop` are injected dynamically at runtime via `ctx.command.transform()`. Zero hardcoded bloat in your `opencode.json`.
|
|
86
|
+
* **๐จ Clean Interactive TUI Installer**: Running the CLI with no arguments launches a full-featured terminal menu to inspect status, install globally, or cleanly uninstall.
|
|
87
|
+
* **๐งน Manifest-Tracked Clean Uninstall**: Installs a `.agent-teams-manifest.json` tracking all 75 curated agents. Running `uninstall` deletes strictly the plugin-owned files, preserving any custom agents you added.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## โก Quickstart & Installation
|
|
92
|
+
|
|
93
|
+
### Option 1: Automatic Installer (Global - Recommended)
|
|
94
|
+
|
|
95
|
+
Run the interactive setup tool:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
npx @mdsohail99/opencode-agent-teams
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
This automatically:
|
|
102
|
+
1. Configures your global `~/.config/opencode/opencode.json` with `"subagent_depth": 2` and registers the plugin.
|
|
103
|
+
2. Copies the 75 curated Department Leads and Specialists into `~/.config/opencode/agents/`.
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
### Option 2: Declarative Config
|
|
108
|
+
|
|
109
|
+
Add the plugin to your global `~/.config/opencode/opencode.json` (or your project's `./opencode.json`):
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{
|
|
113
|
+
"$schema": "https://opencode.ai/config.json",
|
|
114
|
+
"subagent_depth": 2,
|
|
115
|
+
"plugins": [
|
|
116
|
+
"@mdsohail99/opencode-agent-teams"
|
|
117
|
+
]
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## ๐ฎ How to Use in OpenCode
|
|
124
|
+
|
|
125
|
+
1. **Launch OpenCode**:
|
|
126
|
+
```bash
|
|
127
|
+
opencode
|
|
128
|
+
```
|
|
129
|
+
2. **Select Agent-Teams**:
|
|
130
|
+
* Press **`Ctrl + x`** followed by **`a`**, then select `agent-teams`.
|
|
131
|
+
* *Or* press **`Shift + Tab`** to cycle agents.
|
|
132
|
+
* *Or* mention `@agent-teams` directly in your prompt.
|
|
133
|
+
|
|
134
|
+
### Example Prompts:
|
|
135
|
+
|
|
136
|
+
#### 1. Full-Stack Parallel Feature Build (Isolated Worktrees)
|
|
137
|
+
> *"Build user authentication: have Backend implement the JWT endpoints in `src/routes/auth.js` while Frontend creates the login dialog in `src/components/LoginModal.tsx`."*
|
|
138
|
+
- **What happens:** Backend and Frontend each receive dedicated Git worktrees. Both code simultaneously. Changes are auto-tested and merged back into your active branch.
|
|
139
|
+
|
|
140
|
+
#### 2. Comprehensive Read-Only Architectural Audit
|
|
141
|
+
> *"Run an architectural audit across this repository. Strict read-only mode: inspect API routes, state management, and edge cases in parallel without creating files."*
|
|
142
|
+
- **What happens:** The Orchestrator dispatches `backend`, `frontend`, and `security` in-place, returning an integrated Executive Findings Report.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## ๐น๏ธ Swarm Slash Commands
|
|
147
|
+
|
|
148
|
+
| Command | Action |
|
|
149
|
+
| :--- | :--- |
|
|
150
|
+
| **`/team`** | Displays a live ASCII hierarchy tree showing which agents are running, active worktrees, and elapsed times. |
|
|
151
|
+
| **`/team-status`** | Synthesizes current progress and deliverables across all active departments. |
|
|
152
|
+
| **`/team-stop`** | Gracefully terminates active background workers and cleans up their worktrees. |
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## ๐๏ธ Clean Uninstallation
|
|
157
|
+
|
|
158
|
+
To remove Agent-Teams globally without touching any custom user agents or personal config:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
npx @mdsohail99/opencode-agent-teams uninstall
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## ๐ License
|
|
167
|
+
|
|
168
|
+
MIT ยฉ [Sohail Mohammed](https://github.com/mdsohail99)
|