Guides
Durable runs
Loops, reviews, hand-offs, broadcasts, attempts and flows that the box executes and journals, so they keep going while the laptop sleeps and pick up after a restart.
A run is an orchestration the box executes itself: loop an agent until a check passes, have a second agent review its work, hand the work to a fresh agent, send one prompt to many, or try one task several ways and pick the best. Flows run as runs too. The box keeps a journal of every run, so a run:
- keeps going while your laptop sleeps, and shows the same on every device;
- survives
berthdrestarting or upgrading: it resumes where it was; - never sends an agent the same prompt twice, even across a restart.
Runs need a box whose berthd lists the runs capability in
GET /v1/info. Against an older box, the app and berth loop fall back to
running the loop themselves.
Start one
berth run start devl --template loop --param session=shop-checkout-claude \
--param check='pnpm test' --param prompt='Make the tests pass' --follow
berth loop devl/shop-checkout-claude --check 'pnpm test' --prompt 'Make the tests pass' # the same
berth run templates devl # what each takes--param k=v takes text, or JSON for numbers, lists and objects
(--param 'attempts=["claude","codex"]'). --follow prints each step as it
finishes; Ctrl-C stops following, not the run (berth loop --cancel-on-exit
cancels it instead). --idem KEY makes a retried start return the run it
already made.
In the app, Loop until…, Hand off to… (to a new worktree), Review with…, Send a prompt to several agents… and Try N ways… start runs on boxes that have them. Running loops show in the corner panel, from any device; every run is in Automations → Runs.
Templates
| Template | Does | Sends agents |
|---|---|---|
loop | Prompt, wait for the turn, run check; while it fails, send the failing tail back, up to max rounds (5) | Your prompt once; each failed round about 90 characters plus the failing lines and tail, at most 3 KB |
review | A second agent reviews the worktree with its own session (headless by default), optionally sending its verdict to the author (send_back) | About 260 characters plus your criteria; the reply is capped at 15 lines and only it goes back |
handoff | The source agent writes .berth/handoff/<run>.md (Done, Left, Decisions, Gotchas); Shipyard adds the diffstat, commits, the last check and the turn log, then starts a new agent in a new worktree pointed at it. native forks or resumes the source's own conversation instead (same vendor, same box) | 170 characters to the source; the new agent's first prompt is about 90 characters pointing at a packet capped at 2 KB |
broadcast | One prompt (or one each) to several sessions on the box, each when it is idle; waits for every turn | Your prompt, once per session |
attempts | Try a task several ways: see attempts | See below |
fix-ci | A failed check on a PR: the failing tail of the CI log to the worktree's agent, a local check, up to max rounds, then git push | About 110 characters plus the failing log lines, at most 3 KB |
address-review | New review comments (merged while it works) to the worktree's agent, a local check, then git push | About 90 characters plus the comments, labelled as others' words, at most 4 KB |
exec | One command to completion, in the background (berth exec --detach) | Nothing |
Every prompt a template sends is short on purpose: each byte is the agent's to read, every round.
Follow, decide, cancel
berth runs devl # newest first; --status active|done
berth run get devl/r_muttexv8r1yy # its steps as a tree, its gate, attempts and tokens
berth run logs devl/r_muttexv8r1yy --follow
berth run approve devl/r_muttexv8r1yy --pick 3 --note "the smallest diff"
berth run reject devl/r_muttexv8r1yy
berth run cancel devl/r_muttexv8r1yyA run waiting for a person is waiting_gate. It shows as Needs you in
Automations → Runs, sends a notification (and an ntfy push from
the phone), and the phone can approve, reject or cancel it.
before:run.approve hooks decide who may decide a gate; before:run.start
and before:run.cancel gate starting and cancelling.
Attempts
One task, several agents, each in its own worktree; verified, judged, picked.
POST /v1/runs
{ "template": "attempts",
"params": {
"location": "shop", "name": "refunds", "base": "main",
"prompt": "Implement partial refunds (see issue 412)",
"attempts": [ {"agent": "claude", "model": "opus"}, {"agent": "claude", "model": "sonnet", "effort": "high"}, {"agent": "codex", "prompt_suffix": "Prefer the smallest diff."} ],
"verify": { "check": "pnpm test && pnpm lint", "max_rounds": 2 },
"judge": { "by": "agent", "agent": "claude", "criteria": "correctness, tests, the smallest diff" },
"pick": "human",
"then": { "pr": { "draft": true } },
"cleanup": "archive-losers",
"budget": { "max_wall": "2h", "max_agents": 4 } } }- Each attempt gets the worktree
<name>-a<n>and its agent, with the prompt (and its suffix), on its ownmodelandeffortwhen given (so "Opus against Sonnet" is a run). They work at once, up toconcurrency. - Each is verified with
verify.check; a failure sends its failing tail back, up tomax_rounds. - Shipyard collects each attempt's diffstat, commits, check result and tokens.
- The judge, a headless agent that can only read, gets
one line per attempt (its check, diffstat and last commit subjects) and
the worktree paths, about 2 KB for three attempts, never transcripts or
whole diffs (
judge.diff: trueadds diffs, capped at 4 KB each). It must answer{"winner": N, "ranking": [...], "reasons": {...}}; a reply that does not fit is asked once more, then the checks decide.judge.by: "check"skips the agent and takes the passing attempt with the smallest diff. - With
pick: "human"the run waits at a gate. Review's Compare shows the attempts side by side (check, diffstat, commits, the judge's ranking and reasons, files) with Pick this one; orberth run approve RUN --pick N. Withpick: "auto"the judge's winner is taken when its check passed. - The pick gets a draft PR (
then.pr), and the other worktrees go through the project's archive script (cleanup).
The pull request. The pr step pushes the pick's branch and opens the
pull request with gh, on github.com or a GitHub Enterprise host gh is
signed in to. On any other host (Gitea, Forgejo, GitLab, a folder) it pushes
the branch and stops there: the step is skipped, says why, and passes on
the link the forge printed on push for opening one by hand. The run goes on
and archives the other attempts. If gh fails, that is publishing failing,
not the agents' work: the run waits at a gate, "The pull request didn't
open", with gh's words, the pick kept and nothing archived. Retry
publishing (berth run approve) tries again; Finish without a pull
request (berth run reject) skips it, and the run goes on and succeeds.
In the app, Try N ways… in ⌘K or a session's Orchestrate menu starts one.
Across boxes. In Try N ways…, an attempt can go to another box that
has the project. The app starts one attempts run per box, as a group; each
is durable on its box, and each box's judge ranks its own attempts. Review's
Compare shows the whole group as one: picking an attempt approves its run's
gate with it, and the other runs pick none (--pick 0 from the CLI is
attempt 1; the API's pick: -1 is none), so they open no PR and archive
their worktrees. The cross-box comparison happens in the app, so it waits
for you there; each box's work and checks do not.
How a run resumes
Each run has a journal, $BERTH_HOME/box/runs/<id>.jsonl, of its steps'
starts and results, gate decisions and timers. When berthd starts, it
replays every unfinished run: a step with a recorded result returns it
without running again, so loops and fan-outs come back exactly where they
were, and the step that was in flight follows its kind's rule:
| Step | On resume |
|---|---|
run, check | Runs again. Keep checks safe to repeat |
wait | Waits again on the same turn, with no clock: a turn that ended while berthd was down (its hook spooled) is seen as ended |
prompt | At most once: the turn it made is found by its idempotency key and adopted. If none is found, the run waits at a gate, "Did the prompt arrive?": approve if it did, reject to send it again |
start_agent | The worktree and session have fixed names, so it adopts them |
headless | Adopts the answer if the agent finished, or keeps waiting for it; never asks again |
notify, webhook | Sent again with the same idem_key (an Idempotency-Key header on webhooks) |
gate, sleep | Their deadlines are absolute, kept in the journal |
pr | Pushes again and adopts the pull request if it opened. One that waits at "The pull request didn't open" waits there again, without trying gh by itself |
Admission, concurrency and budgets
- A trigger for a worktree where the flow's run is still going waits for
it (at most
queue, default 5) instead of being skipped. Withcoalesce, new GitHub items merge into the run already waiting, as{{event.items}}. A GitHub item counts as seen only once its run exists, and its idempotency key (github:<flow>:<pr>:<item>) makes a second delivery start nothing. ~/.berth/runs.jsonon the box caps the whole box:{"max_concurrent_runs": 10, "max_concurrent_agents": 6}. More runs waitqueued; a run about to start one more agent waits for a slot.- A run's
budget(max_rounds,max_agents,max_wall,max_usd,max_tokens) pauses it at an Over budget gate when passed: approve to go on without that cap, reject to stop it.
Headless agents
Judges and reviewers run as one non-interactive turn (claude -p --output-format stream-json, codex exec --json, gemini -p --output-format json) inside tmux, so you can still attach and watch.
Shipyard reads their final answer, tokens, cost and session ID from the JSON.
Read-only ones get Claude's --allowedTools Read,Grep,Glob,LS and Codex's
--sandbox read-only. berthd headless is the wrapper they run in.
Tokens and cost
A run counts what its agents spent where the agent writes it down: each
turn a wait ended, from Claude Code's or Codex's own session log (token
counts only, never content), and headless agents' reported usage and cost.
berth run get and the Runs timeline show the totals; attempts show each
attempt's.
API
POST /v1/runs {template, params} | {flow: [steps]} | {flow_id, scope, data}
Idempotency-Key header (or "idem_key"), title, session, path, group, budget
GET /v1/runs?status=&template=&flow=&group=&limit=
GET /v1/runs/templates
GET /v1/runs/{id} with steps, gate and candidates
GET /v1/runs/{id}/events?since=N its journal from record N, then live (NDJSON; follow=0 stops)
POST /v1/runs/{id}/cancel
POST /v1/runs/{id}/gates/{step}/decide {approve, note, pick} step "current" is the open one
GET /v1/review?run=ID an attempts run's candidates, each with its worktree's changes
POST /v1/exec {location, command, detach: true} → {run}Runs publish run.created, run.queued, run.started, run.resumed,
run.step, run.gate, run.gate_decided and run.finished
(events). Finished runs past 100 per flow or template,
or 30 days old, are compacted away, journal and all.
From an agent: MCP
berthd mcp is a stdio MCP server of Shipyard's tools for agents on the box,
talking to the box's own socket. berthd integrations install adds it to
Claude Code, Codex and Gemini CLI. Every tool returns at once with minimal
JSON:
| Tool | Returns |
|---|---|
berth_sessions | name, agent, state, turn, where |
berth_screen | the last lines (at most 60) |
berth_task_new | the new session and worktree |
berth_send | the turn (held until the agent is idle, by default) |
berth_wait_turn | the state after at most 90 s; if not ended, a cursor to call again with (for short waits) |
berth_exec | a detached run; with wait (at most 90 s) its exit code and failing tail |
berth_run_start, berth_run_get, berth_run_cancel | a run, in brief |
berth_attempts | an attempts run |
Agents can start and follow runs but not decide their gates: those are a person's.
The tools that start work (berth_task_new, berth_send, berth_exec,
berth_run_start, berth_attempts) take notify (default true) and answer
"notify": true when the agent will
hear back: a <berth-notification>
arrives in its session when the work ends, needs a person or reaches a gate,
so it ends its turn rather than calling berth_wait_turn in a loop.