shipyarddocs
shipyarddocs

Guides

Visual diffs

Before and after screenshots of a worktree's pages at phone, tablet and desktop widths, diffed pixel by pixel, with what broke, shown as an artifact beside the agent's chat.

After a change that can show on a page, an agent runs one command on the box:

berthd shots compare

It screenshots the worktree's pages and the same pages of a base (the main checkout's dev server, by default) at 375, 768 and 1280 pixels wide, diffs every pair, and keeps the result as a visual diff: an artifact you see in the agent's chat, as a tab, and on the worktree's board. The agent reads a few lines (about 450 tokens for 6 pages × 3 sizes) and fixes what it didn't mean before saying it's done; compared again, the same visual diff gets a new version, live.

Agents learn this from the berth-visual-diff skill, which berthd integrations install gives Claude Code and Codex.

What the agent reads

visual diff 88970ccc33 v1: search-perf vs main, 6 pages × 3 sizes in 5.3s
2 of 6 pages changed · most: /search at 768 (48%) · 1 layout warning · 3 new shots · 3 errors
  /account       375,768,1280  ERROR: after: HTTP 500
  /deals         375,768,1280  NEW: 404 before
  /search          375  changed    30%  5 regions, largest 359x712 at 16,704 (section.wrap in main)
                      ⚠ now scrolls sideways: 125px wider than the screen
                      look: 86882c2594cf18d7.png
  /                375  changed   1.7%  1 region, largest 344x64 at 16,296 (form.hero-search in section.wrap.hero); height 1811 → 1823; 450px from y=1277 only moved +12px
  /about                unchanged at every size
look: before|after crops of each shot's largest change, in /…/artifacts/88970ccc33/img/
Artifact 88970ccc33 v1 · visualdiff · Visual changes: search-perf vs main
  • ERROR: the page failed on one side (a 500, a refused connection, a page that never settled), with the page's own JavaScript error.
  • NEW / GONE: a 404 on one side.
  • changed N% and its regions: where pixels changed, the largest named by the element under it (its tag, id or classes, a button's text, and the named element around it).
  • only moved: content pushed down by something taller above it. Rows are aligned before the diff, like lines in a text diff, so that counts as moved, not changed.
  • ⚠ now scrolls sideways: the page is wider than the screen at that size and wasn't before, the usual sign of a broken small-screen layout, flagged however few pixels changed.
  • look: a before|after crop of each shot's largest change, for the agent to read when the numbers don't say enough.

In the app

The tab opens on the most changed page at its most changed size:

  • What was compared: main@3a7b95d → search-perf@e60622c, how many pages and sizes and how long it took, and chips for what needs a look ("/search at 375 scrolls sideways", "/account fails", "/deals new", "3 unchanged"). The same chips are on the card in the chat and on the board.
  • Pages as chips, most changed first, each with its change; sizes as tabs with each size's percentage; Light and Dark when both were shot.
  • Slider (drag, or ←/→ on the handle), Side by side, Flicker and Onion skin.
  • Heatmap: changed pixels glowing amber to magenta by how much they changed, over a faded page; Glow sets how strongly. Regions: numbered boxes around each change, listed beside the stage on a wide pane, with the element each is in. Masked areas are hatched; content that only moved has an "only moved +12px" band; a page that scrolls sideways has a red edge.
  • Changes ‹ n of N ›, or n and p: every change across pages and sizes in turn, errors first, then a sideways scroll's regions, then by size, then new pages.
  • All N shots: every page × size at once, most changed first; click one to compare it.
  • Accept as baseline: keeps the latest version's after-shots as the worktree's accepted look (asked once; main isn't changed). A later berthd shots compare --base accepted shows only what changed since: the all clear when nothing did.

Beside the chat or in a narrow pane, the controls fold to icons and the region list moves out of the way.

Bases

--baseCompares with
main (the default)the main checkout's dev server, as it runs now. Without --base, when it isn't running, the worktree's turn-start baseline instead, said on a note: line; with --base main, the compare refuses and says what to do
turn-startwhat berthd shots baseline saved, at the start of the agent's turn
acceptedwhat Accept as baseline (or berthd shots accept ID) kept
any namea baseline saved with berthd shots baseline --name NAME

A different base is a different visual diff; re-running against the same base adds a version.

Pages behind a login: berthd shots compare --as pro@acme.test logs both sides in as one of the project's dev users first. The worktree and main each have their own dev server and database, so each side runs its own login; a saved baseline was shot as it was. The visual diff records the email in its settings (login).

Repeatable shots

Two loads of an unchanged page must give the same pixels, or every compare shows noise. Each compare runs its own short-lived Chromium (the agent browser's binary, never the agent's own browser or its log-in) and:

  • emulates reduced motion, finishes every finite animation at its end and removes endless ones, turns off transitions, hides the caret and smooth scrolling;
  • waits for the load event and the network to be quiet, fonts, and every image, after scrolling through the page so lazy content loads;
  • shoots at a fixed viewport per width (375×812, 768×1024, 1280×800), at scale 1, in UTC and en-US, full page up to 4,000 pixels;
  • paints masks flat on both sides and leaves them out of the diff.

The diff is pixelmatch's colour distance and anti-aliasing test, ported to Go, at a threshold of 0.03 (both sides render in one Chromium, so there's no cross-machine noise to forgive). A shot under 0.02% changed counts as unchanged.

Configure it

In the repository's .berth/config.json (it runs nothing, so it needs no trust; every field):

{
  "shots": {
    "pages": ["/", "/search", "/login", "/account"],
    "sizes": [375, 768, 1280],
    "mask": ["time", ".avatar", "[data-testid=relative-date]"],
    "color_scheme": "light"
  }
}

Flags override it for one run:

berthd shots compare --pages / /search --sizes 375 1280
berthd shots compare --mask .ad-slot --color-scheme both
berthd shots compare --base turn-start --note "after the refactor"
berthd shots baseline                      # saves turn-start
berthd shots accept 88970ccc33             # Accept as baseline

To take turn-start whenever an agent starts on a prompt, add a hook (repository hooks run in the worktree; about 5 seconds in the background):

{
  "hooks": [
    { "on": "agent.started", "run": "[ \"$BERTH_SIGNAL\" = prompt ] && berthd shots baseline >/dev/null 2>&1 || true", "timeout": "2m" }
  ]
}

An edit in the first seconds of a turn can land before the baseline is shot; compare with main when that matters.

Where it lives, and safety

A visual diff is an artifact of kind visualdiff: its versions are berth.visualdiff/v1 manifests in the box's state folder, its images PNGs named by their content hash beside them (a re-run adds only what changed; images go with the versions that name them, as the first and newest eight are kept). Baselines live in the box's shots/ folder. Nothing is written to the worktree.

  • The compare's browser reaches only the two sides it compares, through their proxy names, as the laptop does; nothing else on the box or the internet.
  • The app draws a visual diff from its data, and reads its images with the box's credentials into blob: URLs: no image is ever served from an origin of its own, and nothing an agent wrote runs.
  • Only berthd shots compare makes one: berthd artifact add refuses a hand-written visual diff.

It takes about 5 to 7 seconds for 6 pages × 3 sizes on a laptop (pages × 0.7s per tab; sizes and sides run in parallel, up to parallel tabs).

Not yet

  • Pages behind a log-in: the compare's browser has no cookies, so it sees what a signed-out visitor sees.
  • Per-worktree databases: when main and the worktree read different data, every list differs. Compare with turn-start (same database), or mask the lists.
  • Hover and open states, canvas and video, and baselines shot on another machine (a different Chromium renders text a pixel differently; the compare notes it).

On this page