PostToolUse hook that catches unintended UI changes by pixel-diffing a just-saved screenshot against its baseline with odiff.
Open the source and read safety notes before installing.
Source-backed facts for citing this resource, derived directly from the registry — also available as plain text for AI assistants.
Decision playbook
Signals are present but mixed. Use the checklist below to confirm the source and operational safety for your environment.
0
78
—
No baseline selected
No major trust-signal divergence detected in the current selection.
Confirm ownership and provenance before trusting install instructions.
Source link availableRequired
Open the canonical repository and verify ownership.
Source provenance statusRequired
Marked as source-backed.
Metadata reviewed
Registry metadata indicates a reviewed listing.
Validate risk disclosures before installation or API wiring.
Safety notes presentRequired
Review the listed safety guidance before running commands.
Privacy notes presentRequired
Review data handling notes before connecting accounts or secrets.
Trust level risk gateRequired
Trust level does not block evaluation.
Check package metadata and artifact integrity signals.
Install payload available
Install or copy payload is available for review.
Package verification flag
No package verification flag provided.
Checksum metadata
No checksum provided for downloaded artifact.
Use compare context to validate trade-offs before adoption.
Compare tray has multiple entries
Add at least one more entry to compare trust differences.
Baseline comparison available
No baseline peer selected yet.
Diverging trust signals identified
No major trust-signal divergence found.
Setup at a glance
Copy-ready — paste the snippet to get started.
Adoption plan
Current risk score 16/100. Use staged verification before broader rollout.
Validate source and review signals before any execution.
Confirm source provenanceRequired
Source URL/provenance metadata is present.
Confirm metadata review state
Listing has review metadata.
Verify install payload
Install/config payload exists and can be inspected.
Confirm safety, privacy, and package integrity signals.
Review safety notesRequired
Safety notes are present.
Review privacy notesRequired
Privacy notes are present.
Verify package integrity metadata
No package verification/checksum metadata.
Adopt in controlled steps based on the selected plan.
Run in isolated sandbox firstRequired
Use a constrained sandbox and observe behavior across multiple tasks.
Roll out graduallyRequired
Roll out to a small cohort before wider usage.
Set monitoring and fallback
Define rollback path and monitor errors after adoption.
Evidence readiness
Required evidence gates are covered (5/6 signals complete).
Source repository/provenance is listed.
Required in this preset
Review metadata is present.
Required in this preset
Safety notes are present.
Required in this preset
Privacy notes are present.
Optional in this preset
Package integrity metadata is missing.
Optional in this preset
Install payload is available.
Required in this preset
Required evidence gates are covered for this preset.
Decision timeline
5/6 steps complete with no blocking gaps for this preset.
triage
Source/provenance metadata is available.
triage
Review metadata is available.
verify
Safety notes are available.
verify
Privacy notes are available.
verify
Package integrity metadata is missing.
rollout
Install payload is available.
No required blockers for this timeline preset.
Prerequisite readiness
3 prerequisites to line up before setup.
Safety & privacy surface
5 safety and 3 privacy notes across 4 risk areas. Review closely: network access.
#!/usr/bin/env bash
set -u
# Claude Code PostToolUse hook. Pixel-diffs a just-saved screenshot against its
# baseline using odiff and reports a visual regression. Advisory only - it
# always exits 0, never overwrites the screenshot or baseline - and fails open
# when jq or odiff is unavailable.
command -v jq >/dev/null 2>&1 || exit 0
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
project_root=${CLAUDE_PROJECT_DIR:-$(pwd -P)}
project_root=$(cd -P -- "$project_root" 2>/dev/null && pwd -P) || exit 0
resolve_project_file() {
path=$1
case "$path" in
/*) abs=$path ;;
*) abs=$project_root/$path ;;
esac
[ -f "$abs" ] || return 1
[ ! -L "$abs" ] || return 1
parent=$(dirname "$abs")
name=$(basename "$abs")
parent_real=$(cd -P -- "$parent" 2>/dev/null && pwd -P) || return 1
resolved=$parent_real/$name
[ -f "$resolved" ] || return 1
[ ! -L "$resolved" ] || return 1
case "$resolved" in
"$project_root"/*) printf '%s\n' "$resolved" ;;
*) return 1 ;;
esac
}
FILE=$(resolve_project_file "$FILE") || exit 0
# Only act on PNG screenshots saved in a visual-test location.
case "$FILE" in
*.png) : ;;
*) exit 0 ;;
esac
case "$FILE" in
*/screenshots/*|*/snapshots/*|*/__snapshots__/*|*/__screenshots__/*|*/visual/*) : ;;
*) exit 0 ;;
esac
dir=$(dirname "$FILE")
base=$(basename "$FILE")
baseline=""
for c in "$dir/baseline/$base" "$dir/baselines/$base" "$dir/__baselines__/$base" "${FILE%.png}.baseline.png"; do
if candidate=$(resolve_project_file "$c"); then
baseline=$candidate
break
fi
done
if [ -z "$baseline" ]; then
echo "Visual regression: no baseline found for $FILE - if this is the intended reference, save it as the baseline." >&2
exit 0
fi
if ! command -v odiff >/dev/null 2>&1; then
echo "Visual regression: install odiff (npm i -g odiff-bin) to diff $base against its baseline." >&2
exit 0
fi
diff_out="${FILE%.png}.diff.png"
case "$diff_out" in
"$project_root"/*) : ;;
*) exit 0 ;;
esac
if [ -e "$diff_out" ] || [ -L "$diff_out" ]; then
echo "Visual regression: refusing to overwrite existing diff output $diff_out; remove it and rerun." >&2
exit 0
fi
tmp_dir=$(mktemp -d "$dir/.visual-regression-diff.XXXXXX") || exit 0
cleanup() { rm -rf "$tmp_dir"; }
trap cleanup EXIT
tmp_diff=$tmp_dir/$base.diff.png
summary=$(odiff "$baseline" "$FILE" "$tmp_diff" 2>&1)
status=$?
if [ "$status" -ne 0 ]; then
echo "Visual regression: $base differs from its baseline." >&2
printf '%s\n' "$summary" | while IFS= read -r line; do
[ -n "$line" ] && echo " $line" >&2
done
if [ -f "$tmp_diff" ] && [ ! -L "$tmp_diff" ] && ln "$tmp_diff" "$diff_out"; then
echo " Review $diff_out; update the baseline only if the change is intended." >&2
else
echo " Diff image was not written because $diff_out already exists or could not be created safely." >&2
fi
fi
exit 0{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/screenshot-visual-regression.sh"
}
]
}
]
}
}screenshots, snapshots, __snapshots__, or visual directory.0, never blocks the write, and never updates the baseline for you.On PostToolUse, the hook resolves the saved file under $CLAUDE_PROJECT_DIR, rejects symlinked inputs, and checks whether the saved file is a screenshot PNG in a visual-test location. It looks for a non-symlinked baseline at baseline/<name>, baselines/<name>, __baselines__/<name>, or <name>.baseline.png, then runs odiff <baseline> <new> <temporary-diff>. odiff exits non-zero when the images differ; the hook then publishes the generated image to a new file.diff.png path only when that path does not already exist, reports the difference, and points at the diff image so the change can be reviewed and the baseline updated only if intended.
mkdir -p .claude/hookstouch .claude/hooks/screenshot-visual-regression.shchmod +x .claude/hooks/screenshot-visual-regression.shnpm i -g odiff-bin.claude/settings.json. Do not add this project-local $CLAUDE_PROJECT_DIR/.claude/hooks/... command to user/global settings (~/.claude/settings.json); global hooks should only point to trusted user-owned scripts outside the project.npm i -g odiff-bin)baseline/, baselines/, __baselines__/, or as name.baseline.png)This configuration is for project settings (.claude/settings.json) only. For user/global settings, point to a trusted script in a user-owned location such as ~/.claude/hooks/ instead of using $CLAUDE_PROJECT_DIR.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/screenshot-visual-regression.sh"
}
]
}
]
}
}
baseline lookup paths adjusted.Show that Screenshot Visual Regression - Claude Code Hook is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.
[](https://heyclau.de/entry/hooks/screenshot-visual-regression)Screenshot Visual Regression - Claude Code Hook side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.
1 trust signal differ across this comparison (Submitter).
| Field | PostToolUse hook that catches unintended UI changes by pixel-diffing a just-saved screenshot against its baseline with odiff. Open dossier | Automated accessibility testing and compliance checking for web applications following WCAG 2.1 and WCAG 2.2 guidelines. This hook automatically runs accessibility scans on HTML files after they are written or edited, using axe-core for comprehensive WCAG compliance testing. Open dossier | PostToolUse hook that compares a just-edited OpenAPI or JSON Schema document against the version committed in git and warns about backward-incompatible drift — removed OpenAPI paths and removed required properties — so breaking API changes are surfaced before they ship. Advisory only; it never blocks the edit. Open dossier | A PostToolUse hook that runs the matching test runner for a changed file's language — Jest or Vitest for JS/TS, pytest for Python, go test, or Maven/Gradle for Java — scoped to the edited file. Open dossier |
|---|---|---|---|---|
| Next steps | ||||
| Trust | ||||
| Review status | ReviewedMaintainer reviewed | ReviewedMaintainer reviewed | ReviewedMaintainer reviewed | ReviewedMaintainer reviewed |
| Package trust | Package not verified | Package not verified | Package not verified | Package not verified |
| Source provenance | Source-backed | Source-backed | Source-backed | Source-backed |
| SubmitterDiffers | techforgeworks | — | jony376 | — |
| Install risk | Review first | Review first | Review first | Review first |
| Notes | Safety ✓ Privacy ✓ | Safety ✓ Privacy ✓ | Safety ✓ Privacy ✓ | Safety ✓ Privacy ✓ |
| Brand | — | — | — | — |
| Category | hooks | hooks | hooks | hooks |
| Source | Source-backed | Source-backed | Source-backed | Source-backed |
| Author | techforgeworks | JSONbored | jony376 | JSONbored |
| Added | 2026-06-04 | 2025-09-19 | 2026-06-04 | 2025-09-16 |
| Platforms | ||||
| Harness | ||||
| Source repo | — | — | — | — |
| Safety notes | ✓Runs after every Write, Edit, and MultiEdit but only acts on PNG files saved under a screenshots, snapshots, or visual directory, and reads the screenshot and its baseline image from disk. Install this project-local command only in project settings (`.claude/settings.json`). Do not place `$CLAUDE_PROJECT_DIR/.claude/hooks/screenshot-visual-regression.sh` in user/global settings, because that would allow each opened project to supply the executed script. When a baseline exists and odiff is installed, it writes a new diff image next to the screenshot (file.diff.png) through a temporary file and non-clobber link, and refuses to overwrite an existing path or follow symlinks; it never deletes or overwrites the screenshot or the baseline. Advisory and always exits 0 - it reports a visual difference but never blocks the write or updates the baseline on its own. Fails open: with no baseline, no odiff, or no jq, it prints a short hint and does nothing else. | ✓Runs automatically on its configured Claude Code hook event and executes shell logic that can read, modify, or delete files in your project (and may run builds, installs, or network calls); review the script and scope it to expected paths before enabling. | ✓Runs after every Write, Edit, and MultiEdit and only inspects JSON files that declare openapi, swagger, a $schema key, or paths. Stays read-only and runs git show to read the committed version; it never edits, stages, or commits anything. Advisory by design and always exits 0, so it never blocks a write even when drift is detected. Uses key-set comparison heuristics for removed paths and required fields, so it catches common breaking changes but is not a full OpenAPI diff. | ✓Runs your project's test command automatically after each edit; tests execute arbitrary project code, so enable this only in a trusted repo and expect it to run frequently. The script invokes whichever runner it detects (npm test, npx vitest, pytest, go test, mvn/gradle); make sure the right one is installed so it does not run an unexpected command. |
| Privacy notes | ✓Reads only local image files (the new screenshot and its baseline); it makes no network calls. Writes one local diff image (file.diff.png) next to the screenshot when a difference is found and the diff path does not already exist; it writes no other logs. File paths and odiff's pixel-difference summary are printed to local hook stderr and may reveal project structure. | ✓Receives Claude Code hook input (session metadata, file paths, and tool output) and reads local project files; review what the script logs or forwards to external services and keep credentials out of its output. | ✓Reads the edited schema file and its committed HEAD version from the local repository only. Prints removed path and required-field names to local hook stderr; it makes no network calls and writes no logs. Path and field names shown in output may reveal internal API surface in your terminal. | ✓Runs locally and prints test output to the hook; that output can include file paths, test names, and any data your tests log. |
| Prerequisites |
| — none listed |
| — none listed |
| Install | | | | |
| Config | | | | |
| Citations | ||||
| Claim | Unclaimed | Unclaimed | Unclaimed | Unclaimed |
Source-backed guides for putting this to work.
Loading live community signals…
A short, calm digest of reviewed Claude resources. Unsubscribe any time.