Back to Blog

Visual Regression Testing in Cursor: Diffy Skills and CLI Setup

Cursor's agent can look at a page, but not compare it with a known-good version. How to give it Diffy's visual regression checks with skills, the CLI and a rule.

Yuriy Gerasymov
Yuriy Gerasymov
20 Nov 2026 · 6 min read

Cursor’s agent can open a browser, load your page and take a screenshot. That’s useful for checking the one thing you just changed. It isn’t visual regression testing. A screenshot tells the agent what the page looks like now, not what it looked like before, and nobody asks it to look at the other forty pages and three breakpoints that share the stylesheet it just edited.

For that, the agent needs something to compare against. This post shows how to give Cursor’s agent Diffy’s visual checks: through Diffy’s open-source skills, which use the same SKILL.md format Cursor loads, or through the Diffy CLI directly. It’s a follow-up to Claude Code visual regression testing, which covers the skills in depth.

One thing up front: we built and tested the Diffy skills in Claude Code. Everything below about Cursor comes from Cursor’s own documentation, as checked on 20 November 2026. If something works differently in your version, tell us.

Looking at a page vs comparing it

Cursor’s browser tool lets the agent navigate pages, click, fill forms, read the console and take screenshots, and the agent sees those screenshots as images. It’s a good way for the agent to check its own work on the page it’s changing.

A visual regression check answers a different question: across every page and breakpoint you care about, what changed compared with a known-good version? To answer it you need:

  • a reference, such as production, staging or a baseline taken before the edit;
  • the same renderer on both sides, so fonts and browser versions don’t show up as changes;
  • a per-page, per-breakpoint result the agent can read as numbers;
  • a report a person can open before merging.

Diffy provides all four. The agent’s job is to run it and read the result.

Option 1: add Diffy’s skills to Cursor

The Diffy skills are ten SKILL.md files, MIT-licensed, built on the Diffy CLI. Two do the whole job in one go:

  • visual-diff captures your running local app in Diffy’s screenshot-worker Docker container before you edit, captures it again after, and diffs the two.
  • compare-environments has Diffy screenshot two deployed environments on its servers, for example production and a preview URL, and diffs them.

The other eight are building blocks: create a project, read or update its settings, take or check a screenshot set, compare two sets, and summarise a diff.

Install them

The skills are packaged as a Claude Code plugin, and Cursor doesn’t load that format: its plugin reference lists only .cursor-plugin/plugin.json and a root plugin.json. But Cursor’s skills docs say it loads skills from .cursor/skills/ in your project (or ~/.cursor/skills/ for every project) and walks that folder recursively for any SKILL.md. So copy the whole plugin folder in:

git clone https://github.com/DiffyWebsite/diffy-skills /tmp/diffy-skills
mkdir -p .cursor/skills
cp -R /tmp/diffy-skills/plugins/diffy .cursor/skills/diffy

Copy the whole plugins/diffy folder, not just the skill folders. The local-capture skills run a script from scripts/, which they expect two levels above each SKILL.md.

Each skill’s name matches its folder, as Cursor requires, so the skills show up as /visual-diff, /compare-environments and so on, without the diffy: prefix they have in Claude Code. You can call one from the / menu in Agent chat, or let the agent pick it when your request matches its description. The files also contain an allowed-tools field from Claude Code. Cursor’s docs don’t list it, so don’t rely on it to limit what the agent can run in Cursor.

Add the skills’ working folders to .gitignore:

.diffy-skills/
.diffy-visual/

Install the CLI and log in

The skills are built on the Diffy CLI and use its login. The CLI is a PHP 8.2+ application shipped as a single file:

wget -O /usr/local/bin/diffy https://github.com/diffywebsite/diffy-cli/releases/latest/download/diffy.phar
chmod a+x /usr/local/bin/diffy
diffy auth:login <API_KEY>

Create the API key at app.diffy.website/#/keys. API access is included in every Diffy plan, the free one too.

For local capture you also need Docker and Node. The first local run pulls Diffy’s screenshot-worker image (about 1.1 GB) and clones the worker code into ~/.cache/diffy/diffy-worker. That download is easier from your own terminal than from inside the agent’s sandbox, so run it once yourself:

node .cursor/skills/diffy/scripts/run-worker.mjs --provision
node .cursor/skills/diffy/scripts/run-worker.mjs --check

Let the agent reach Diffy

Cursor runs agent terminal commands in a sandbox, and its run modes docs say network access there is blocked by default. The Diffy CLI needs app.diffy.website. Allow it in .cursor/sandbox.json in the project, or in ~/.cursor/sandbox.json for every project:

{
  "networkPolicy": {
    "default": "deny",
    "allow": ["app.diffy.website"]
  }
}

In Cursor’s default network mode, this list is added to Cursor’s built-in defaults for common package managers and language tools. In the “sandbox.json Only” mode, only your list applies, and “Allow All” ignores it. If you’d rather not change the file, approve the command if Cursor asks to run it outside the sandbox. Either way, check your team’s security policy first.

Local capture starts a Docker container on your machine. If a command fails inside the sandbox, Cursor’s docs say the agent can rerun it outside the sandbox, and Cursor asks for your approval when it does.

Use it

With the skills in place, a request in plain words is enough:

  • “Take a Diffy baseline of localhost:3000 for project 12345, then I’ll change the header.” After the edit: “Compare it now.” The agent runs visual-diff: capture, edit, capture, diff, then a table of pages and breakpoints sorted by how much changed, with a link to the report.
  • “Compare production with https://pr-42.example.com in Diffy.” The agent runs compare-environments, and Diffy screenshots both sides on its servers. Comparing against a custom URL like a pull request preview needs a paid Diffy plan.

The skills never delete Diffy projects, and none of them approves changes in a diff. That stays with you.

Option 2: the CLI without skills

If you’d rather not add skills, the agent can call the CLI directly. Three commands cover it:

diffy project:compare <PROJECT_ID> prod custom --env2Url="https://pr-42.example.com"
diffy diff:get-status <DIFF_ID>             # prints 1 once the comparison is complete
diffy diff:get-result <DIFF_ID> --format=json

The details, including why the agent should wait for the status before reading results, are in visual regression testing for AI coding agents.

Make it a habit with a rule

Skills are used when the agent decides they’re relevant or when you call them. To make the check part of every UI change, add a project rule. Cursor reads rules from .cursor/rules/ as .mdc files; a rule with alwaysApply: true is included in every chat. Cursor also reads AGENTS.md, if you keep instructions there for several agents.

---
description: Run a Diffy visual check after UI changes
alwaysApply: true
---

After any change to CSS, templates or UI components:

1. If a local dev server is running, use the visual-diff skill against Diffy project 12345.
   Take the baseline before editing.
2. Otherwise, once the change is deployed to a preview URL, use compare-environments
   to compare production with that URL.
3. Report the pages and breakpoints that changed, largest first, and the report link.
4. Never approve changes or update baselines in Diffy. Leave that to a person.

Save it as .cursor/rules/visual-checks.mdc. A rule is guidance, not enforcement: the agent can still skip it. Keep the real gate in CI, where Diffy reports on the pull request through GitHub Actions or GitLab CI.

Frequently asked questions

Can Cursor do visual regression testing on its own?

Cursor’s agent can open a browser and take screenshots, so it can look at a page. It doesn’t keep baselines or compare every page and breakpoint against a known-good version. For that you add a visual regression tool such as Diffy and let the agent run it.

Does the Diffy plugin for Claude Code work in Cursor?

Not as a plugin. Cursor loads plugins with a .cursor-plugin/plugin.json or a root plugin.json manifest, and the Diffy plugin ships a Claude Code manifest. The skills inside it are SKILL.md files, the format Cursor’s docs say it loads from .cursor/skills/. We have only tested them in Claude Code.

Why does the Diffy CLI fail inside Cursor with a network error?

Cursor runs agent terminal commands in a sandbox where network access is blocked by default. Add app.diffy.website to networkPolicy.allow in .cursor/sandbox.json, or approve the command if Cursor asks to run it outside the sandbox.

Can Diffy screenshot my localhost from Cursor?

Diffy’s servers can’t reach localhost. Either capture locally with the visual-diff skill, which runs Diffy’s screenshot-worker Docker container on your machine, or compare a preview deployment, staging site or tunnel URL.

Try it

Create a free Diffy account, add a project with your pages and breakpoints, and create an API key. The free plan includes 500 screenshots a month and the API.

Start free: 500 screenshots a month

Related reading: Claude Code visual regression testing · Visual regression testing for AI coding agents · Screenshot testing: how to get reliable results · Diffy integrations

Related Articles

More guides on visual regression testing, QA automation, and keeping your site pixel-perfect as it changes.