[FEATURE]: Coordinator shell + fork mode

[chebykinn]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

As we explore more and more subagents usage, I think what I'm proposing is a pretty natural evolution. Let me start with what we have now.

Now

Currently each opencode session is very much sequential, only designed to work on one prompt at a time. People achieve parallelization by creating multiple instances in different terminals. This works for now, but it has many issues:

1. It's wasteful - there are a lot of waits in-between queries
2. It's hard to track sessions - when it blocked, when it is waiting for input, none of the states are properly documented and based on my experiments it's pretty hard to derive session state from the agent storage.
3. It's hard to do inter agent communication - well, this is basically a green field area, everyone does whatever.

Proposal - fork by default

Coordinator agent

The main agent should only act as a coordinator. The goal is to avoid queueing messages as much as possible.
When the user submits the prompt, first it should understand the ask, get more context (if needed), and fork the session and run it in a subagent.

I believe it should decide by itself whether to send follow up to any given subagent - this could be a tool, and the user can specify more info to find the subagent. The coordinator agent should have tools to list the running agents, read their state and read their output or changed files.

Subagents

Any session can be a subagent - It could be either a planning session, code editing, or just an ask. Each session should have a human-readable slug - Claude Code already started doing that, and it's would be easy for the user and the agent to lookup these subagents.
There is an elephant in the room regarding context - not all agents need the entire previous session after fork. Frankly this is not a new problem - Unix has the same progress flow: first it runs fork(), and creates a copy of the parent process, and then it runs exec() and replaces the whole process with a new one. This approach can be reused with subagents - it can check if the parent context is relevant, and discard it if the task is completely new.

Eventually this can be something similar to the system process model, but entirely built on agentic level of abstraction.

Communication

Agent to agent communication is out of scope of this proposal. The only communication flow that should happen is when subagent finishes - the parent agent should see summary of work, whether the agent completed or not and it can decide to retry or launch with different params.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]:Support for multi-agent orchestration in isolated workspaces #17994: Support for multi-agent orchestration in isolated workspaces
• [FEATURE]: Ephemeral Sub-Agent Teams (parallel multi-agent orchestration) #19999: Ephemeral Sub-Agent Teams (parallel multi-agent orchestration)
• [FEATURE]: DB-backed agent team coordination (parallel sub-agents, messaging, memory) #19215: DB-backed agent team coordination (parallel sub-agents, messaging, memory)
• [FEATURE]:Real-time Agent-to-Agent (A2A) & Non-blocking SubAgent Communication #17374: Real-time Agent-to-Agent (A2A) & Non-blocking SubAgent Communication
• [FEATURE]: Multi-Agent Coding #9649: Multi-Agent Coding

If this covers different ground, please clarify how it differs from the above.

[chebykinn]

Regarding previous feature requests:

• I disagree with the idea of "teams": model reasoning is not there yet to provide a sophisticated "lead" agent that can direct subagents. Each subagent should verify it's own work, and if something must be checked, it's should be implemented as a hook, outside of LLMs.
• Using tmux is a hack, allocate pty if you need to, but I think the subagent should just run as a normal child process.
• I would say that agent to agent communication is out of scope for this proposal.

[rentiansheng]

If the tasks within a plan can be structured as independent domains, would it then be possible to achieve parallel execution without the need for forking? This is analogous to writing technical documentation or a full-length novel: once the outline or main storyline has been defined, the process simply involves drafting specific individual chapters.

[chebykinn]

If the tasks within a plan can be structured as independent domains, would it then be possible to achieve parallel execution without the need for forking? This is analogous to writing technical documentation or a full-length novel: once the outline or main storyline has been defined, the process simply involves drafting specific individual chapters.

@rentiansheng Great examples! Yes, that's a good way to think about it - coordinator should be able to decide that the subagents don't need the full conversation and just task them with filling an individual chapter or implementing a single component.

[rentiansheng]

If the tasks within a plan can be structured as independent domains, would it then be possible to achieve parallel execution without the need for forking? This is analogous to writing technical documentation or a full-length novel: once the outline or main storyline has been defined, the process simply involves drafting specific individual chapters.

@rentiansheng Great examples! Yes, that's a good way to think about it - coordinator should be able to decide that the subagents don't need the full conversation and just task them with filling an individual chapter or implementing a single component.
#20368 (comment) The two issue can be relation.

• Humans perceive a hierarchical structure,
• LLM reads a tree-like structure. Each leaf node can be executed independently by an agent.

Each leaf node is a domain. The main agent begins multi-agent operations.

[m13v]

the fork-by-default model with a coordinator is elegant. the Unix process analogy (fork then exec, discard parent context if irrelevant) maps well to how agent sessions actually work.

from running this pattern in production: the coordinator should be deterministic code, not an LLM. we tried LLM-based task decomposition and the coordinator would sometimes create phantom dependencies or reassign tasks mid-flight. the LLM does the actual coding work, but the scheduling and dispatch should be pure code with a simple state machine (pending, claimed, running, done, failed).

for context management on fork, the simple heuristic that works: pass the coordinator's plan summary (not the full conversation) plus the specific task prompt. the subagent almost never needs the parent's full conversation, and injecting it wastes tokens and confuses the model about what it is supposed to focus on.

one thing to add: a session slug that is both human-readable and stable. "fix-auth-middleware-34a" is searchable and debuggable. random UUIDs are not. Claude Code started doing this and it makes a real difference when you are managing 5+ concurrent agents.

[m13v]

the orchestration spec we use for the coordinator pattern with deterministic dispatch and human-readable session management: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md

and the tool execution framework that handles the multi-step invocation loop in each subagent: https://github.com/m13v/fazm/blob/main/Desktop/Sources/Providers/ChatToolExecutor.swift

[chebykinn]

I'm currently prototyping this, you can follow the progress in this branch: https://github.com/chebykinn/opencode/tree/coordinator

Start opencode with bun run dev, then using /agents select "Coordinator", and then ask for some long running task. Here's what I'm testing it on, lol:
"Can you run a subagent that will print counting sheeps for 30 seconds? Each second it should call bash for sleep 1, but in separate calls, and then count sheeps by itself. After 15 sheeps the subagent should ask a question: Clap? with options Once and Twice. After running the subagent attach to it".

The agent attaches to the subagent stream and you will see the the messages as it works. I've asked the coordinator to attach to the agent, so cancelling that tool would cancel the subagent as well. If you ask to follow the subagent, then it will work like tail -f, and cancelling the tool will just stop the stream. After 15 seconds you will see that subagent tool is forwarded to coordinator.

[m13v]

love the sheep counting test, that's actually a solid stress test for the message passing and timeout behavior. the coordinator branch looks like the right direction.

one thing from our experience: make sure the subagent question/approval flow has a timeout so a stuck approval doesn't block the coordinator indefinitely. also curious how you're handling the TUI rendering when multiple subagents are producing output simultaneously. that was one of the trickier UX problems we hit, ended up doing per-agent output panels with a shared status bar.