shipyarddocs
shipyarddocs

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 berthd restarting 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

TemplateDoesSends agents
loopPrompt, 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
reviewA 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
handoffThe 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
broadcastOne prompt (or one each) to several sessions on the box, each when it is idle; waits for every turnYour prompt, once per session
attemptsTry a task several ways: see attemptsSee below
fix-ciA 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 pushAbout 110 characters plus the failing log lines, at most 3 KB
address-reviewNew review comments (merged while it works) to the worktree's agent, a local check, then git pushAbout 90 characters plus the comments, labelled as others' words, at most 4 KB
execOne 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_muttexv8r1yy

A 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 } } }
  1. Each attempt gets the worktree <name>-a<n> and its agent, with the prompt (and its suffix), on its own model and effort when given (so "Opus against Sonnet" is a run). They work at once, up to concurrency.
  2. Each is verified with verify.check; a failure sends its failing tail back, up to max_rounds.
  3. Shipyard collects each attempt's diffstat, commits, check result and tokens.
  4. 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: true adds 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.
  5. 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; or berth run approve RUN --pick N. With pick: "auto" the judge's winner is taken when its check passed.
  6. 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:

StepOn resume
run, checkRuns again. Keep checks safe to repeat
waitWaits again on the same turn, with no clock: a turn that ended while berthd was down (its hook spooled) is seen as ended
promptAt 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_agentThe worktree and session have fixed names, so it adopts them
headlessAdopts the answer if the agent finished, or keeps waiting for it; never asks again
notify, webhookSent again with the same idem_key (an Idempotency-Key header on webhooks)
gate, sleepTheir deadlines are absolute, kept in the journal
prPushes 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. With coalesce, 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.json on the box caps the whole box: {"max_concurrent_runs": 10, "max_concurrent_agents": 6}. More runs wait queued; 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:

ToolReturns
berth_sessionsname, agent, state, turn, where
berth_screenthe last lines (at most 60)
berth_task_newthe new session and worktree
berth_sendthe turn (held until the agent is idle, by default)
berth_wait_turnthe state after at most 90 s; if not ended, a cursor to call again with (for short waits)
berth_execa detached run; with wait (at most 90 s) its exit code and failing tail
berth_run_start, berth_run_get, berth_run_cancela run, in brief
berth_attemptsan 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.

On this page