opencode-courier

Your OpenCode session hands work to other sessions, ends its turn, and is woken when they report. Multi-session orchestration for OpenCode V2: spawn child sessions, be woken by them. No polling.

https://github.com/user-attachments/assets/d7cf74f8-15b3-4cc1-866e-b75ba0ac3f8a

A narrated tour of the terminal UI: the tree panel, the asks inbox, failing children and memory.

Quickstart

npm install -g @opencode/[email protected]   # OpenCode V2, the version courier is tested on
opencode plugin add opencode-courier
opencode

Paste this prompt:

Start two helper sessions with courier_spawn and have each report back to you. One runs `sleep 20; echo $((17 * 23))`, the other `sleep 40; echo $((2 ** 10))`. Do not run the commands yourself. When both have reported, reply with one line: RESULTS <first> <second>

The parent starts both children and ends its turn. Each report wakes it, and it replies RESULTS 391 1024. Free models sometimes stall; if nothing moves for a few minutes, send the prompt again.

Why courier

OpenCode's own subagent tool hands back a child's final answer. Use it when one result is all you need. Use courier for more:

• Messages mid-run. A child reports progress or asks its parent at any time.
• Waking an idle session. A message, a schedule or a GitHub webhook starts a new turn.
• Parallel edits. isolate: true gives a child its own git worktree and branch to merge.
• Asks reach you. A child's permission requests and questions come to you through the top session. Only you approve a request, in OpenCode's own prompt.
• Trees. A child may split its part again, within limits you set.

How it works

A parent calls courier_spawn, gets the child's session id at once, and ends its turn. When done or stuck, the child calls courier_send with a status (done, partial, blocked or failed). The message lands in the parent's inbox and starts a new turn if the parent is idle.

Children started with the same group report together, in one message. A child that fails (a rate or quota limit with when it lifts), or ends its turn without reporting, is reported to its parent. A message that does not wake its session is sent once more, then shown as stalled. Children, held reports and scheduled messages survive a restart. The courier-orchestrate skill, listed in every session, tells a model when to split a task and how to check and merge the parts. Every detail: the reference.

Install

Requires OpenCode V2: the opencode command from @opencode/cli. Each release is tested against one OpenCode version; this one is tested on OpenCode 2.1.4 (check with opencode --version).

npm install -g @opencode/[email protected]
opencode plugin add opencode-courier

This adds "opencode-courier" to plugins in ~/.config/opencode/opencode.json. Install it by name, without a version: OpenCode offers updates only for an entry without an exact version (updating).

Supported OpenCode version

| opencode-courier | OpenCode V2 (opencode and @opencode/plugin) | |---|---| | 0.11.1 | 2.1.4 | | 0.11.0 | 2.1.3 | | 0.10.2, 0.10.3 | 2.1.2 |

Every release: the full table. The server part loads on any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.1.4 only.

Options

Set the server options on the plugin's entry in the global config, ~/.config/opencode/opencode.json:

{
  "plugins": [{ "package": "opencode-courier", "options": { "maxDepth": 2, "maxChildren": 3 } }]
}

| Option | Default | | |---|---|---| | maxDepth | 3 | How deep a tree goes. Your session is depth 0. A session at maxDepth cannot start sessions. | | maxChildren | 5 | Live children one session may have. | | maxTotal | 20 | Live spawned sessions in one tree. | | memory | true | Keep a record of each session tree for later orchestrators (memory). | | nativeChildren | false | Create non-isolated children as OpenCode subagents (native children). | | webhook | off | Start the webhook receiver (webhooks). |

The terminal part reads its options only from ~/.config/opencode/cli.json, in the same entry form. Its one option, "animations": false, keeps the tree panel still.

Tools

| Tool | Does | |---|---| | courier_spawn | Starts a child session with a task and returns at once. isolate, group, agent, title. | | courier_send | Messages a session, waking it if idle. With a status, it is a child's report. | | courier_status / courier_children / courier_tree | One look at a session, at the sessions it started, or at its whole tree. | | courier_stop | Stops a session below you and everything under it. | | courier_cleanup | Removes an isolated child's worktree and forgets the child. | | courier_answer | Proposes an answer to a child's permission request, or passes on your answer to its question. | | courier_later / courier_cancel | Schedules a message for a session, or drops one. | | courier_subscribe / courier_unsubscribe | Subscribes a session to webhook deliveries for a topic, or drops it. | | courier_recall / courier_note | Reads what earlier trees in this project did, or writes this tree's one-line lesson. |

Parameters and behaviour: the reference.

In the terminal

• Footer: courier 1 waiting on you · 2 running · group pair 1/2.
• /courier tree: a panel with the tree. enter opens a session, s stops it, q closes.
• /courier stop <session>: stops a session and everything under it.
• ctrl+x k or /asks: every ask waiting on you in the tree, answered in a dialog.
• /courier memory: the project's tree records. p pins one, x forgets one.

More: in the terminal.

Tips

• Keep opencode service start running, so sessions can be woken while you are away. Run one OpenCode server per data directory (why).
• Allow up front what the work needs, and the question tool if children should ask you. A child's approval prompt waits for you, and the top session's own prompts stall the whole tree (allow bun run * or npm run * and git).
• Choose a web search provider before children search, or the first one shows you a form.
• Use isolate: true when children edit files in parallel. The worktree starts from the last commit, so keep providers in the global config or commit opencode.json.
• For a long-running child, schedule a courier_later check-in, in case the server stops.

Contributing

Questions and bugs: issues. Pull requests are welcome; start with development.md.

License

MIT, see LICENSE.