shotdiff

See what AI changed before you accept it.

Visual before/after diffs for AI-assisted development. No more hidden layout breaks.

Install • Quick Start • How It Works • Commands • Config

---

The Problem

You ask your AI coding tool to "fix the button styling." It does. But it also:

• Shifted your nav 3px to the left
• Changed the font weight on your headings
• Broke the mobile layout entirely

Code diffs don't show you this. You only find out when a user reports it.

The Solution

npx shotdiff snap          # Take a "before" screenshot
# ... let AI make changes ...
npx shotdiff diff          # See exactly what changed visually

Shotdiff captures your running app before and after changes, then generates a beautiful visual comparison with pixel-level highlighting.

Install

npm install -g shotdiff
# or use directly
npx shotdiff

Quick Start

# 1. Start your dev server
npm run dev

# 2. Take a snapshot before AI changes
npx shotdiff snap

# 3. Make your AI changes (Claude, Cursor, Windsurf, whatever)

# 4. See what actually changed
npx shotdiff diff

A beautiful HTML report opens in your browser with:

• Side-by-side comparison of before/after
• Slider overlay to drag and reveal changes
• Pixel diff highlight showing exactly what moved
• Change summary with percentage of affected pixels

Commands

shotdiff snap

Takes a "before" screenshot of your running app.

shotdiff snap                        # Default: http://localhost:3000
shotdiff snap --url http://localhost:5173   # Custom URL
shotdiff snap --width 1440 --height 900    # Custom viewport
shotdiff snap --full-page                   # Capture full scrollable page

shotdiff diff

Takes an "after" screenshot and shows the visual diff.

shotdiff diff                        # Compare against last snap
shotdiff diff --threshold 0.1       # Sensitivity (0-1, lower = more sensitive)
shotdiff diff --no-open             # Don't auto-open browser

shotdiff watch

Watches for file changes, auto-captures and shows diff after each change.

shotdiff watch                       # Watch current directory
shotdiff watch --url http://localhost:5173  # Custom URL
shotdiff watch --delay 2000         # Wait 2s after change for HMR

shotdiff history

Shows all snapshots taken in this session.

shotdiff history                     # List all snapshots
shotdiff history --clean            # Delete all snapshots

Config

Create shotdiff.config.json in your project root:

{
  "url": "http://localhost:3000",
  "width": 1280,
  "height": 720,
  "fullPage": false,
  "threshold": 0.1,
  "delay": 1000,
  "routes": ["/", "/dashboard", "/settings"]
}

Or pass flags to any command:

Flag	Default	Description
--url	http://localhost:3000	URL to capture
--width	1280	Viewport width
--height	720	Viewport height
--full-page	false	Capture full scrollable page
--threshold	0.1	Diff sensitivity (0-1)
--delay	1000	Delay after file change (ms)

How It Works

1. Snap captures a PNG screenshot using Playwright's Chromium
2. Screenshots are stored in .shotdiff/ (add to .gitignore)
3. Diff uses pixelmatch for pixel-level comparison
4. Results are rendered as a self-contained HTML report with inline base64 images
5. No cloud, no uploads, everything stays local

Works With

Any local development server. Any framework. Any AI coding tool.

• Next.js, React, Vue, Svelte, Angular
• Claude Code, Cursor, Windsurf, Copilot, Cody
• Any URL running on localhost

Requirements

• Node.js 18+
• A running local dev server

Playwright's Chromium is downloaded automatically on first run.

Why Not Percy/Chromatic?

Those are great CI tools for visual regression testing. Shotdiff is different:

	shotdiff	Percy/Chromatic
Use case	Real-time AI change review	CI/CD regression testing
Setup	npx shotdiff snap	Config, CI integration, account
Cost	Free forever	Free tier, then paid
Where	Local, instant	Cloud, async
When	Before you accept AI changes	After you push code

License

MIT

---

_{Built to save developers from invisible AI breakage.}