Visual Testing Plugin for AI coding agents

Add a Percy visual review loop to your AI coding agent to gate UI changes against a baseline before they merge.

Alongside Percy’s CLI and SDK integrations, the Visual Testing Plugin brings visual testing into AI-assisted development. Developers use it to shift testing left and catch UI regressions as they write code.

When your agent changes UI code, the plugin makes sure a Percy build runs and reviews each visual difference against your change to identify an intended update from a bug. The plugin then blocks the merge if it finds a real regression, all without leaving your editor. To classify differences and catch bugs, the plugin uses the Visual Review Agent, which is available on paid Percy plans.

The plugin works in Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Antigravity, Gemini CLI, and any AI IDE that reads an AGENTS.md file.

Benefits

• Automated reviews: The plugin runs the whole review loop for you, from starting the build to classifying each visual difference, so you do not review builds manually.
• Automatic bug detection and fixes: Working in your IDE with the Visual Review Agent, the plugin catches bugs and unintended changes and drives your agent to fix them before merge.
• Low setup overhead: The plugin sets up Percy, adds snapshots, and connects the workflow to your repository.
• Human review at every decision: You confirm every approve and reject, and the plugin escalates only ambiguous differences for your review.

Prerequisites

• A Percy project and its PERCY_TOKEN available in your environment. Find the token in your Percy dashboard under project settings.
• Your BrowserStack username and access key, used to approve or reject builds.
• A supported AI coding agent: Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Antigravity, or Gemini CLI. Claude Code and GitHub Copilot have a native install. The others install through the AGENTS.md script.
• An existing test suite in a Percy-supported framework, such as Playwright, Cypress, Selenium, Puppeteer, or Storybook. The plugin adds visual coverage to these tests by inserting percySnapshot() calls. It does not write the tests for you.

Getting started takes two steps: install the plugin, then set up Percy in your project.

Install the plugin

Choose the path for your agent.

Claude Code

Add the plugin marketplace and install the plugin from your Claude Code session:

/plugin marketplace add percy/percy-visual-testing-agent
/plugin install percy-visual-testing

Cursor, Codex, Antigravity, or Gemini CLI

For these agents, and any other IDE that reads AGENTS.md, run the installer in your repository:

curl -fsSL https://raw.githubusercontent.com/percy/percy-visual-testing-agent/main/install.sh | bash

The installer adds skills to .percy/skills/ and appends a short section to your AGENTS.md. To do this manually, copy those files from the repository.

GitHub Copilot

Run the same installer with the --copilot flag, which also adds prompts to .github/prompts/ and the /percy-* slash commands to Copilot Chat:

curl -fsSL https://raw.githubusercontent.com/percy/percy-visual-testing-agent/main/install.sh | bash -s -- --copilot

After installing through any path, the /percy:* commands are available in your agent.

Set up Percy in your project

Run the setup command and follow the prompts:

/percy:setup

When you run it, setup checks for PERCY_TOKEN and tells you what to do if it is missing, then detects your project’s current state and routes you down the matching path. The first run takes about five minutes and a few confirmations.

The path depends on where your project starts:

Once setup finishes, the workflow is connected to your repository, and the review loop runs on your next UI change. To grow coverage later, run /percy:expand-coverage <test file>. The plugin analyzes the test file and proposes percySnapshot() calls at uncovered touchpoints.

Use the review loop

After setup, the loop runs whenever you or your agent change UI code and open a pull request:

1. Intent: The /percy:visual-intent command drafts what the change is meant to look like from your session, lets you edit it, and writes a Percy visual intent section into the pull request description.
2. Build: A Percy build runs in CI, through /percy:run-build, or manually.
3. Review and gate: The /percy:gate command watches the build, classifies each difference against your intent and code, and enforces the outcome. A clean build becomes a one-line approve, real bugs trigger a fix-and-retry loop, and the plugin escalates ambiguous differences to you. The loop runs up to three times and stops early once the fixes stop reducing the bug count.

If you already have an open pull request with a Percy build, run /percy:gate directly. It backfills intent from your pull request difference and returns a verdict on the existing build in about two minutes, with no rebuild needed.

Understand the gate verdicts

When you run /percy:gate, the plugin gives each visual difference one of the following verdicts. Use this table to read the result and know what happens next:

To decide a verdict, the plugin reconciles Percy’s own analysis of the change with your code and your stated intent. Its strongest signal is code context: if Percy flags a region but no code change touched that surface, the difference is almost certainly dynamic content rather than a regression you introduced.

Run Percy in CI

Local setup is the first step. In regular use, Percy runs in CI, so the token has to be available there too. Make PERCY_TOKEN a CI secret and expose it on the test step. For example, in GitHub, add it under Settings > Secrets > Actions. The /percy:setup command offers to add this to your existing workflow.

On each pull request, the CI build runs the full review loop: intent, build, review, gate, and fix-iterate.

Things to know

In a few situations the plugin cannot trust its signal enough to gate a build. It never auto-rejects in these cases. Use this table to recognize them and know what to do:

Command reference

The plugin adds the following commands to your agent. Most run as part of the setup and review flows above. This table is a quick lookup for all of them, including the utility commands:

Related topics

• Visual review agent
• Visual test integration agent
• AI agents