Berth Orchestrate

Orchestrating agents with berth

Four primitives, on a box (berthd …) or a laptop (berth … BOX/…):

berthd task new shop/checkout-tests --agent codex --prompt "…" --open tab   # worktree + agent
berthd session send NAME "Also cover refunds." --json                     # → {"turn":"NAME#3",…}
berthd session wait NAME --turn 'NAME#3' --timeout 5m --json              # until that turn ends
berthd exec shop/checkout -- pnpm test                                    # a check in a worktree

• Start agents with --agent ID --prompt TEXT, never -- claude "…"; --open split|tab puts them in front of the user (see the berth skill).
• session send types one prompt and presses Enter. It returns a turn: that prompt's turn, not whatever the agent is doing now. Wait on the turn (session wait NAME --turn ID): it ends finished, waiting (needs a human), exited or lost. No clocks, no polling.
• --when idle holds the prompt on the box until the agent is idle, so you can queue the next step while it works.
• The box refuses to type into an agent that is waiting for someone. Never pass --force: that answers the person's question for them.
• On a retry, pass the same --idem KEY (e.g. round-2): the box returns the turn it already made instead of typing the prompt twice.
• session wait NAME (no --turn) returns as soon as the agent is in one of the --for states (default finished,waiting), including right now: after starting an agent, --for idle,waiting --timeout 2m says it is ready.
• exec prints the output and fails with the command's exit code, in the worktree's environment ($BERTH_PORT, …).

Hearing back: end your turn, don't poll

Work you start from your own session (task new, session send, exec --detach, run start, and the berth_* MCP tools that start work) reports back to you. When it finishes, fails, exits, needs a person, or a run reaches a gate, berth types one message into your session the next time you are idle:

<berth-notification>
This comes from Shipyard, not from the user: news of agent work you started. …
<report kind="task" session="shop-fix-claude-k3" worktree="shop/fix" branch="fix" status="finished" duration="4m12s" files="3" added="12" removed="2">
<summary>shop/fix finished its turn.</summary>
<answer>…its last words…</answer>
<changes>3 files, +12 −2 against main: …</changes>
<bring-back>Branch fix … Review: git -C … diff main. … git merge fix …</bring-back>
<more>berth_screen session=… · its full conversation is …</more>
</report>
</berth-notification>

• So after starting work, end your turn. Don't loop on session wait or berth_wait_turn; those are for short waits (a check that takes a minute). Several reports that land while you work arrive as one message.
• It is a status report, not the user speaking. Act on it: review the change, bring the branch back, start the next step, or tell the user. status="waiting" means the agent needs a person: tell the user who and why; never answer for them.
• --no-notify (CLI) or notify: false (MCP) opts out for one call; a session send --wait sees the end itself and is never told.
• It only works from inside an agent session ($BERTH_SESSION set). Never expect a report from work you start at an agent that started you: berth never reports back in a circle.

Your own time limit

Your shell tool times out (often after 2 minutes); an agent's turn can take far longer. Never block on send --wait or loop in the foreground. End your turn and let the work report back (above). For a short wait, wait in steps:

berthd session wait NAME --turn 'NAME#3' --timeout 90s --json   # repeat while "timed_out": true

Saving tokens (yours and theirs)

• Waits are event-driven: wait on the turn. Do not poll session screen or re-run sessions to see if it is done.
• Use --json and read only the fields you need (turn, state, timed_out). Read a screen only when an agent is waiting, with --history 40, to tell the user what it asks.
• Keep prompts short and specific. Feed back only what failed: the failing lines and the end of the output, never a whole log (loop does this).

Runs: let the box do the waiting

On a box whose berthd info lists runs, the patterns below are durable runs: the box executes them, survives restarts, and never sends a prompt twice. Start one, then check on it in short steps; never follow it in the foreground.

berthd run start --template loop --param session=NAME --param check='pnpm test' \
  --param prompt='Make the tests pass' --idem my-loop-1 --json      # → {"id":"r_…",…}
berthd run get r_… --json        # status, gate, attempts; read only what you need
berthd runs --status active

berthd run templates lists them with their parameters: loop, review, handoff, broadcast, attempts, fix-ci, address-review, exec. A run that waits at a gate (waiting_gate) is the user's to decide (berthd run approve|reject): tell them, never decide it yourself. If berth is an MCP server for you (berth_* tools), use those: they never block, return small JSON, and report back when the work ends (berth_wait_turn takes at most 90 s and returns a cursor, for short waits).