Give Your AI Coding Assistant Eyes: Visual Testing with the PixelEagle CLI and Skill

AI coding assistants change UI code without seeing the result. The code compiles, the tests pass, the agent reports success, and the button is now overlapping the nav bar.

The fix is the same one that works for human developers: a visual feedback loop. Make a change, capture a screenshot, compare it against a baseline, look at what changed. The PixelEagle CLI is a good fit for agents because every step is a shell command with parseable output, exactly the interface coding agents already know how to drive.

The Loop

Here is the whole workflow, in the commands an agent runs:

# 1. Capture screenshots with the project's own tooling (Playwright, engine screenshots, ...)
npx playwright test tests/visual/

# 2. Create a run and upload
RUN_ID=$(pixeleagle new-run --metadata '{"branch": "fix-navbar"}')
pixeleagle upload-screenshots --clean-name $RUN_ID screenshots/*.png

# 3. Compare against the latest main-branch baseline
pixeleagle --format json compare-run $RUN_ID --filter branch:main --wait

The comparison output is machine-readable JSON:

{
  "from": 128,
  "to": 121,
  "unchanged": [{ "name": "settings", "hash": "…" }],
  "new": [],
  "missing": [],
  "diff": [
    { "name": "homepage", "hash": "…", "previous_hash": "…", "diff": { "Done": 0.0124 } }
  ]
}

An agent can read this directly: diff, new, and missing all empty means no visual change; a diff entry means screenshot homepage changed with a difference score of 1.24%. No screen scraping, no vision model required for the pass/fail decision.

Actually Seeing the Diff

Scores tell an agent that something changed; for what changed, PixelEagle can hand over the images themselves. On public projects, the CLI downloads both the screenshot and the computed diff image:

pixeleagle download-diff $RUN_ID --with-run 121 homepage --output /tmp/homepage-diff.png

Modern coding agents are multimodal; Claude Code, for example, can read an image file directly. Feed it the diff image (changed regions highlighted) and the agent can distinguish "the intended button style change" from "the sidebar also moved 12 pixels, which was not intended" and keep iterating until only the intended change remains.

For private projects, image download isn't available; agents rely on the per-screenshot scores and the review URL the CLI prints, and the human reviews the visuals in the web UI.

The Skill: Teaching the Workflow Once

Rather than re-explaining this workflow in every session, install the PixelEagle skill into your project:

mkdir -p .claude/skills/pixel-eagle
curl -fsSL https://raw.githubusercontent.com/vleue/PixelEagle-cli/main/skills/pixel-eagle/SKILL.md \
  -o .claude/skills/pixel-eagle/SKILL.md

The skill teaches the agent the full workflow: which commands exist and their exact flags, how to parse the JSON output (including checking new and missing, not just diff), when to download and inspect diff images, how to interpret difference scores (sub-0.5% on rendered content is often anti-aliasing noise; look before declaring a regression), and the iteration loop for fixing a visual bug. It also carries the guardrails: never fabricate run IDs or scores, keep screenshot names stable, don't burn upload quota re-uploading unchanged sets.

With the skill installed, "check your change didn't break anything visually" becomes a one-line instruction to the agent, and "fix the navbar overlap" becomes a loop the agent runs autonomously: change code, re-capture, re-compare, inspect the diff, repeat until the comparison is clean.

Why This Beats Ad-hoc Screenshotting

Agents can already take one-off screenshots with a browser tool. The difference is the baseline:

• A lone screenshot tells the agent what the page looks like; a comparison against the golden record tells it what changed, including changes it didn't intend, on screens it didn't touch.
• Uploading the full screenshot set catches the classic LLM failure mode where the fix works on the page being edited and breaks two others.
• The agent compares against the exact baseline your pull request will be checked against, so "clean locally" means the PR check will be clean too.
• With NVIDIA ꟻLIP as the project's evaluator, rendering variance between the agent's environment and the baseline environment doesn't produce false alarms that send the agent chasing phantom regressions.

Setup Checklist

1. Create a project on pixel-eagle.com and generate a project token
2. Install the CLI: curl -fsSL https://pixel-eagle.com/install.sh | sh
3. Export PIXEL_EAGLE_TOKEN in the environment the agent works in (never in the prompt)
4. Install the skill into .claude/skills/pixel-eagle/
5. Make sure the project has a screenshot script the agent can run, and a baseline to compare against (a golden record, or runs tagged branch:main from CI)

From there, the agent has what it was missing: a way to check what its change to your UI actually looks like.

Key Takeaways

• LLM coding agents ship UI changes they cannot see; a compare-against-baseline loop closes that gap
• The PixelEagle CLI is agent-friendly by construction: shell commands, stdout run IDs, --format json output
• Downloaded diff images let multimodal agents inspect the changed regions themselves and iterate on unintended changes
• The skill packages the whole workflow (commands, JSON parsing, score interpretation, guardrails) into one installable file
• The agent compares against the same baseline as your CI, so local-clean means PR-clean