image-diff

Compare two PNG screenshots and find out how much changed — pixel-diff count, ratio, a dimension check, and an optional highlighted diff image. For UI-verification loops: screenshot before, make a change, screenshot after, compare.

compare({ path_a: "before.png", path_b: "after.png", output: "diff.png" })
→ { dimensions_match: true, total_pixels: 786432, diff_pixels: 1842,
    diff_ratio: 0.0023, identical: false, output: "diff.png" }

The tool

compare(path_a, path_b, output?, threshold?) — returns:

• dimensions_match — if false, you get a_size/b_size (can't pixel-compare different sizes)
• diff_pixels / total_pixels / diff_ratio and identical
• writes a highlighted diff PNG to output when provided
• threshold (0–1, default 0.1) — per-pixel color tolerance; raise it to ignore anti-aliasing / minor noise

Built on pngjs + pixelmatch — pure JS, no native build.

Setup

npm install
npm test

claude mcp add image-diff -- node /abs/path/image-diff/dist/server.js
# CLI: agent-imgdiff before.png after.png --out diff.png   (exit 0 if identical)

Honest limits

• PNG only (what pngjs decodes). Convert JP/WebP first if needed.
• Pixel comparison, not perceptual/semantic — a 1px layout shift lights up lots of pixels. Use threshold and diff_ratio to set a sensible tolerance.
• Images must share dimensions to be compared (otherwise it just reports the sizes).