Skip to content
Back to search

opencode-ensemble

Agent teams for OpenCode. Run multiple agents in parallel with messaging, shared tasks, and coordinated execution.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/hueyexe/opencode-ensemble with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/hueyexe/opencode-ensemble'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hueyexe--opencode-ensemble/badge.svg)](/listings/hueyexe--opencode-ensemble)

HTML

<a href="/listings/hueyexe--opencode-ensemble"><img src="/api/listings/hueyexe--opencode-ensemble/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the plugin and you're done:

opencode plugin add @hueyexe/opencode-ensemble@0.18.0

Then restart OpenCode and ask it to do something that benefits from parallel work. The agent handles the rest. See [Install](#install) for worktree permissions and other options.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 503 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="social-preview.png" alt="OpenCode Ensemble - Parallel agents. One coordinated team." width="100%">
  3. </p>
  4. # OpenCode Ensemble
  5. [![npm version](https://img.shields.io/npm/v/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
  6. [![npm downloads](https://img.shields.io/npm/dm/@hueyexe/opencode-ensemble.svg)](https://www.npmjs.com/package/@hueyexe/opencode-ensemble)
  7. [![CI](https://github.com/hueyexe/opencode-ensemble/actions/workflows/ci.yml/badge.svg)](https://github.com/hueyexe/opencode-ensemble/actions/workflows/ci.yml)
  8. [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)]()
  9. [![deps](https://img.shields.io/badge/deps-runtime%3A%20OpenCode%20SDKs-blue.svg)]()
  10. [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
  11. Run parallel AI agents in OpenCode. Each agent gets its own session, context window, and task. They coordinate through messaging and a shared task board.
  12. Built on the public OpenCode SDKs — no OpenCode internals. Runtime dependencies are the three OpenCode SDK packages (`@opencode-ai/sdk`, `@opencode-ai/plugin`, `@opencode/plugin`). The bundled TUI companion additionally uses SolidJS and OpenTUI, provided by the OpenCode host and declared as peer dependencies.
  13. ## Quick Start
  14. Install the plugin and you're done:
  15. ```sh
  16. opencode plugin add @hueyexe/opencode-ensemble@latest
  17. ```
  18. Then restart OpenCode and ask it to do something that benefits from parallel work. The agent handles the rest. See [Install](#install) for worktree permissions and other options.
  19. ## What actually happens
  20. You ask the agent to do something complex. It creates a team, spawns teammates, and they work in parallel. Each teammate runs in its own OpenCode session with a fresh context window.
  21. A realistic development-team interaction:
  22. ```
  23. You: "Fix checkout idempotency so duplicate Stripe webhooks cannot create
  24. duplicate orders. Add regression tests and review the final diff for risk."
  25. The lead agent:
  26. 1. Creates a team called "checkout-idempotency".
  27. 2. Adds independent tasks first and records the generated task IDs.
  28. 3. Adds dependent QA and review tasks with `depends_on` using real returned IDs.
  29. 4. Spawns a small team with explicit roles:
  30. - scout: explore agent, worktree disabled, model openai/gpt-5-mini (example)
  31. - api-dev: build agent, own worktree, model anthropic/claude-opus-4-7 (example), plan_approval: true
  32. - qa: build agent, own worktree, model anthropic/claude-opus-4-7 (example)
  33. - reviewer: explore agent, worktree disabled, model openai/gpt-5-mini (example)
  34. ```
  35. The lead uses the task board to make sequencing visible. Record the returned task IDs before creating dependent tasks:
  36. ```ts
  37. team_tasks_add({
  38. tasks: [
  39. { content: "Map checkout webhook flow and identify idempotency risks", priority: "high" },
  40. { content: "Implement duplicate-webhook idempotency guard", priority: "high" },
  41. ],
  42. })
  43. // -> Added 2 tasks: task_abc123, task_def456
  44. team_tasks_add({
  45. tasks: [
  46. { content: "Add regression tests for duplicate webhook delivery", priority: "high", depends_on: ["task_def456"] },
  47. ],
  48. })
  49. // -> Added 1 task: task_ghi789
  50. team_tasks_add({
  51. tasks: [
  52. { content: "Review final diff for order, payment, and retry risks", priority: "medium", depends_on: ["task_def456", "task_ghi789"] },
  53. ],
  54. })
  55. // -> Added 1 task: task_jkl012
  56. ```
  57. Then it spawns teammates one at a time:
  58. ```ts
  59. team_spawn({
  60. name: "scout",
  61. agent: "explore",
  62. worktree: false,
  63. model: "openai/gpt-5-mini",
  64. claim_task: "task_abc123",
  65. prompt: "Trace the checkout webhook flow. Report the files, data model, existing tests, and the smallest safe implementation plan. Do not edit files.",
  66. })
  67. team_spawn({
  68. name: "api-dev",
  69. agent: "build",
  70. model: "anthropic/claude-opus-4-7",
  71. plan_approval: true,
  72. claim_task: "task_def456",
  73. prompt: "After scout reports, implement the idempotency guard. Keep the change narrow. Commit your work and send a task-result message.",
  74. })
  75. ```
  76. The same pattern assigns `qa` to regression tests and `reviewer` to final review. The reviewer stays read-only (`worktree: false`) so it can inspect merged changes without producing another branch.
  77. Teammates coordinate without the lead polling:
  78. ```
  79. scout -> lead: "Checkout flow is src/webhooks/stripe.ts -> createOrderFromPayment(). Existing tests are in test/checkout-webhook.test.ts. Risk: retries race before order insert commits."
  80. api-dev -> lead: "Plan ready: add unique event_id insert before order creation, treat duplicate insert as success, add a transaction around order creation."
  81. lead -> api-dev: approves plan
  82. qa -> api-dev: "Which duplicate signal should tests assert: event_id conflict or existing order lookup?"
  83. api-dev -> qa: "Assert duplicate event_id returns success and creates one order. See src/webhooks/stripe.ts."
  84. ```
  85. When work is done, the lead reviews and integrates deliberately:
  86. ```
  87. team_results({ from: "api-dev" })
  88. team_shutdown({ member: "api-dev" })
  89. team_merge({ member: "api-dev" })
  90. team_results({ from: "qa" })
  91. team_shutdown({ member: "qa" })
  92. team_merge({ member: "qa" })
  93. team_spawn({ name: "reviewer", agent: "explore", worktree: false, claim_task: "task_jkl012", prompt: "Review the merged diff for correctness, missed tests, and risky behavior. Do not edit files." })
  94. ```
  95. The lead runs the repository verification commands, summarizes the result, and only then cleans up the team. All merged teammate changes remain in your working directory as unstaged changes for review with `git diff`.
  96. ## Agent Skill
  97. Install the companion skill to teach your AI how to form useful Ensemble teams, write better teammate prompts, choose models, and avoid common coordination failures:
  98. ```bash
  99. npx skills@latest add hueyexe/opencode-ensemble --skill opencode-ensemble
  100. ```
  101. Inside this repository the skill lives at `.agents/skills/opencode-ensemble`, so OpenCode discovers it automatically while working on Ensemble itself. The `skills/` entry is a symlink kept for the skills CLI.
  102. The skill is useful when you want the agent to decide whether parallel work is appropriate, split work into independent slices, use `depends_on` correctly, or pick a safe mix of `explore` and `build` teammates.
  103. Good team shapes:
  104. - **Scout, builder, reviewer**: one read-only `explore` agent maps the code, one `build` agent changes it, one read-only `explore` agent reviews the diff.
  105. - **Parallel slices**: two or three `build` agents own independent files or vertical slices, then one reviewer checks the combined result.
  106. - **Risky change**: use `plan_approval: true` on the implementing teammate, then approve or reject the plan through `team_message` before edits begin.
  107. ## Dashboard
  108. A real-time mission control dashboard runs at `http://localhost:4747` while OpenCode is active.
  109. ![Ensemble Dashboard](docs/dashboard.png)
  110. - **Health ring** — at-a-glance team health indicator in the header
  111. - **Agent cards** — status, current task, activity sparklines, timing. Click to open detail drawer
  112. - **Agent drawer** — full prompt, model, execution status, chat-style message history with markdown rendering
  113. - **Task board** — progress bar, collapsible status groups, dependency arrows
  114. - **Dependency graph tab** — task cards with agent ownership, prerequisite arrows,
  115. dependency inspection, live updates, and missing/cyclic dependency warnings
  116. - **Activity feed** — chat-style message bubbles with avatars, expandable with full markdown
  117. - **Timeline** — horizontal event strip showing spawns, messages, completions, shutdowns
  118. - **Keyboard shortcuts** — `j/k` navigate agents, `Enter` opens drawer, `Esc` closes, `?` shows help
  119. - **Live clock** — current time + team session duration
  120. - **Project outline** — collapsible per-project grouping when teams span multiple working directories
  121. The **Dependency graph** tab lays out every task as a card, with arrows from each prerequisite to its dependent, live agent ownership/status, a detail panel for prerequisites and dependents, and warnings for missing or cyclic dependency IDs. Add dependencies with the `depends_on` field on `team_tasks_add`.
  122. Configure the port in `.opencode/ensemble.json`:
  123. ```json
  124. {
  125. "dashboardPort": 4747,
  126. "dashboardHost": "127.0.0.1"
  127. }
  128. ```
  129. Set `dashboardPort` to `0` to disable. The dashboard starts automatically when OpenCode loads the plugin. `dashboardHost` defaults to loopback; changing it can expose dashboard data to other machines on your network.
  130. ## Install
  131. Two steps: add the plugin, then allowlist worktree paths.
  132. ### Runtime requirements
  133. The plugin uses SQLite via the host's runtime adapter:
  134. - **Bun**: any version with `bun:sqlite` (Bun ≥ 1.0).
  135. - **Node / Electron** (e.g. opencode Desktop): **Node ≥ 24** for stable `node:sqlite`. Older Node (20.x) lacks the module entirely; Node 22.5–23 has it behind `--experimental-sqlite`. If you load the plugin under an older Node and see `Cannot find module 'node:sqlite'` at startup, your runtime is too old.
  136. ### 1. Add the plugin
  137. The simplest install is the CLI (npm registry or Git package specifiers both work):
  138. ```sh
  139. opencode plugin add @hueyexe/opencode-ensemble@latest
  140. ```
  141. This installs globally and writes the config entry for you. To update later: `opencode plugin update @hueyexe/opencode-ensemble`.
  142. **Manual config** — add to your OpenCode config with `@latest`, or pin an exact version for reproducibility. Project-level or global.
  143. **Project-level** (`opencode.json` in your project root):
  144. ```jsonc
  145. {
  146. // OpenCode v2:
  147. "plugins": ["@hueyexe/opencode-ensemble@latest"]
  148. }
  149. ```
  150. **Global** (`~/.config/opencode/opencode.json`): same entry.
  151. ```jsonc
  152. {
  153. // OpenCode v1:
  154. "plugin": ["@hueyexe/opencode-ensemble@latest"]
  155. }
  156. ```
  157. OpenCode auto-installs npm plugins at startup. To update, change the version spec in your config (or keep `@latest`) and restart OpenCode.
  158. **If updates do not appear:** OpenCode has a [known bug](https://github.com/anomalyco/opencode/issues/6774) where unpinned plugins (e.g., `"@hueyexe/opencode-ensemble"`) get cached on first install and never auto-update, even after restarting. If you hit it, pin an exact version tag (for example, `@0.21.0`) and bump it when you upgrade, or clear the cache manually:
  159. ```bash
  160. rm -rf ~/.cache/opencode/packages/@hueyexe
  161. ```
  162. Then restart OpenCode.
  163. ### 2. Allow worktree directory access
  164. Teammates work in git worktrees outside your project directory. Without this permission, OpenCode will prompt you to approve every file operation in a teammate's worktree.
  165. Add to your OpenCode config (`~/.config/opencode/opencode.json`).
  166. OpenCode v2 (`permissions` array):
  167. ```jsonc
  168. {
  169. "permissions": [
  170. { "action": "external_directory", "resource": "~/.local/share/opencode/worktree/**", "effect": "allow" }
  171. ]
  172. }
  173. ```
  174. OpenCode v1 (`permission` map):
  175. ```json
  176. {
  177. "permission": {
  178. "external_directory": {
  179. "~/.local/share/opencode/worktree/**": "allow"
  180. }
  181. }
  182. }
  183. ```
  184. This is required. Without it, you'll see "Permission required — Access external directory" prompts constantly.
  185. ### Local development
  186. Configure the worktree as a local plugin (v2 loads the source entry; v1 uses the `server()` export from the same file):
  187. ```jsonc
  188. {
  189. "plugins": [{ "package": "/path/to/opencode-ensemble" }]
  190. }
  191. ```
  192. No build step needed for local testing — but run `bun run typecheck && bun test && bun run build` before committing. Restart OpenCode (or wait for hot-reload) to pick up changes.
  193. ## Tools
  194. 14 tools. The lead has all of them. Teammates get 6 (messaging + tasks).
  195. **Team lifecycle** (lead only, except archived-team purge may also be run from the main session)
  196. | Tool | What it does |
  197. |------|-------------|
  198. | `team_create` | Create a team. Caller becomes the lead. Accepts optional `project_name` to label the project. |
  199. | `team_spawn` | Start a new teammate with a task. Supports `plan_approval` mode. |
  200. | `team_shutdown` | Ask a teammate to stop. Preserves their branch before aborting. Supports `force` flag. |
  201. | `team_merge` | Merge a shutdown teammate's branch into working directory (unstaged). Blocks if you have local changes to overlapping files. |
  202. | `team_cleanup` | Remove the current team when done. Safety-net merges forgotten branches. With `purge`, previews archived-team deletion and returns exact approval labels plus a confirmation token. |
  203. | `team_status` | See all members, their status, and a task summary. |
  204. | `team_view` | Resolve a teammate's session; pass `navigate: true` to switch the TUI to it (opt-in — only when the user explicitly asks). |
  205. Archived-team purge is intentionally two-step. First call `team_cleanup` with `purge` to get a preview, exact approval and denial option labels, and `confirm_token`; no data is deleted. Stale archived worktree/workspace references and stale Ensemble-owned branches are counted in the preview and cleaned during confirmed purge. Arbitrary non-Ensemble branches still block purge for safety. The lead must then use the question tool with those exact options. Only after the user selects the exact approval option should it call `team_cleanup` again with the same `purge`, `confirm_purge: true`, and the preview token.
  206. **Communication** (everyone)
  207. | Tool | What it does |
  208. |------|-------------|
  209. | `team_message` | Send a direct message to a teammate or the lead. Also handles plan approval/rejection. |
  210. | `team_broadcast` | Message everyone on the team. |
  211. | `team_results` | Retrieve full message content (messages to lead are truncated on delivery). |
  212. **Task board** (everyone)
  213. | Tool | What it does |
  214. |------|-------------|
  215. | `team_tasks_list` | See all tasks with status and assignee. |
  216. | `team_tasks_add` | Add tasks to the shared board. |
  217. | `team_tasks_complete` | Mark a task done. Unblocks dependents. |
  218. | `team_claim` | Claim a pending task. Atomic, prevents double-claims. |
  219. ## What you see in the TUI
  220. The plugin works within OpenCode's existing UI on every client (terminal, desktop, web): tools, approvals, messages, and the [dashboard](#dashboard) at `http://localhost:4747` all live server-side.
  221. What you get:
  222. - **Team state in context** — the lead's system prompt carries member statuses and task counts, so it stays aware across turns including after compaction.
  223. - **Teammate messages** arriving in the lead's session as labeled blocks with the sender's name.
  224. - **Rich tool titles** in the sidebar (e.g. "Spawned alice (build)", "Message -> bob", "Task board (3 tasks)").
  225. - **Status checks** via `team_status` for a snapshot of the whole team.
  226. - **Terminal extras** (terminal only): a sidebar widget with live member status and task counts via the bundled `./tui` companion, loaded automatically with the plugin. `team_view` reports the teammate session by default; ask for it and `navigate: true` switches the TUI there (ctrl+p to return).
  227. ## Architecture
  228. - **SQLite** (WAL mode) for teams, members, tasks, and messages. Uses `bun:sqlite` in Bun and `node:sqlite` in Node/Electron through the internal database adapter.
  229. - **promptAsync** for message delivery: injects a message and starts the prompt loop in one call
  230. - **Git worktree isolation**: each teammate gets their own worktree by default, so multiple agents can edit files without conflicts. Opt out with `worktree: false` for read-only agents.
  231. - **System prompt injection**: the lead's system prompt includes team state (member statuses, task counts) on every LLM call. Teammates get a short role reminder.
  232. - **Compaction safety**: team context is preserved when OpenCode compacts long conversations
  233. - **Shell environment**: teammate shells get `ENSEMBLE_TEAM`, `ENSEMBLE_MEMBER`, `ENSEMBLE_ROLE`, and `ENSEMBLE_BRANCH` variables
  234. - **Sub-agent isolation**: teammates' sub-agents can't use team tools (parent chain tracking, max depth 10)
  235. - **Crash recovery**: stale busy members marked as errored on restart, orphaned sessions aborted, orphaned worktrees cleaned up, undelivered messages redelivered
  236. - **Spawn rollback**: if the initial prompt fails, the member, session, and worktree are all cleaned up
  237. - **Timeout watchdog**: teammates stuck busy beyond the TTL are automatically timed out and aborted
  238. - **Stall detection**: detects teammates making no progress (low output tokens or no communication) and escalates to the lead
  239. - **Peer-to-peer communication**: teammates can message each other directly, with idle-flush delivery and chatty agent detection
  240. - **Auto-merge on cleanup**: worktree branches are squash-merged into your working directory as unstaged changes for review
  241. - **Overlap detection**: `team_merge` blocks when you have local changes to files the agent also modified, preventing silent overwrites
  242. - **Spawn circuit breaker**: stops retrying after 3 consecutive spawn failures
  243. - **Graceful shutdown**: busy teammates receive a shutdown message and finish their current work. Use `force: true` to abort immediately.
  244. - **Rate limiting**: token bucket (configurable via config file or `OPENCODE_ENSEMBLE_RATE_LIMIT`, default 10 tokens/sec)
  245. ## Model Selection
  246. Control which AI models your agents use. By default, teammates inherit the lead conversation's current model, read at spawn time (including its variant on v2). You can override this per-agent, per-agent-type, or with automatic rotation.
  247. **All agents use the same model:**
  248. ```json
  249. {
  250. "defaultModel": "anthropic/claude-sonnet-4-6"
  251. }
  252. ```
  253. **Different models for different agent types:**
  254. ```json
  255. {
  256. "modelsByAgent": {
  257. "build": "anthropic/claude-opus-4-7",
  258. "explore": "openai/gpt-5.3-codex-spark"
  259. }
  260. }
  261. ```
  262. **Rotate through a pool for diverse perspectives:**
  263. ```json
  264. {
  265. "modelPool": ["anthropic/claude-opus-4-7", "anthropic/claude-sonnet-4-6", "openai/gpt-5.4"],
  266. "modelAssignment": "rotate"
  267. }
  268. ```
  269. **Ask the user before spawning:**
  270. ```json
  271. {
  272. "promptForModels": true,
  273. "modelPool": ["anthropic/claude-opus-4-7", "opencode/big-pickle", "openai/gpt-5.3-codex-spark"]
  274. }
  275. ```
  276. When `promptForModels` is true, the lead uses the question tool to ask which models to use before spawning any agents. The user can pick the same model for all agents, mix from the pool, or choose per agent.
  277. **Resolution order** — when an agent is spawned, the model is determined by:
  278. 1. Explicit `model` param on `team_spawn` (lead or user chose it)
  279. 2. `modelsByAgent` mapping for this agent type
  280. 3. `modelAssignment` strategy (`rotate` or `random` from `modelPool`)
  281. 4. `defaultModel`
  282. 5. The lead conversation's current model at spawn time (including its variant on v2)
  283. 6. OpenCode's default model
  284. The lead can always override by passing `model` directly on `team_spawn`, regardless of config.
  285. Model IDs use the `provider/model` format from [models.dev](https://models.dev) (e.g. `anthropic/claude-opus-4-7`, `openai/gpt-5.4`). For OpenCode Zen models, use the `opencode/` prefix (e.g. `opencode/big-pickle`).
  286. ## Configuration
  287. Configure via JSON files, environment variables, or both. Project config overrides global config. Env vars override everything.
  288. ### Config file
  289. **Global** (`~/.config/opencode/ensemble.json`):
  290. ```json
  291. {
  292. "mergeOnCleanup": true,
  293. "stallThresholdMs": 300000,
  294. "stallMinSteps": 5,
  295. "stallTokenThreshold": 200,
  296. "timeoutMs": 1800000,
  297. "rateLimitCapacity": 10,
  298. "dashboardPort": 4747,
  299. "dashboardHost": "127.0.0.1",
  300. "defaultModel": "anthropic/claude-sonnet-4-6",
  301. "modelPool": ["anthropic/claude-opus-4-7", "anthropic/claude-sonnet-4-6", "openai/gpt-5.4"],
  302. "modelsByAgent": {},
  303. "modelAssignment": "default",
  304. "promptForModels": false,
  305. "systemPromptTeamState": "full",
  306. "taskDepthLimit": 0,
  307. "taskDepthLimitOverflowAction": "lead_resolve"
  308. }
  309. ```
  310. **Project** (`.opencode/ensemble.json` in your project root) — same shape, overrides global per-key.
  311. All fields are optional. Missing fields use defaults.
  312. | Key | Default | Description |
  313. |-----|---------|-------------|
  314. | `mergeOnCleanup` | `true` | Auto-merge worktree branches on cleanup (squash + unstage) |
  315. | `stallThresholdMs` | `300000` (5 min) | Time without communication before stall escalation. `0` disables. |
  316. | `stallMinSteps` | `5` | Min model steps before token-based stall check kicks in |
  317. | `stallTokenThreshold` | `200` | Output tokens per step below which the agent is considered stalled |
  318. | `timeoutMs` | `1800000` (30 min) | Hard timeout for busy teammates. `0` disables. |
  319. | `rateLimitCapacity` | `10` | Token bucket capacity for team tool calls. `0` disables. |
  320. | `dashboardPort` | `4747` | Dashboard server port. `0` disables. |
  321. | `dashboardHost` | `127.0.0.1` | Dashboard network interface to bind. Keep the loopback default unless you intend to expose the dashboard on your network. |
  322. | `defaultModel` | `""` | Default model for all agents (e.g. `"anthropic/claude-sonnet-4-6"`). Empty = inherit the lead conversation's current model, then OpenCode's default. |
  323. | `modelPool` | `[]` | List of models for rotation/random assignment. |
  324. | `modelsByAgent` | `{}` | Map agent type to model (e.g. `{"build": "anthropic/claude-opus-4-7"}`). |
  325. | `modelAssignment` | `"default"` | How to assign models: `"default"`, `"rotate"`, or `"random"`. |
  326. | `promptForModels` | `false` | Lead asks user about model preferences before spawning. |
  327. | `systemPromptTeamState` | `"full"` | Live team state in the system prompt: `"full"` (statuses, tasks, message payloads), `"state-only"` (no message payloads; use `team_results`), or `"off"` (stable role/workflow guidance only). Lower settings avoid provider prefix-cache invalidation on every state change. |
  328. | `taskDepthLimit` | `0` (unlimited) | Maximum active task dependency depth, counting unresolved roots as depth 1. Completed/cancelled prerequisites are treated as resolved and do not accumulate into a lifetime chain. `team_tasks_add` rejects a batch that would exceed it, before writing anything. The issue #42 `depth_limit` alias is accepted. |
  329. | `taskDepthLimitOverflowAction` | `"lead_resolve"` | `"lead_resolve"` tells the lead to split the work; `"user_resolve"` tells the lead to ask the user first. Both reject the over-limit batch. The issue #42 `depth_limit_overflow_action` alias is accepted. |
  330. ### Environment variables
  331. Env vars override config file values. Useful for CI or one-off overrides.
  332. ```bash
  333. # Adjust teammate timeout (default: 1800000ms = 30 minutes)
  334. OPENCODE_ENSEMBLE_TIMEOUT=3600000
  335. # Disable timeout watchdog
  336. OPENCODE_ENSEMBLE_TIMEOUT=0
  337. # Adjust rate limit (default: 10 tokens, refills 2/sec)
  338. OPENCODE_ENSEMBLE_RATE_LIMIT=20
  339. # Disable rate limiting
  340. OPENCODE_ENSEMBLE_RATE_LIMIT=0
  341. # Adjust stall detection threshold (default: 300000ms = 5 minutes)
  342. STALL_THRESHOLD_MS=300000
  343. # Disable stall detection
  344. STALL_THRESHOLD_MS=0
  345. ```
  346. ## Best practices
  347. - Start with 2-3 teammates. More agents means more coordination overhead.
  348. - Give each teammate specific, self-contained tasks. Vague prompts produce vague results.
  349. - Spawn an explore agent first to understand the codebase, then spawn build agents with that context.
  350. - Use `worktree: false` for read-only agents (research, review, code analysis).
  351. - Use `plan_approval: true` for risky changes. The teammate sends a plan first, you review and approve before they write any code.
  352. - Don't micromanage. Teammates message you when done or when they're blocked.
  353. - Don't poll `team_status` in a loop. Wait for messages.
  354. ## Known limitations
  355. - **Lead agent/model preservation is best-effort (v1).** On v1, Ensemble reads the lead's current agent and model and passes them on teammate wake prompts, so a Plan lead normally stays in Plan. If OpenCode cannot report the selection, it may fall back to Build/default; pass an explicit `model` on `team_spawn` when this matters. V2 wakes are synthetic and do not switch the lead's agent/model.
  356. - **Model variants are v2-only.** A `provider/model#variant` reference is forwarded to v2's `session.switchModel`; v1 hosts do not have a variant field and ignore the suffix.
  357. - **Session switching is opt-in (v2).** `team_view` reports the teammate's session ID by default; it switches the user's client only when asked for with `navigate: true` — agents never hijack the client unprompted. The live sidebar (terminal only) shows member status on every client's dashboard at `http://localhost:4747`.
  358. - **Per-session shell env is unavailable (v2).** The v2 shell hook carries no session ID, so `ENSEMBLE_*` variables are not injected into teammate shells. Team identity travels in prompts and tool calls instead.
  359. ## How this differs from Claude Code agent teams
  360. Same coordination model (shared tasks, peer messaging, lead coordination) with some additions:
  361. - **Git worktree isolation by default**: each teammate gets their own branch, no merge conflicts between parallel agents
  362. - **System prompt injection**: the lead's system prompt is updated with team state so it stays aware across turns
  363. - **Compaction safety**: team context is preserved when sessions get long
  364. - **Team-aware shell environment**: `ENSEMBLE_TEAM`, `ENSEMBLE_MEMBER`, `ENSEMBLE_ROLE`, `ENSEMBLE_BRANCH`
  365. - **Graceful shutdown**: teammates finish current work before stopping, with a force flag for emergencies
  366. - **Plan approval mode**: review teammate plans before they write code
  367. - **Works today as a plugin**: install and go, no upstream changes needed
  368. ## Development
  369. ```bash
  370. bun install
  371. bun run typecheck
  372. bun test # 835 tests
  373. bun run build
  374. ```
  375. See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.
  376. ## License
  377. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.