mcpField
I
image-compare

image-compare

github.com/pascalorgTesting & quality10093 installsUpdated 7w ago
Repository

About image-compare

image-compare compares two images pixel by pixel and reports their differences. It is for developers checking visual implementations or regressions, with mismatch statistics and a generated diff image highlighting changes in red.

Key features

  1. 01Compares images pixel by pixel
  2. 02Resizes inputs to matching dimensions
  3. 03Configurable comparison threshold
  4. 04Reports mismatch counts and percentage
  5. 05Generates a red-highlighted diff image

Use cases

  1. 01Compare a UI screenshot with a design
  2. 02Check visual regressions between versions
  3. 03Verify a page against a Figma export

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/pascalorg/skills --skill image-compare

After installing, type/image-comparein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

scripts/
image-compare.js
image-compare.sh
package-lock.json
package.json

Details

From the project README

Image Compare

Compare two images pixel-by-pixel. Returns a diff count, mismatch percentage, and generates a diff image highlighting the differences in red.

When to Use

  • Comparing an implementation screenshot against the original design
  • Spotting visual regressions between two versions of a page
  • Verifying that a UI matches a Figma export

How It Works

  1. Both images are loaded and resized to match dimensions (uses the smaller of the two)
  2. pixelmatch compares every pixel and flags differences above a configurable threshold
  3. Returns mismatch stats and writes a diff image showing changes in red

Usage

bash <skill-path>/scripts/image-compare.sh <image1> <image2> [diff-output.png] [threshold]

Arguments:

  • image1 — First image path (required)
  • image2 — Second image path (required)
  • diff-output.png — Path to write the diff image (optional, defaults to ./diff.png)
  • threshold — Pixel matching threshold 0-1, lower is stricter (optional, defaults to 0.1)

Examples:

# Compare a design against implementation
bash <skill-path>/scripts/image-compare.sh design.png screenshot.png

# Compare with custom threshold and output path
bash <skill-path>/scripts/image-compare.sh before.png after.png ./changes.png 0.05

Output

{
  "totalPixels": 921600,
  "differentPixels": 4523,
  "mismatchPercentage": 0.49,
  "dimensions": { "width": 1280, "height": 720 },
  "diffImage": "./diff.png",
  "threshold": 0.1
}
FieldTypeDescription
totalPixelsNumberTotal pixels compared
differentPixelsNumberNumber of pixels that differ
mismatchPercentageNumberPercentage of pixels that differ
dimensionsObjectWidth and height used for comparison
diffImageStringPath to the generated diff image
thresholdNumberSensitivity threshold used

Present Results to User

After comparing, present a summary:

Comparison: design.png vs screenshot.png

Mismatch: 0.49% (4,523 pixels out of 921,600)
Diff image saved to: ./diff.png

The images are nearly identical. Differences are highlighted in red in the diff image.

Interpret the percentage:

  • < 0.1% — Essentially identical
  • 0.1% - 1% — Minor differences, likely anti-aliasing or sub-pixel rendering
  • 1% - 5% — Noticeable differences, worth reviewing
  • > 5% — Significant visual changes

Troubleshooting

Different sized images — The script automatically resizes both images to the smaller dimensions. For best results, use images of the same size.

Too many false positives — Increase the threshold (e.g., 0.2). Anti-aliasing differences are common between browsers.

Comments

Markdown supported