imuratalpay/ui-diff
Developer ToolsCompares before/after UI screenshots in a PR, highlights pixel diffs and posts one sticky comment.
This repo is an agent skill pack · 1 skillsSkill list and install →What it does
ui-diff captures before and after screenshots of the UI routes affected by a pull request, runs a pixel diff, and writes a short UX summary as a single sticky PR comment. It ships as an agent skill for Claude Code, Cursor and Codex plus a TypeScript CLI that people and CI can run directly.
Changed files are mapped to routes using ui-diff.config.json, framework routing conventions (Next.js, SvelteKit, Nuxt, Astro, Remix, TanStack Router, plain HTML) and an import graph. The base and head revisions run in temporary git worktrees, and Playwright takes deterministic screenshots with animations settled, fonts awaited, randomness seeded, and repeated captures until stable. pixelmatch highlights changed pixels and composes before | after | diff images, and the agent turns the images and measurements into the UX summary.
Optional flags add variant tables for query parameters, before/after motion clips, a design-token audit, accessibility deltas via axe-core, and support for protected preview URLs.
Quick start
Prerequisites are git and Node.js 20.10+, on macOS/Linux or WSL2 on Windows. gh auth login is only needed for publishing and --pr.
git clone https://github.com/imuratalpay/ui-diff.git ~/src/ui-diff
~/src/ui-diff/install.sh --claude # Cursor reads this too; use --codex for Codex
alias ui-diff='node ~/src/ui-diff/skills/ui-diff/bin/ui-diff.mjs'
cd ~/src/my-app # on your feature branch
ui-diff init # writes ui-diff.config.json: check startCommand and routes
ui-diff run # working tree vs the default branch
The first run builds the skill and downloads Playwright's Chromium (~150 MB). Results land in .ui-diff/: open .ui-diff/comment.local.md for the comment preview and .ui-diff/compare/ for the images. Nothing is posted until you run ui-diff publish --pr <number>. In an agent session you can ask it to run the skill on a PR and update the sticky comment.
For CI, the example workflow runs run and publish on every PR push using the repository's own token; it expects the skill committed into the app repository and skips fork PRs.
Configuration and extras
The config schema covers startCommand, route-to-file mappings, global files, themes, capture masks and a frozen clock. See the full configuration reference and JSON Schema. Optional features are documented in the extras reference.
Privacy and image hosting
Screenshots stay in the same repository: by default publish commits them to an orphan branch ui-diff-assets and links them so only users with read access can view them. The command checks repository visibility and refuses public repositories unless --allow-public-repo is passed. Trade-offs: anyone with read access can open the images, full clones download the current assets snapshot, deleted images may persist in GitHub caches for a while, and GitHub Mobile and email may not render them. Alternatives include a text-only comment, CI artifacts, or a separate private assets repository; details are in the privacy notes.
Constraints
- Requires macOS or Linux, or WSL2 on Windows, plus Node.js 20.10+; the first capture downloads Chromium unless
UI_DIFF_BROWSER_CHANNEL=chromeis set. - Framework apps need a working
startCommandand port binding; servers that only bind IPv6 or block127.0.0.1need thebaseUrlfix described in the troubleshooting guide. - Publishing needs a signed-in
gh; publishing to a public repository is refused by default. - Protected previews take credentials only from environment variables and send them only to the preview origins.
- Licensed under MIT.
Verified example
The repository includes a sample site committed at two revisions. Running ui-diff on those commits produced the exact comment body in the example output: four changed captures across desktop/mobile and light/dark, with the taller button shifting the page down 4px, one new accessibility issue in dark mode, and three new off-token spacing values. The comparison was verified against a local bare remote; no real PR was contacted.
HotRepo's take
On the TypeScript new-project list for 2026-11-21, ui-diff showed 102 stars and 7 forks with a net gain of 2 stars over the recorded one-hour window. That is a small sample, so it does not establish a trend. The technical substance is clearer than the numbers: route detection, deterministic capture, and a single-sticky-comment workflow fit into an existing PR review loop, and keeping screenshots in the same repository is a deliberate design choice rather than a hosted image service. The roadmap items for measured style changes, Figma fidelity checks and design sign-off gates show the project is still early, so treat the current feature set as the scope.
Written by AI from the project's public information and HotRepo's records, updated . The project's own docs are the source of truth.
You might also like
- anthropics/claude-code-security-reviewAI-powered GitHub Action that reviews pull request diffs with Claude for security vulnerabilities and posts findings as PR comments.
- init-co-jp/diff-tourTurns a git diff into a step-by-step guided tour written by an LLM, for engineers who need to understand why a change was made.
- smokeeaasd/flawless-ui-uxA UI/UX guidance skill plus inspection CLI that helps coding agents design, refine, and audit interfaces.
- anthropics/claude-code-actionA GitHub Action that lets Claude answer PR and issue questions and implement code changes.
- DEEIX-AI/WincA Rust-built desktop code editor with fast startup, low memory use, git diffs, and a terminal.