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