shipyarddocs
shipyarddocs

Guides

Orchestration

Agents driving agents. Prompt, wait, check, loop, hand off and broadcast, from the app, the CLI, the API or another agent.

Agents in Shipyard can drive each other, and so can you, a hook, a flow or a plugin. Four pieces on every box do it, the same from the app, the CLI and the API:

PieceCLIBox API
Start work: a worktree with an agent in itberth task new BOX/LOC/NAME --agent claude --prompt …POST /v1/tasks
Prompt a running agentberth session send BOX/SESSION TEXTPOST /v1/sessions/{name}/send
Wait for its turn to endberth session wait BOX/SESSION --turn IDGET /v1/turns/{id}/wait
Run a check where it worksberth exec BOX/LOC[/WT] -- COMMANDPOST /v1/exec

On a box, berthd takes the same commands without the BOX/ prefix, which is what agents there use.

The patterns below (loop, review, hand-off, broadcast, try several ways) are durable runs on boxes that have them: the box executes them and keeps a journal, so they keep going while the laptop sleeps and resume after berthd restarts.

Send

berth session send devl/shop-checkout-claude "Rebase on main and fix any conflicts"
# Sent to shop-checkout-claude (turn shop-checkout-claude#4)

The text is pasted as one block (so a multi-line prompt is one prompt), then Enter is pressed (--no-enter leaves it typed). Prompts never appear in events or logs; only session.sent with the session's name. before:session.send hooks can refuse a prompt.

A send returns the turn it started (see turns), the journal number of the send (seq) and the box's time (at); --json prints them:

{ "sent": true, "turn": "shop-checkout-claude#4", "seq": 812, "at": "2026-10-04T09:12:03.411Z" }
OptionAPI fieldEffect
--when now (default)when: "now"Type it at once. Refused (HTTP 409) while the agent is waiting for you
--when idlewhen: "idle"Hold it in the box's inbox for the session (up to 16 prompts) and type it once the agent is idle or finished; the turn is queued until then. Never typed while the agent waits for you
--forceforce: trueType it even into an agent waiting for you. For people answering it, never for agents and scripts
--idem KEYidem_keyA retry with the same key returns the turn it already made (duplicate: true) and types nothing

A request without when (an older client) types at once, as before. With --wait, it then waits for that turn to end (up to --timeout, 30 minutes by default). With --queue, a prompt for a box that cannot be reached waits on the laptop instead of failing; see the offline queue.

Wait

berth session wait devl/shop-checkout-claude --turn 'shop-checkout-claude#4'   # that turn
berth session wait devl/shop-checkout-claude                                    # finished or waiting, now or later
berth session wait devl/shop-checkout-claude --for finished --timeout 1h
berth session turns devl/shop-checkout-claude                                   # its last turns

A turn wait returns when the turn ends (finished, exited, lost) or waits for you (waiting), so a prompt sent while the agent was mid-turn is not ended by the turn it was already in. It needs no clock: the box orders everything by its journal. GET /v1/turns/{id}/wait?until=end|waiting&timeout=90s is the API (encode # as %23).

berth session wait without --turn returns when the agent is finished or waiting (or the states you ask for), including right now, or when its program exits. Over the API, GET /v1/sessions/{name}/wait?after= still works for older clients: the box places after in its journal's order, so a caller whose clock runs ahead or behind the box's still sees the turn end. A wait that times out reports the last state it saw.

Hearing back

An agent that starts work through Shipyard doesn't have to wait for it. When it makes a task, sends a prompt, starts a run or a detached exec from its own session, the box remembers who asked. When that work finishes, fails or exits, waits for a person, or a run reaches a gate, the box types one short message into the asking agent's session the next time it is idle, the way Claude Code tells an agent a background task is done:

<berth-notification>
This comes from Shipyard, not from the user: news of agent work you started. …
<report kind="task" session="shop-checkout-fix-claude-k3" worktree="shop/checkout-fix" branch="checkout-fix" status="finished" duration="4m12s" files="3" added="12" removed="2">
<summary>shop/checkout-fix finished its turn.</summary>
<answer>Fixed the rounding in totals.ts and added a test…</answer>
<changes>3 files, +12 −2 against main: totals.ts +10 −1, …</changes>
<bring-back>Branch checkout-fix, in /w/checkout-fix. Review: git -C /w/checkout-fix diff main. … git merge checkout-fix …</bring-back>
<more>berth_screen session=shop-checkout-fix-claude-k3 shows its screen; its full conversation is ~/.claude/projects/…</more>
</report>
</berth-notification>

So the agent ends its turn instead of polling session wait or berth_wait_turn, and picks up when the report arrives. Each report has the session, worktree, branch, status and how long it took; the agent's last words (trimmed); the files changed with their line counts; for a worktree, how to review and merge its branch (or hand it on with the handoff template); and where to read more. In the app, the asking agent's chat shows each report as a card ("checkout-fix · Finished · +12 −2 · 4m12s") with an Open button, not the tagged text, headed like the cards for other agents' messages (conversation view).

  • Who asked. The MCP tools and the berthd commands that start work (task new, session send, exec --detach, run start) name the agent's own session ($BERTH_SESSION) to the box. Codex starts its MCP servers without that variable, so berthd mcp then asks the box which session's pane its agent runs in. Only callers on the box's own socket can name one, and only an agent session is ever told. Opt out for one call with notify: false or --no-notify; session send --wait and run start --follow see the end themselves and are never told.
  • When. At the asking agent's next idle, through the same queue as --when idle, so it never interrupts a turn and never types into an agent that waits for you. Reports that land while it works go as one message.
  • Once. Each turn's end, each wait for a person, and each gate is reported once, and a berth_wait_turn that sees a turn end drops its report. Watches and undelivered reports are kept in the box's state (notify.json), so a restart loses none.
  • Never in a circle. A report is never itself a watch, work can't report back to an agent that reports to it, and an agent that ended its turn to wait for work of its own reports once that is back and it is done.
  • Limits. At most one message every 15 seconds and 30 an hour per agent, 20 reports held at once. An agent whose session is gone (stopped, or its worktree archived) is never typed into: what it would have been told is dropped.

GET /v1/notify lists who hears back about what.

Exec

berth exec devl/shop/checkout -- pnpm test --changed

Runs a command to completion through a login shell in the location or worktree, with its environment, and returns its exit code and the last 64 KB of output (--timeout, 10 minutes by default). before:exec hooks can refuse it. With --detach (API detach: true) it answers at once with a run whose result holds the exit code and output (berth run get), so no caller blocks on a long check.

Patterns

Loop until a check passes

berth loop devl/shop-checkout-claude --check "pnpm test" --prompt "Make the tests pass" --max 5

It prompts, waits for that prompt's turn, runs the check in the session's worktree, and sends back what failed until the check passes or --max rounds (default 5) run out. What goes back is short, since the agent reads every byte of it: the lines that say what failed and the end of the output, without colours, at most about 3 KB, never the whole log. Each round's prompt carries an idempotency key, so a retried send never types it twice. It stops if the agent is waiting for a human (the box refuses to type into it); --turn-timeout bounds each turn. On a box with runs it is a run of the loop template on the box: Ctrl-C stops following it, not the loop (--cancel-on-exit cancels it, --detach only starts it), and it survives the laptop sleeping and berthd restarting. In the app, Loop until… in a session's menu does the same, and running loops show in a panel in the corner, from every device.

Hand off

A new worktree and agent picking up where another left off, with a handoff packet:

berth run start devl --template handoff --param session=shop-checkout-claude \
  --param name=checkout-tests --param agent=codex --param prompt='Write the missing tests.'

The source agent is asked to write .berth/handoff/<run>.md (Done, Left, Decisions, Gotchas; at most 30 lines). Shipyard adds the diffstat, the commits, the last check's failing tail and the turn log, caps it at about 2 KB, and carries uncommitted work over. The new agent's first prompt only points at the file. With --param native=true and the same vendor on the same box, the new agent continues the source's own conversation instead (claude --resume <id> --fork-session, codex resume <id>). The app's Hand off to… with In a new worktree does this; without a runs box it starts the task with a prompt that names where the work was.

Review

A second agent reviewing a worktree, with its own session identity so its turns never end the author's waits:

berth run start devl --template review --param session=shop-checkout-claude --param send_back=true

By default the reviewer is a headless agent that can only read; its verdict (at most 15 lines) is the run's output, and send_back sends it to the author. The app's Review with… starts an interactive reviewer beside the author.

Broadcast

The app can send one prompt to several agents at once, from the composer's Running agents tab: pick the running agents it goes to, write the prompt or start from a saved one, and read or change each agent's copy under Options. Send a prompt to several agents… in ⌘K, Send to N agents… on the Agent Dashboard, Prompt agents… on a selection in Worktrees and Send to several… in the prompt library open it with those agents picked; a session's Send prompt… and Loop until… open it on that one (a loop prompts, waits, runs the check and sends failures back). The prompt's {{variables}} are filled in for each agent (its branch, worktree, project, box), sends go one after another, and you can wait for every turn to end and read what each said. An agent that is waiting for you is skipped, never typed into. Agents on offline boxes can be queued for when they're back. On boxes with runs, each box's share is a broadcast run there: the box holds each prompt until its agent is idle and waits for every turn, even if the app quits.

Try several ways

Try N ways… (⌘K, or a session's Orchestrate menu), or picking several agents in the composer, gives one task to several agents, each in its own worktree, verifies them with a check, has a headless judge rank them, and lets you pick in Review's Compare. See attempts.

Chain with hooks and flows

A hook on the box can start the next step when an agent finishes. Here a Codex session named reviewer looks at whatever Claude Code just did; the case keeps the reviewer's own finished turns from prompting it again:

~/.berth/hooks.json
{
  "hooks": [
    { "on": "agent.finished", "run": "case \"$BERTH_AGENT\" in claude) berthd session send reviewer \"Review what changed in $BERTH_PATH\";; esac" }
  ]
}

For anything with more than one step (run the tests, send failures back, notify you), use a flow.

From an agent

The skills Shipyard installs (berthd integrations install claude) teach agents these commands, so an agent can split work across worktrees, ask another agent for a review, or loop on a check by itself. The berth-orchestrate skill also tells them never to answer another agent's question on the user's behalf, and to end their turn once they start work rather than poll: it reports back. See agent integrations. The same install adds berthd mcp, an MCP server of typed, non-blocking tools for the same things; see runs.

From a plugin

Plugins get the same operations as berth.orchestrate: send (which resolves with the turn), waitTurn, wait, exec, handoff, review and loop (runs on boxes that have them), and runs to start, follow, decide and cancel any run; see the plugin SDK.

Agent state

All of this relies on agents reporting their turns: fully through hooks for Claude Code, Codex (with its hooks trusted), Gemini CLI and OpenCode, Cursor except for "needs you", and by reading the terminal for anything else. See sessions and agents.

Agents driving agents, cheaply

An orchestrating agent pays in tokens for everything it reads, and so does every agent it prompts. Shipyard keeps both small: waits are event-driven (wait on the turn; never poll session screen or rerun sessions), --json output is compact, prompts Shipyard writes (loop feedback, GitHub comments in flows, handoff packets, the judge's summaries) are short and capped, and idempotency keys mean a resumed caller never sends the same prompt twice. Each template's budget is in its description (berth run templates). An agent's shell tool usually times out within minutes, so the skill tells agents to end their turn and let the work report back, and to wait in short steps (session wait --turn ID --timeout 90s) only for short waits.

On this page