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 compareIt 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 acceptedshows 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
--base | Compares 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-start | what berthd shots baseline saved, at the start of the agent's turn |
accepted | what Accept as baseline (or berthd shots accept ID) kept |
| any name | a 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 baselineTo 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 comparemakes one:berthd artifact addrefuses 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).
Artifacts
Charts, tables, diagrams, notes and small pages an agent makes for you, shown in its chat, as a tab and on the worktree's board, and updated live.
Agent browser
A headless browser on the box for each worktree, which agents drive with short commands and you can watch live, confined to the worktree's own pages.