Getting started
First agent
Start Claude Code, Codex or another agent in a worktree, see what it needs, and steer it.
Let the box report agent state
Shipyard knows whether an agent is working, waiting for you or done from the
agents' own hooks, installed on the box where the agents run. berthd install (which berth add ssh and the install script run) installs them for
every agent CLI it finds on the box, and says so:
Agent integrations (hooks for needs-you, working and done; Shipyard's skills):
Claude Code: skills in /home/me/.claude/skills; hooks added in /home/me/.claude/settings.json
Not found: Codex, Cursor Agent. After installing one, run: /home/me/.local/bin/berthd integrations install codex|cursorAn agent you install on the box later has none. The first time the app starts it there, it offers to install them (Install Claude Code's hooks on my-box). Or run, from the laptop:
ssh me@my-box '~/.local/bin/berthd integrations install claude'Use codex, cursor or all for other agents. For Codex this sets
notify in ~/.codex/config.toml, unless you already use it for something
else; then it prints the line to change yourself. The full path matters: a
command over SSH may not have ~/.local/bin, where berthd lives, on its
PATH. To skip all this, install with --no-integrations.
This also installs Shipyard's skills, so
agents on the box know how to use Shipyard themselves. The hooks record
berthd's full path, so they work whatever PATH the agent has. Without them
an agent still runs; Shipyard just can't tell what state it is in (apart from
Claude Code's "trust this folder" question at startup, which it spots on the
screen).
Start a task
A task is a worktree with an agent already running in it, made in one step:
berth task new my-box/app/fix-login --agent claude --prompt "Fix the login redirect"| Flag | What it does |
|---|---|
--agent ID | Which agent: see berth agents my-box for what the box can start |
--prompt TEXT | Its first prompt; its first line, cut to about 48 characters, becomes the session's title |
--title T | Name the work yourself instead |
--branch B, --base REF | As for worktree new |
--open split|tab | Ask the app to show the new agent: in its worktree when you are looking at it, otherwise as a notice that opens it |
The built-in agents, offered when their command is installed on the box:
| ID | Agent | Command |
|---|---|---|
claude | Claude Code | claude |
codex | Codex | codex |
opencode | OpenCode | opencode --prompt … |
gemini | Gemini CLI | gemini -i … |
cursor | Cursor Agent | cursor-agent |
A repository can add its own or replace these in
.berth/config.json.
In the app
The app starts work in one place, the composer: on home (the workspace
with no worktree open), in an empty worktree, before an agent's first prompt,
and in a dialog from ⌘N anywhere. Write what to do and press Enter. Its
pickers say where (the project, the box when there are several, a new
worktree or the main checkout) and which agents: one is a task; several, one
model against another, or ×2 of each are attempts,
compared by a judge; No agent makes the worktree alone. Options (the
sliders) open what the new worktree starts from (#1234, a branch, a pull
request or issue link), its folder, branch, base and
template, and for attempts their check and judge.
Its Running agents tab sends a prompt to agents already at work instead
(see broadcast).
Each agent is named after its task: the first line of the prompt
("Fix checkout webhook"), with the agent beside it. Rename one from its tab's
menu (right-click), or berth session rename my-box/SESSION "New title".
To start an agent in a worktree that already exists, or a plain shell:
berth session new my-box/app/fix-login --agent codex --prompt "Review the diff"
berth session new my-box/app/fix-login # a shellWatch it
berth sessions my-box # every session, with its agent's state
berth session screen my-box/SESSION # what it shows right now
berth attach my-box/SESSION # take over this terminal; Ctrl-b d detachesSessions run in tmux on the box. Detaching, closing the app or sleeping the laptop leaves them running.
In the app:
- Agent Dashboard (⌘J) shows every agent on every box by what it needs: Needs you, Working, Done, Ready.
- Review lists agents' finished work, to approve, send back or discard.
- A notification tells you when an agent is waiting for you.
The sidebar starts with Home (the Agent Dashboard, or the harbour home with Labs), Review, Worktrees and Automations. Everything else, Kits and plugins' screens included, is under More; right-click a place, or use Customize sidebar…, to pin, move or hide it. Drag the sidebar's right edge to make it wider or narrower (200 to 420px); double-click the edge for the default, or focus it and use ← and →. Dragged past its narrowest it folds to the rail of agents (⌘), and dragging the rail's edge out opens it again. The width is kept. The arrows at the sidebar's top, Go → Back (⌘[) and Go → Forward (⌘]), and a mouse's back and forward buttons take you back through the places you've been, as in a browser: a page, or a worktree and its tab. When the worktree you're in is archived or removed, you go back to where you were before it. Help → Keyboard shortcuts (⌘/) lists every shortcut, in your keyboard's layout: on a Norwegian one Back and Forward read ⌘Å and ⌘¨. In the Mac app they are in the menu bar too, under File, View, Go and Help. Keyboard shortcuts has what each does where. View → Zoom in (⌘+ or ⌘=), Zoom out (⌘−) and Actual size (⌘0) make the app's text bigger or smaller, from 11 to 20px; the size is kept, and also set in Settings → Appearance → Text size. With a terminal focused they size the terminal's font instead, as in a terminal app.
Steer it
berth session send my-box/SESSION "Now add a test for it" --wait
berth loop my-box/SESSION --check "pnpm test" --prompt "Make the tests pass"send --wait returns when the turn it starts ends. loop prompts, waits,
runs the check in the worktree and sends failures back until it passes. More
in orchestration.
What next
- Automations: run the tests after every agent turn, or send PR review comments straight to the agent.
- Hooks and gates: a notification when an agent waits, or a rule that refuses an action.
- The phone companion: answer agents from your phone.