@mdsohail99/opencode-agent-teams 2.0.0 โ†’ 2.1.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/README.md CHANGED
@@ -1,351 +1,179 @@
1
- <div align="center">
2
- <h1>๐Ÿค– OpenCode Agent Teams Relay</h1>
3
- <p><strong>Async Department-Lead Orchestration & Parallel Sub-Agent Relay Engine for OpenCode</strong></p>
4
-
5
- <p>
6
- <img src="https://img.shields.io/npm/v/opencode-agent-teams-relay?style=flat-square&color=blue" alt="NPM Version"/>
7
- <img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License"/>
8
- <img src="https://img.shields.io/github/stars/mdsohail99/opencode-agent-teams-relay?style=flat-square" alt="GitHub"/>
9
- <img src="https://img.shields.io/badge/OpenCode-Plugin-FF6B6B?style=flat-square&logo=opencode&logoColor=white" alt="OpenCode"/>
10
- <img src="https://img.shields.io/badge/Node.js-%3E%3D20.19-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js"/>
11
- <img src="https://img.shields.io/badge/TypeScript-5.0-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"/>
12
- </p>
13
- </div>
14
-
15
- ---
16
-
17
- ## ๐Ÿ“Œ Project Overview
18
-
19
- **`opencode-agent-teams-relay`** is a portable, production-grade orchestration package and background relay engine for [OpenCode](https://github.com/sst/opencode).
20
-
21
- It introduces **true asynchronous sub-agent fan-out** and a multi-agent **Department Lead architecture** into OpenCode. Instead of running single sequential sub-tasks that block your session, `opencode-agent-teams-relay` allows an orchestrator agent (`Agent-Teams`) to launch unlimited child agents in parallel, keep working independently, and react to results as they complete.
22
-
23
- Built on the principle of **Management by Exception**, successful sub-agent work digests silently into final reports, while **blockers or failures trigger immediate escalations** to spawn targeted fixer leads concurrently.
24
-
25
- ---
26
-
27
- ## โšก Features (v1.0.8)
28
-
29
- - ๐Ÿš€ **Stock OpenCode 1.18.34+ Native Compatibility**: Full native support for upstream OpenCode! Supports `subagent_depth = 2` (Root Orchestrator โ†’ Department Lead โ†’ Specialist) and native `Ctrl+B` background subagent detaching.
30
- - ๐Ÿ‘๏ธ **Visible Parallel Batch Task Mode**: Concurrent `Task` dispatch rendered natively in the terminal as live interactive `โ”‚ Task` widgets with animated spinners and toolcall logs (`โ†ณ Edit src/...`).
31
- - ๐Ÿ“ก **Detached SDK Relay Engine**: External Node.js background process connects via `@opencode-ai/sdk`, tracking `session.idle` and `session.error` events in real-time via SSE.
32
- - ๐ŸŽฎ **Swarm Slash Command Palette**: Pre-configured `/tree`, `/report`, `/ask`, `/resume`, `/stop`, and `/errors` commands for real-time swarm observability and mid-flight steering.
33
- - ๐Ÿข **7 Department Leads & 67 Specialists**: Pre-configured orchestrators (`Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA`, `Agent-Teams`) routing tasks to specialized domain agents.
34
- - ๐Ÿ›ก๏ธ **Automated Git Worktree Sandboxing**: Integrates with core worktree endpoints to allocate isolated git sandboxes per task, preventing write conflicts and git branch collisions.
35
- - ๐Ÿ” **Deterministic Error Resumption**: Seamlessly revives failed or paused agents via `Task(task_id="<id>", prompt="...")`, retaining accumulated memory, tool state, and file diffs.
36
- - โšก **Management by Exception**: Unblocked work digests silently; blockers trigger immediate escalations so fixers dispatch in parallel without waiting for unblocked streams.
37
- - โšก **Fast Capability Probing**: Instant API-based feature detection eliminates the 5-second startup freeze and ghost probe sessions on SQLite.
38
- - ๐Ÿ”’ **Shared-Secret Security**: Authenticated HTTP communications using 32-byte tokens stored in XDG-compliant state directories (`AppData/Local/opencode/...`).
39
- - ๐Ÿ“ฆ **1-Command Safe Installer**: Non-destructive installer featuring automated full-config backups, rollback capability, and smart marked-block `AGENTS.md` merging.
40
-
41
- ---
42
-
43
- ## ๐Ÿง  Resilience & Durability (v1.0.8)
44
-
45
- - ๐Ÿ’พ **Durable WAL + checkpoint state store**: The relay persists its full session tree (`nodes`, `teams`, and an append-only `events` diary) to an append-only write-ahead log (`<state-dir>/agent-teams-relay.wal`) with periodic atomic checkpoints (`<state-dir>/agent-teams-relay-state.json`) โ€” a restarted relay recovers every result, drained flag, and retry budget intact.
46
- - ๐Ÿ‘๏ธ **Full-instance visibility**: A plugin supervisor loop (10s tick, started at plugin load) health-checks and respawns the relay, and pushes the opencode server's *entire* live session list to the relay's `/reconcile` endpoint โ€” every session on the instance is monitored, not just relay-spawned children.
47
- - ๐ŸŒณ **Fast-path capability probe**: Modernized API checks query core capabilities directly without creating throwaway probe sessions, eliminating startup delays and ghost SQLite records.
48
- - ๐ŸŒฒ **Native worktree sandbox lifecycle**: Allocates isolated worktree folders for mutating parallel tasks and cleans them up automatically upon task settlement.
49
- - ๐Ÿ—‘๏ธ **Non-destructive by design**: Nothing is ever deleted automatically. Teams are cleaned up **only** after their parent session is *confirmed* deleted. Unreachability is never mistaken for deletion.
50
- - ๐Ÿ” **`resume_agent` & `task_id` resumption**: Send follow-up instructions to any alive agent session or recover failed tasks via deterministic `task_id` resumption; context and sandboxes remain preserved.
51
- - ๐ŸงŠ **Per-agent failure isolation**: Transient provider errors retry per-node (cap 3) โ€” one stuck agent goes `error` with a `needs_attention` event while sibling workers keep running uninterrupted.
52
-
53
- ---
54
-
55
- ## ๐Ÿ“Š Performance & Measured Impact
56
-
57
- *Real numbers from an in-repo orchestration run (Aug 2026). Items labeled **measured** are evidenced facts from that run; everything else is a **modeled estimate** with labeled confidence โ€” never presented as fact.*
58
-
59
- ### What actually happened (measured โœ…)
60
-
61
- | Fact | Value |
62
- |---|---|
63
- | Fan-out shape | 1 main orchestrator โ†’ **4 department leads** in one parallel batch โ†’ each spun **13 specialists** of their own |
64
- | Total concurrent sessions | **18** (1 main + 4 leads + 13 specialists) |
65
- | Wall-clock to final synthesis | **โ‰ˆ15 minutes** (measured floor) |
66
- | Cross-team escalations | **8** raised & routed while other tracks kept running โ€” none forced the run to stop |
67
-
68
- > Methodology: the first drain call returned with zero completions (no lead had finished); the four leads then drained sequentially, with the slowest lead bounding the headline runtime. **15 minutes is the measured floor**, not a ceiling โ€” larger tasks amortize the coordination tax further.
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
- ```
154
-
155
- ---
156
-
157
- ## ๐Ÿ“‹ Prerequisites First
158
-
159
- > โš ๏ธ **Important:** Ensure you have the following installed before running the quick start installer:
160
- > 1. **OpenCode** installed and configured on your machine.
161
- > 2. **Node.js >= 20.19** available in your `PATH` (the relay's durable store is an append-only WAL + periodic atomic checkpoint).
162
- > 3. Active terminal session with access to `npx`.
163
-
164
- ---
165
-
166
- ## โšก Quick Start
167
-
168
- Deploy `opencode-agent-teams-relay` directly to your local OpenCode environment with one command:
169
-
170
- ```powershell
171
- npx opencode-agent-teams-relay
172
- ```
173
-
174
- This launches an interactive TUI installer menu:
175
-
176
- ```text
177
- Agent-Teams Relay Manager
178
- =========================
179
-
180
- > 1. Install / Upgrade Agent-Teams
181
- 2. Revert to Backup
182
- 3. Check Status
183
- 4. Uninstall
184
- 5. Exit
185
- ```
186
-
187
- ---
188
-
189
- ## ๐ŸŽฎ Swarm Slash Command Palette
190
-
191
- Agent-Teams registers 6 native slash commands directly into your OpenCode configuration (`opencode.json`), giving you real-time command-and-control over the swarm:
192
-
193
- | Slash Command | Question It Answers | What It Does |
194
- | :--- | :--- | :--- |
195
- | **`/tree [filter]`** | *"Who is working right now?"* | Renders a live hierarchical ASCII parent-child tree showing running/completed agents, elapsed execution time, and `[stalled]` tags. |
196
- | **`/report [filter]`** | *"What is the status of the work?"* | Harvests all completed deliverables, code changes, and active tasks across leads to synthesize an executive summary. |
197
- | **`/ask <agent> <query>`** | *"Can I steer a worker mid-flight?"* | Sends an out-of-band side query directly to an active subagent without interrupting its execution or losing turn state. |
198
- | **`/resume <agent> [notes]`**| *"How do I un-stick a paused task?"* | Resumes a stalled, paused, or failed worker, keeping its accumulated memory, tool context, and git worktree sandbox intact. |
199
- | **`/stop [agent|all]`** | *"How do I halt runaway workers?"* | Surgically halts a specific worker or triggers an immediate full-swarm emergency stop. |
200
- | **`/errors`** | *"Did anything break?"* | Scans the swarm for failed, errored, or stalled workers and outputs actionable diagnostic traces. |
201
-
202
- ---
203
-
204
- ## โš™๏ธ Installation Modes
205
-
206
- The package ships **two installation modes** to support both upstream stock OpenCode and custom native forks:
207
-
208
- ### 1. `full` โ€” Default (Stock OpenCode + Swarm Control Plane)
209
-
210
- ```powershell
211
- npx opencode-agent-teams-relay-install
212
- # or, from this repo:
213
- .\install.ps1
214
- ```
215
-
216
- Installs the complete orchestration suite:
217
- 1. **74 Curated Agents**: `agents/orchestrators/*.md` + `agents/specialists/*.md`.
218
- 2. **`AGENTS.md` Rules**: Injects Department Lead orchestration and hub-and-spoke rules (non-destructive marker-based merge).
219
- 3. **Native `subagent_depth = 2` & `max_concurrent_agents = 20`**: Configured directly in `opencode.json` for deep hierarchy support.
220
- 4. **Slash Commands**: Registers `/tree`, `/report`, `/ask`, `/resume`, `/stop`, and `/errors` in `opencode.json`.
221
- 5. **Agent-Teams Plugin**: `plugins/agent-teams.ts` providing fast-path capability probing and bridge tools.
222
- 6. **Background Relay Daemon**: `relay/agent-teams-relay.mjs` providing out-of-band monitoring, SQLite WAL state persistence, and native git worktree sandboxing.
223
- 7. **NPM Dependency**: Adds `@opencode-ai/plugin` to `~/.config/opencode/package.json`.
224
-
225
- *Use this mode if you are running official stock OpenCode (`v1.18.34+`) from npm.*
226
-
227
- ### 2. `agents` โ€” Agents-Only (Native Fork / Ultra-Lean Mode)
228
-
229
- ```powershell
230
- npx opencode-agent-teams-relay-install --agents-only
231
- # or, from this repo:
232
- .\install.ps1 -AgentsOnly
233
- ```
234
-
235
- Installs **only**:
236
- 1. **74 Curated Agents**: Uses the fork-native orchestrator configured for in-engine `Task(background=true, daemon=true, worktree=true)`.
237
- 2. **`AGENTS.md` Rules**: Full department orchestration contracts.
238
- 3. **Native `subagent_depth = 2`**: Configured directly in `opencode.json`.
239
-
240
- *Does **NOT** install the plugin, the relay daemon, or extra npm dependencies. Zero background processes, zero open ports, zero overhead. Ideal for native forks (e.g. `anomalyco/opencode`) where background primitives are compiled directly into the binary.*
241
-
242
- ### Mode Marker & Uninstall Discipline
243
-
244
- Every installation writes `.installed-mode` (`"full"` or `"agents"`) into your OpenCode configuration directory. The uninstaller inspects this marker so it only removes what that specific mode manages:
245
- - In `agents` mode, uninstalling never touches user plugins, `node_modules`, or `package.json`.
246
- - In `full` mode, uninstaller cleans up the relay and parked plugins while preserving user settings.
247
- - Re-running the installer seamlessly switches between modes (`full` โ†” `agents`).
248
- - Check current status anytime with `npx opencode-agent-teams-relay-uninstall status`.
249
-
250
- ---
251
-
252
- ## ๐Ÿ› ๏ธ Commands & Automation
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.
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.3.2-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.3.2`).
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** (`experimental.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
+ <p align="center">
30
+ <img src="assets/agent_teams_v2_architecture.gif" alt="OpenCode Agent-Teams v2 Architecture" width="720"/>
31
+ </p>
32
+
33
+ <details>
34
+ <summary><b>View Raw Mermaid Architecture Flow</b></summary>
35
+
36
+ ```mermaid
37
+ flowchart TD
38
+ User(["๐Ÿง‘โ€๐Ÿ’ป Developer"]) -->|opencode| OC["OpenCode v2 Engine"]
39
+
40
+ subgraph Plugin["Agent-Teams v2 Plugin (In-Process)"]
41
+ OC --> Root["Depth 0: agent-teams (Root Orchestrator)"]
42
+
43
+ Root -->|Fan-Out / Escalate| Dept1["Depth 1: Backend Lead"]
44
+ Root -->|Fan-Out / Escalate| Dept2["Depth 1: Frontend Lead"]
45
+ Root -->|Fan-Out / Escalate| Dept3["Depth 1: Security Lead"]
46
+ Root -->|Fan-Out / Escalate| Dept4["Depth 1: QA Lead"]
47
+
48
+ Dept1 -->|team_delegate\nworktree: true| Spec1["Depth 2: Backend Architect\n(Git Worktree: swarm/backend-...)"]
49
+ Dept2 -->|team_delegate\nworktree: true| Spec2["Depth 2: Frontend Developer\n(Git Worktree: swarm/frontend-...)"]
50
+ Dept3 -->|team_delegate\nworktree: false| Spec3["Depth 2: AppSec Engineer\n(In-Place Read-Only Audit)"]
51
+ end
52
+
53
+ Spec1 -->|Verified & Tested| Merge1["Auto-Commit & Auto-Merge\ninto Active Branch"]
54
+ Spec2 -->|Verified & Tested| Merge2["Auto-Commit & Auto-Merge\ninto Active Branch"]
55
+
56
+ Merge1 --> Summary["Consolidated Executive Report\nto User"]
57
+ Merge2 --> Summary
58
+ Spec3 --> Summary
59
+ ```
60
+
61
+ </details>
62
+
63
+ ---
64
+
65
+ ### ๐Ÿ”„ Hub-and-Spoke: The Delegating Agent as Escalation Resolver
66
+
67
+ 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:
68
+
69
+ 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.
70
+ 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:
71
+ ```text
72
+ ESCALATE: <dept> | WHAT: <need> | WHERE: <file/module> | CONTEXT: <work done + blocker details>
73
+ ```
74
+ 3. **The Delegating Agent Resolves:** The root orchestrator (`agent-teams`) acts as the central **Escalation Resolver**:
75
+ - It intercepts the escalation without terminating the caller.
76
+ - It checks whether the target department lead is already running (to reuse active session memory) or spawns it inside an isolated Git worktree (`swarm/...`).
77
+ - 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.
78
+
79
+ ---
80
+
81
+ ## โœจ Key Features in v2
82
+
83
+ * **๐Ÿš€ 100% In-Process Native Plugin**: Built directly on `@opencode/plugin@2.3.2` and `@opencode/client@2.3.2`. No external relay daemons, no background servers, no socket tokens, and zero orphaned processes.
84
+ * **๐ŸŒณ 2-Level Hierarchical Swarms (`experimental.subagent_depth = 2`)**: Out-of-the-box support for nested multi-agent trees:
85
+ * **Depth 0**: Root Orchestrator (`agent-teams`)
86
+ * **Depth 1**: Department Leads (`backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`)
87
+ * **Depth 2**: 68 Curated Domain Specialists (`backend-architect`, `api-tester`, `a11y-auditor`, `threat-detection-engineer`, etc.)
88
+ * **๐Ÿ›ก๏ธ 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.
89
+ * **๐Ÿ› ๏ธ Swarm Control Tooling**:
90
+ * `team_delegate`: Dispatch tasks with optional Git worktree sandboxing.
91
+ * `team_status`: Inspect live progress, deliverables, and active Git worktrees.
92
+ * `team_broadcast`: Steer running teammates with instructions simultaneously.
93
+ * `team_terminate`: Gracefully halt workers and discard unneeded worktrees.
94
+ * **โŒจ๏ธ 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`.
95
+ * **๐ŸŽจ Clean Interactive TUI Installer**: Running the CLI with no arguments launches a full-featured terminal menu to inspect status, install globally, or cleanly uninstall.
96
+ * **๐Ÿงน 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.
97
+
98
+ ---
99
+
100
+ ## โšก Quickstart & Installation
101
+
102
+ ### Option 1: Automatic Installer (Global - Recommended)
103
+
104
+ Run the interactive setup tool:
105
+
106
+ ```bash
107
+ npx @mdsohail99/opencode-agent-teams
108
+ ```
109
+
110
+ This automatically:
111
+ 1. Configures your global `~/.config/opencode/opencode.json` with `"experimental": { "subagent_depth": 2 }` and registers the plugin.
112
+ 2. Copies the 75 curated Department Leads and Specialists into `~/.config/opencode/agents/`.
113
+
114
+ ---
115
+
116
+ ### Option 2: Declarative Config
117
+
118
+ Add the plugin to your global `~/.config/opencode/opencode.json` (or your project's `./opencode.json`):
119
+
120
+ ```json
121
+ {
122
+ "$schema": "https://opencode.ai/config.json",
123
+ "experimental": {
124
+ "subagent_depth": 2
125
+ },
126
+ "plugins": [
127
+ "@mdsohail99/opencode-agent-teams"
128
+ ]
129
+ }
130
+ ```
131
+
132
+ ---
133
+
134
+ ## ๐ŸŽฎ How to Use in OpenCode
135
+
136
+ 1. **Launch OpenCode**:
137
+ ```bash
138
+ opencode
139
+ ```
140
+ 2. **Select Agent-Teams**:
141
+ * Press **`Ctrl + x`** followed by **`a`**, then select `agent-teams`.
142
+ * *Or* press **`Shift + Tab`** to cycle agents.
143
+ * *Or* mention `@agent-teams` directly in your prompt.
144
+
145
+ ### Example Prompts:
146
+
147
+ #### 1. Full-Stack Parallel Feature Build (Isolated Worktrees)
148
+ > *"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`."*
149
+ - **What happens:** Backend and Frontend each receive dedicated Git worktrees. Both code simultaneously. Changes are auto-tested and merged back into your active branch.
150
+
151
+ #### 2. Comprehensive Read-Only Architectural Audit
152
+ > *"Run an architectural audit across this repository. Strict read-only mode: inspect API routes, state management, and edge cases in parallel without creating files."*
153
+ - **What happens:** The Orchestrator dispatches `backend`, `frontend`, and `security` in-place, returning an integrated Executive Findings Report.
154
+
155
+ ---
156
+
157
+ ## ๐Ÿ•น๏ธ Swarm Slash Commands
158
+
159
+ | Command | Action |
160
+ | :--- | :--- |
161
+ | **`/team`** | Displays a live ASCII hierarchy tree showing which agents are running, active worktrees, and elapsed times. |
162
+ | **`/team-status`** | Synthesizes current progress and deliverables across all active departments. |
163
+ | **`/team-stop`** | Gracefully terminates active background workers and cleans up their worktrees. |
164
+
165
+ ---
166
+
167
+ ## ๐Ÿ—‘๏ธ Clean Uninstallation
168
+
169
+ To remove Agent-Teams globally without touching any custom user agents or personal config:
170
+
171
+ ```bash
172
+ npx @mdsohail99/opencode-agent-teams uninstall
173
+ ```
174
+
175
+ ---
176
+
177
+ ## ๐Ÿ“„ License
178
+
179
+ MIT ยฉ [Sohail Mohammed](https://github.com/mdsohail99)