Repository navigation
[FEATURE]: Ephemeral Sub-Agent Teams (parallel multi-agent orchestration) #19999
Description
[FEATURE]: Ephemeral Sub-Agent Teams (parallel multi-agent orchestration)
Feature hasn't been suggested before
This builds on the ideas in #12711 and #19215 but proposes a different approach: ephemeral, scoped teams that are created for a task and destroyed when done — no persistent team state, no new DB tables, no file-based coordination.
Describe the enhancement you want to request
Problem
The task tool spawns sub-agents sequentially — each runs in its own session, returns a result, and that's it. There's no way for sub-agents to:
- Run in parallel on independent subtasks
- Communicate with each other during execution
- Coordinate via a lead agent that assigns work, monitors progress, and merges results
Claude Code's "agent-teams" capability solves this. OpenCode should too.
What's different from #12711 and #19215
Both proposals add persistent team infrastructure (file-based or DB-backed). That's a large surface area with recovery logic, TUI integration, and ongoing state management.
This proposal takes a lighter approach:
| Aspect | #12711 / #19215 | This proposal |
|---|---|---|
| Lifecycle | Persistent teams that survive restarts | Ephemeral — created per-task, auto-cleaned |
| Storage | JSON files / new SQLite tables | Existing sessions + in-memory coordination |
| Recovery | Complex reconciliation | None needed — if parent dies, children abort |
| Scope | 9+ new tools | 1 new tool (team) + 1 coordination module |
| Communication | Cross-session message injection | Shared message bus scoped to team lifetime |
Proposed design
One new tool: team
z.object({
description: z.string(),
tasks: z.array(z.object({
agent: z.string(),
prompt: z.string(),
id: z.string().optional(), // for dependency references
depends: z.array(z.string()).optional(),
})),
concurrency: z.number().optional(), // default: all parallel
})The LLM calls team with a batch of tasks. The tool:
- Creates child sessions (like
taskdoes today) - Runs them in parallel via
Promise.all(respectingdependsfor ordering) - Pipes results back as a combined output
- Cleans up — child sessions remain browsable but the coordination state is gone
Optional: inter-agent messaging
A lightweight Bus-based channel scoped to the team's lifetime. Agents can post messages visible to siblings. This enables patterns like "agent A produces a schema, agent B consumes it" without round-tripping through the lead.
Why ephemeral
- No new persistence — uses existing Session infrastructure
- No recovery logic — parent abort signal cascades to children (already works in
task.ts) - No new TUI — child sessions already show in the session hierarchy
- Minimal blast radius — opt-in via
experimental.team_tool, same pattern asbatch_tool
Use cases
- Parallel file analysis (explore agent per directory)
- Concurrent implementation + test writing
- Multi-model review (run same prompt through different providers)
- Research fan-out (multiple search queries simultaneously)
Activity
github-actions commentedon Mar 30, 2026
This issue might be a duplicate of existing issues. Please check:
The issue notes differences from #12711 and #19215 specifically, but there is significant overlap with this broader set of issues around parallel/multi-agent orchestration. Please check these to see if your proposal can be consolidated or if it is truly distinct enough to warrant a separate issue.
AndresCdo commentedon Mar 31, 2026
Following up with a non-duplicate Phase 2 proposal that builds directly on #20152 (experimental
teamtool) while intentionally avoiding the persistent/team-platform scope in #12711 and #19215.Current baseline (already in #20152)
teamtool)Proposed Phase 2: ephemeral mailbox (runtime-only)
Goal: add in-run inter-agent communication for team children without introducing persistent team entities, new DB tables, or TUI team infrastructure.
Scope (what this adds)
teamgains optional channel id in metadata and creates an in-memory mailbox hub for that invocation.team:team_send({ to, message })team_recv({ from?, timeout_ms? })task_1,task_2, ... or caller-provided ids) and used for addressing.Non-goals (what this does NOT add)
Why this should not duplicate #12711 / #19215
Behavioral contract
teamexecution lifetime.team_recvcan block up to timeout and returns empty if none available.task/tool permissions;team_send/recvare only exposed in team-child context.Safety + verification matrix for implementation
team_recvIf maintainers agree, I’ll open a focused implementation PR as Phase 2 only (small diff, tests-first), and keep persistent/team-platform concerns out of scope.
feat(opencode): add ephemeral mailbox for inter-agent communication (…
m13v commentedon Apr 9, 2026
the ephemeral approach is exactly right. we tried persistent team state early on and the recovery logic alone was more code than the actual orchestration.
one thing worth adding to the team tool spec: a timeout per task. different tasks have wildly different completion times, and without per-task timeouts, a single stuck agent blocks the entire Promise.all. we use a watchdog that checks for tool activity (not just process liveness) since an agent can be alive but spinning in circles.
for the inter-agent messaging bus, keep it strictly unidirectional (producer posts, consumers poll). we tried bidirectional agent-to-agent messaging and it immediately degenerated into ACK loops where agents just kept acknowledging each other instead of doing work. the parent collects results, the children never talk to siblings directly.
the depends array for ordering is clean. one edge case: circular dependencies in the DAG. worth adding a cycle check before dispatch rather than discovering it at runtime when two tasks deadlock waiting on each other.
m13v commentedon Apr 9, 2026
our agent orchestration workflow that handles the ephemeral team pattern with per-task timeouts and context injection between handoffs: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md
mguttmann commentedon Jun 13, 2026
We built something close to this: a deterministic multi-agent workflow layer (fan-out / pipeline / synthesize across ephemeral sub-agent sessions, with per-agent worktree isolation and an abort cascade) on top of nested sub-agent spawning. Reference implementation in PR #32167, design-review proposal in #32166 — curious whether it overlaps with the ephemeral-teams approach you had in mind.
prassanna-ravishankar commentedon Jun 21, 2026
@m13v's point about persistent team state being more recovery code than orchestration is the right lesson, and it generalises. the durable bit you actually want isnt a team table, its liveness reconciliation, so a crashed member gets evicted instead of leaving the team wedged.
i went ephemeral-by-default in repowire for the same reason. peers register on start, and a lazy-repair pass evicts ghosts when a request next needs the registry, so theres no team state to recover and nothing runs on a timer. spawn a peer, it does the task, it falls off the mesh when it dies.
not native opencode, but the teardown model youre describing (created per-task, destroyed when done, no DB tables) is exactly what fell out of building it, happy to share what worked if useful.
github-actions commentedon Aug 20, 2026
To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.