coss.comshipyard

Plugin SDK

Every call, hook, component and type in @berth/plugin and @berth/plugin/ui.

@berth/plugin is in packages/plugin-sdk. It is types only: at runtime the app provides one shared copy of @berth/plugin, @berth/plugin/ui and React to every plugin. A guide is in writing a plugin.

activate

type Activate = (berth: BerthPluginContext) => void | Dispose | Promise<void | Dispose>;
type Dispose = () => void;

A plugin's default export. definePlugin(activate) is an identity function that gives activate its types.

BerthPluginContext

Adding things

Each returns a Dispose. Everything is also removed when the plugin unloads.

Doing things

Worktree sections

Where work starts in a worktree (its launcher, when no tabs are open, and a new agent's "What should Claude Code do?" screen) the app lists what runs there under the composer: the dev server's private URL, other web tools such as Prisma Studio or Storybook, and data stores, each with Open in tab and copy. Helpers that only listen, such as an agent's headless Chrome, fold away under Other ports.

addWorktreeSection puts a section of your own below that, for the worktree in front. The app gives it a small heading (title) and the composer's width; keep it to a few rows.

import { definePlugin, type WorktreeSectionProps } from "@berth/plugin";
import { Button } from "@berth/plugin/ui";

function Deploys({ berth, worktree }: WorktreeSectionProps) {
  const url = `https://${worktree}-shop.vercel.app`;
  return (
    <div className="flex items-center gap-2 px-2 text-sm">
      <span className="min-w-0 flex-1 truncate font-mono text-xs text-muted-foreground">{url}</span>
      <Button size="xs" variant="outline" onClick={() => berth.openBrowser(url)}>
        Open in tab
      </Button>
    </div>
  );
}

export default definePlugin((berth) => {
  berth.addWorktreeSection({ id: "deploys", title: "Preview deploys", Component: Deploys });
});

The hello-ports example plugin adds one too: the ports open in the worktree, as buttons.

Home widgets

Home is a grid of widgets under the composer, which people arrange themselves. addHomeWidget adds one to its Add widget picker, listed under your plugin's name; once someone adds it, it sits on Home with the app's own.

The app draws the card around it: the heading (icon, title, count, your plugin's name), the menu (size, Refresh now, remove), and an error boundary, so a widget that throws shows a note in its own card. Your component draws only the rows.

Some rules keep Home quick and steady:

  • Fetch only while visible. It is false when the widget is off screen, Home is behind a worktree, or the window is hidden. useWidgetData does this for you, keeps the last read in your storage so it shows at once next time, and reads again on Refresh now.
  • Draw for the room you get. A narrower window has two columns, or one, and a widget is never wider than the grid. Cards are container queries (@max-[320px]:hidden), so hide secondary bits by width.
  • Hold your size while loading. Show WidgetSkeleton rows, never nothing, so Home doesn't move when data arrives.
  • Say when there's nothing. WidgetEmpty takes a scene, a title, a hint and one action.
  • In the picker's preview, preview is true and nothing can be clicked: don't take focus or start anything on mount.
import { definePlugin, useWidgetData, type HomeWidgetProps } from "@berth/plugin";
import { WidgetEmpty, WidgetRow, WidgetSkeleton } from "@berth/plugin/ui";

interface Issue { id: string; title: string; url: string }

function Assigned({ berth }: HomeWidgetProps) {
  const { data, error } = useWidgetData<Issue[]>("assigned", () => fetchAssigned(berth.storage.get("key", "")), { every: 2 * 60_000 });
  if (!data) return error ? <WidgetEmpty scene="storm" title="Couldn't reach Linear" hint={error} /> : <WidgetSkeleton rows={3} />;
  if (!data.length) return <WidgetEmpty scene="calm" title="Nothing assigned to you" />;
  return (
    <div>
      {data.slice(0, 6).map((i) => (
        <WidgetRow key={i.id} onClick={() => berth.openUrl(i.url)}>
          <span className="w-16 shrink-0 font-mono text-[11px] text-muted-foreground">{i.id}</span>
          <span className="min-w-0 flex-1 truncate">{i.title}</span>
        </WidgetRow>
      ))}
    </div>
  );
}

export default definePlugin((berth) => {
  berth.addHomeWidget({
    id: "assigned",
    title: "Linear",
    description: "Issues assigned to you, not done.",
    icon: "ListTodo",
    category: "Work",
    sizes: ["l", "m", "t", "w"],
    source: "Linear's API with your key, every 2 minutes while on screen",
    Component: Assigned,
  });
});

The built-in Linear widget (plugins/issues/src/home.tsx) is this, reading through berth.linear so it never holds a key. The other built-in widgets from plugins are worth reading: Pull requests and CI failures in plugins/pull-request/src/home.tsx, Agent usage in plugins/usage/src/home.tsx, Notes in plugins/notes/src/home.tsx, and the smallest, Hello ports, in plugins/hello-ports.

A built-in plugin that is off until turned on can list its widgets' titles in berth-plugin.json ("homeWidgets": ["Agent usage"]), so the picker offers to turn it on.

api

orchestrate

The same as berth session send|wait, berth exec and berth loop (orchestration). Sessions are named by box and session name; locations as the box API names them, "shop" or "shop/checkout".

prompts

The library the app's prompt picker and broadcast use, one document on this laptop (/v1/app/prompts). Bodies take {{variables}}: the built-ins fill in from the session a prompt goes to ({{worktree.name}}, {{worktree.path}}, {{branch}}, {{base}}, {{project}}, {{location}}, {{box}}, {{agent}}); the rest people fill in when sending.

linear

Linear through the laptop agent, which holds the person's API key and makes the calls. A plugin never sees the key, and can't reach api.linear.app itself: the app's window only talks to the agent.

Without a key the calls other than status() reject with code: "linear_off"; with a key Linear refuses, "linear_auth". Send the person to the key with berth.openSettings("integrations").

helper

A plugin can carry a program of its own that runs on a box: a helper. The plugin's berth-plugin.json names it under box.helper, with a build for each platform and each build's checksum; the laptop agent downloads the one for a box, checks it, and hands it to the box, which keeps it running, gives it a folder for its data and passes requests through to its HTTP API. Leadline is built this way.

berth.helper is always the calling plugin's own helper: there is no plugin id to pass, and no way to reach another plugin's.

Installing puts a program on someone's machine, so ask first, saying which program and which box: Shipyard doesn't ask for you. The consent dialog and the plugin's row in Settings already say the plugin can do this, by the program's name, and because the manifest is part of what is allowed, a plugin can't gain a helper or change it without being asked about again.

berth-plugin.json
{
  "box": {
    "helper": {
      "name": "berth-leadline",
      "version": "0.1.0",
      "args": ["serve", "--dir", "{dir}", "--addr", "127.0.0.1:0"],
      "ready": "helper.json",
      "assets": {
        "linux-amd64": { "url": "https://…", "sha256": "…", "size": 123 }
      }
    }
  }
}

{dir} is the folder the box gives the helper, and ready a file the helper writes there once it is listening. A request goes through the box as JSON, one answer for one request, so a helper's event stream can't be followed this way: read again on a timer while your view is on screen.

React hooks

From @berth/plugin, backed by the app's live state:

And two helpers:

  • worktreeLocation({ location, worktree, main }): how the box API names a worktree, "shop" for the main checkout, "shop/checkout" otherwise.
  • sessionName(session, { sessions?, locations?, place?, agent? }): what the app calls a session: its title ("Fix checkout webhook"), "Fix checkout webhook · Claude Code" with agent, or without a title the agent's name ("Claude Code 2"); place puts where it runs first ("shop / checkout-fix · Codex").

UI components

From @berth/plugin/ui, the app's own kit (coss ui, built on Base UI), with the same props as in the app:

packages/plugin-sdk/src/ui.ts lists every export with a note on each.

Types

The JSON the laptop agent and boxes speak, with field names exactly as the Go structs have them, in packages/plugin-sdk/src/types.ts:

To put these together, start from writing a plugin.

Last updated