shipyarddocs
shipyarddocs

Guides

Agent integrations

Claude Code, Codex, Cursor, Gemini CLI, OpenCode and oh-my-pi hooks, the skills Shipyard teaches agents, and announcing events from any tool.

Shipyard works with the tools around it in both directions: tools drive Shipyard through its CLI, berth, and Shipyard drives tools through hooks. Every event records the tool it came from, so a change never bounces back and forth between two tools.

Agent tools → Shipyard

Claude Code, Codex, Cursor, Gemini CLI, OpenCode

berth integrations install claude     # on a laptop
berthd integrations install claude    # on a box, where agents usually run
berth integrations install all

berthd install (which berth add ssh and the install script run) already does this on a box for every agent CLI it finds there, unless given --no-integrations; for one installed later, the app offers to when it first starts that agent on the box, and berth doctor BOX (or berthd doctor on the box) warns about each agent CLI without its hooks, with the command that installs them.

  • Claude Code: installs Shipyard's skills in ~/.claude/skills/ and SessionStart / UserPromptSubmit / PostToolUse / PermissionRequest / Notification / Stop / StopFailure / SessionEnd hooks in ~/.claude/settings.json. Only permission and question notifications mean "needs you"; the idle reminder and login notices are ignored.
  • Cursor: appends sessionStart, beforeSubmitPrompt and stop hooks to ~/.cursor/hooks.json, after any hooks already there (Orca's are kept).
  • Codex: installs Shipyard's skills in ~/.agents/skills/, where Codex reads user skills (a copy an older version left in ~/.codex/skills/ is removed), adds SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / PermissionRequest / Stop hooks to ~/.codex/hooks.json (trust them once in Codex with /hooks), and a notify line to ~/.codex/config.toml for versions without hooks. Codex's question box is a tool, so its PreToolUse means "needs you" (never with the questions). Notify comes at the end of each of Codex's messages, not only the turn's: once a session's hooks have said a prompt started, its Stop hook alone ends the turn. Codex runs a single notify program, so when the config already sets one to something else, Shipyard leaves it and prints the line to change yourself. Codex can run every session from one shared background daemon, which runs hooks with the environment of the session that started it, so every session's hooks would report as that one. Shipyard starts Codex with --no-daemon when the installed Codex has the flag, and for a Codex hook from another session's folder, or about a conversation another session holds, goes by the folder and the conversation, not the name.
  • Gemini CLI: SessionStart / BeforeAgent / Notification / AfterAgent / SessionEnd hooks in ~/.gemini/settings.json.
  • OpenCode: a small plugin, ~/.config/opencode/plugin/berth.js, that runs the hook when a session gets busy, asks for a permission, or goes idle.
  • oh-my-pi: a small extension, ~/.omp/agent/extensions/berth.ts, that runs the hook when a session starts, a turn starts or ends, or a tool asks for approval. Subagents have no UI and report nothing. On a box it also adds berthd mcp to mcpServers in ~/.omp/agent/mcp.json, next to any servers already there.

Every account

A box can have several logins per agent (the Usage & accounts plugin): each Claude Code account is a config folder that CLAUDE_CONFIG_DIR picks, each Codex account a home that CODEX_HOME picks, and an agent reads its hooks (and Claude Code its skills and MCP servers) from that folder alone. So Shipyard installs them in every account folder:

  • the default, ~/.claude and ~/.codex (or berthd's own CLAUDE_CONFIG_DIR and CODEX_HOME);
  • every folder in ~/.berth/accounts/claude/ and ~/.berth/accounts/codex/, where the Usage plugin's Add account… makes them;
  • any folder in your home that CLAUDE_CONFIG_DIR or CODEX_HOME names in the box's ~/.berth/env.json or a project's box-local config.

Only folders that exist count. In another account's folder, Claude Code's settings go in settings.json, its skills in skills/ and its MCP server in .claude.json; Codex's hooks go in hooks.json and config.toml. Codex reads user skills from ~/.agents/skills/ whatever CODEX_HOME is, so all its accounts share one copy. berthd integrations shows where they are:

Claude Code: hooks and 7 skills in ~/.claude, ~/.berth/accounts/claude/personal
Codex: hooks in ~/.codex, ~/.berth/accounts/codex/work; 7 skills in ~/.agents/skills

berthd doctor says the same, and warns about an account without them. A new account gets them without a command: Add account… installs them in the folder it makes, and when berthd starts a session whose CLAUDE_CONFIG_DIR or CODEX_HOME names a folder without them, it installs them there before the agent starts (a file read when they're there already). That happens only for an agent whose default account has Shipyard's hooks, and the new account gets the skills the default has. Installing or removing user skills (berthd skills, Settings → Agents) does it for every Claude Code account.

An account folder other than ~/.claude or ~/.codex may be one a project names, so Shipyard never writes there through a symbolic link: a settings.json that is a link is left as it is, and that account is reported as not installed.

After an upgrade

berthd brings hooks it installed before up to date when it starts, in every account, and gives an account added since the default's hooks and skills. Every session Shipyard starts has BERTH_SESSION (and, for an agent preset, BERTH_AGENT) in its environment; the hook sends it along, so Shipyard knows which session a hook came from when agents share a worktree. When berthd is down, berthd hook keeps the event in ~/.berth/box/spool/ and berthd publishes it, in order, when it starts. What each agent can report, and how Shipyard fills the gaps, is in turns.

Installs are idempotent, keep every existing setting, back up the previous file to *.berth-backup, and refuse to touch a file that is not valid JSON.

The hooks run berth hook TOOL EVENT, which turns the tool's payload into an event (agent.finished, agent.waiting, agent.started, agent.ready, agent.exited). Only identifiers and the working directory are kept: prompts, messages, and transcripts never leave the tool. A hook never fails or blocks the tool that called it.

Skills

Shipyard ships its skills embedded in the binary:

SkillTeaches agents to
berthfind their way around: boxes, repos, worktrees, tasks, sessions, the worktree's $BERTH_* variables and ports, .berth/config.json, services
berth-orchestrateprompt, wait for, check, loop, hand off to and review with other agents, and never answer for the human
berth-previewrun the dev server on the worktree's port and open it in the user's Shipyard app (berthd preview)
berth-hookswrite hooks and gates at the right scope, with the event catalog
berth-artifactsshow you a chart, table, diagram, notes or a small page in Shipyard instead of a wall of text, and update it live (Artifacts)
berth-visual-diffcheck what a change did to the app's pages before saying done (berthd shots compare): phone, tablet and desktop shots of the worktree and main, diffed, with what broke (Visual diffs)

Install them for the box's user, or inside one repository for just that project, for Claude Code, Codex, or both:

berthd skills                                         # what is installed where
berthd skills install                                 # all, for both agents, for this user
berthd skills install berth-preview --agent claude --target project --location shop
berthd skills install --target project --location shop --commit   # visible to git, to share
berthd skills uninstall berth-hooks
berth skills devl install                             # the same from a laptop
TargetClaude CodeCodex
user~/.claude/skills/<skill>/, and skills/<skill>/ in each account's folder~/.agents/skills/<skill>/, which every account reads
project<repo>/.claude/skills/<skill>/<repo>/.agents/skills/<skill>/

Project skills are listed in the repository's .git/info/exclude so they are not committed, unless installed with --commit. berthd skills reports each copy as installed, outdated (Shipyard has a newer version: install again) or missing; the app shows the same in Settings → Agents and in a project's settings. Removing only deletes a folder whose SKILL.md is Shipyard's skill of that name.

The sidebar's reminder

When a box is online, has Claude Code or Codex, and its user's skills are missing or out of date (as they are after a box upgrade, until installed again), the app says so at the foot of the sidebar: "devl: Shipyard's skills aren't installed for Claude Code", or "gpu: 3 skills are out of date". One box shows and the others fold under "2 more boxes"; with the sidebar folded it is one button that opens the same notices.

  • Install now (or Update now) installs all of Shipyard's skills for the box's user, for the agents the box has, as berthd skills install does. If a before:skills.install gate refuses, or the box goes offline on the way, the notice says why, with Retry and Settings, which opens Settings → Agents on that box.
  • Snooze puts that box's notice away until tomorrow morning, for a week or for a month. A snooze is for the state it was made in: one made while skills were out of date says nothing of a box that later has none. Once its time has passed, the box reminds again, as after the next upgrade.
  • Don't remind me for devl holds until you turn Remind me about devl's skills back on in Settings → Agents. A snooze shows there too, and ends with Remind me now.

Skills inside a project never raise it; those stay in the project's settings. The app asks a box when it connects, after an upgrade, and when skills are installed or removed there, never on a timer, and the notice makes no toast, sound or system notification. What you chose is kept by the laptop agent on this computer (~/.berth/app/skills-notice.json), so it is the same in every window; another computer paired with the same box asks for itself.

The API is GET /v1/skills[?location=L], and POST /v1/skills/install and POST /v1/skills/uninstall with {skills, agent, target, location, commit}. Changes announce skills.installed and skills.removed, and before:skills.install and before:skills.uninstall gates can refuse them.

The skills tell agents never to share a port publicly unless a person asked, and never to answer an agent's question on the user's behalf.

Anything else

Any script can announce an event:

berth emit agent.finished path="$PWD" --origin=mytool     # on a laptop
berthd emit deploy.done url=https://… --origin mytool      # on a box

Worktrees from any tool

berthd watches its locations. A worktree created by another app, an agent, or plain git worktree add shows up in Shipyard and produces a worktree.created event with origin detected. Nothing needs configuring in those tools.

Shipyard → tools

Shipyard drives other tools through hooks and plugins rather than adapters built into it: a hook on worktree.created can register the worktree with any tool that has a CLI, and a plugin can ship those hooks along with its UI. See hooks and plugins.

berth events streams every event from the laptop and all its boxes; the full list is in events and gates.

On this page