Install, then ask
What it needs: Node 22 or later and git; Playwright with its Chromium, in the project or installed globally (your
agent asks before adding it); and, to put the pictures in a pull request, the GitHub CLI (gh), signed in. It works
on any site you can open in a browser, whatever it is built with.
One skill, any coding agent that reads Agent Skills:
npx skills add victorsaly/sideshot -g
-g puts it in your home folder, for every project; leave it out for this project only. The same line serves Claude
Code, Codex, Cursor, OpenCode and the other agents the skills command knows: it asks which of yours to put it in, or
name them with -a (-a '*' for all). Add .sideshot/ to .gitignore: the pictures are taken there. Then, on a
branch with a pull request:
SideShot this PR: the pricing table changed. Compare it with production, on desk and phone.
Then carry on: "add dark mode", "also the checkout page", "put it in the PR".
A part is the piece of the page your change touches, named and found with a CSS selector (plans=#plans); SideShot
pictures the part, not the whole page, so before and after line up. Desk and phone are its two screens unless
you name others (1280×900 and 390×844).
Save where before and after live in .sideshot.json at the project's root, so later runs need only the parts:
{ "before": "https://example.com", "after": "http://localhost:4321",
"devices": { "web": "desk", "mobile": "phone", "kiosk": "1080x1920" } }
Claude Code, as a plugin (updates come through /plugin):
/plugin marketplace add victorsaly/sideshot
/plugin install sideshot@sideshot
Then type /sideshot or just ask. From a terminal: claude plugin marketplace add victorsaly/sideshot and
claude plugin install sideshot@sideshot.
By hand, no agent at all: copy skills/sideshot/ anywhere and run its script (see Options).
What you get
Real pictures, from a real pull request: a studio page whose merge button learned to wait while work was still
running (agentic-blog #151).
| On a desk | On a phone | Light and dark |
|---|
| | |
| The part that changed, not the whole page, so before and after line up. | The same change where most people read it. | Colour and contrast checked in both themes. |
Add --note and --mark-changes and the picture says what changed: a numbered ring on what the change is about
(its words go under the table), a box on everything else that differs, a dashed rule where something went.
- What changed, said on the picture. A numbered ring around what the change is about, with its words under
the table, and an outline on everything else that differs. Content that only moved is left alone, and so is a
card beside the one that changed.
- Your screens, not ours. Desk and phone by default; tablet, laptop, wide, or any size you name.
- A colour that stands out on your page. Marks are marigold unless your page is marigold too; then SideShot
picks the colour your pictures use least.
- Pictures that stay out of your code. They live on a
sideshot branch that never merges, and --prune
takes off the pictures of pull requests closed long ago, so it does not grow for ever.
- A table that does not pile up. The description gets one before/after table between markers; running again
replaces it.
- You look first, and what you saw is what goes in. Each run makes one overview sheet for each part, every
before beside its after. When they look right,
--reuse publishes those same pictures instead of taking new ones.
- Quick. Pictures are taken four at a time, and each page is loaded and settled once for all its pictures:
eight pictures in about seven seconds.
- Honest about gaps. A part that was removed shows as (not there) on after, and the run says so.
- Something new, shown as it is. A part that was not there before is shown on its own, with nothing drawn on
it, and when all of it is new the description says What's new.
--new does the same sooner, never opening a
"before" site at all.
- Nothing to compare, said plainly. A pair the same before and after is left out, and named under the table.
When nothing is left, nothing is pushed, and the description says why.
Instead of screenshots by hand
- Open the site as it is and your branch, side by side.
- Picture the part on each: desk and phone, light and dark, before and after. Eight pictures.
- Crop every pair so it lines up, upload them, and type the table.
- Do it all again after every review comment.
+ One sentence to your agent. Eight pictures of a small page take about seven seconds.
+ Cropped to the part and lined up, with what changed marked.
+ The table written into the pull request, and replaced, not added to, on the next run.
What it writes, and who sees it
- On your machine: the pictures, in
.sideshot/<pull request>/. Nothing leaves it until you say so.
- With
--publish, after you have looked: one commit of those pictures to the sideshot branch on origin
(the picture branch; --branch names another). It never merges, so your code stays as it was.
- With
--update-pr: the table, between markers in the pull request's description. Running again replaces it.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
