/visual-validation

name: visual-validation
description: Autonomous screenshot verification — captures, compares, and AI-evaluates UI changes for visual regressions
when-to-use: When a UI or static-asset change needs visual verification before shipping
user-invocable: false
effort: medium

Visual Validation — Autonomous Screenshot Verification

Philosophy

Every UI change should be visually verified before it ships. Peekaboo captures pixel-accurate screenshots. The system compares before/after and flags visual regressions. No manual "looks good to me" — the machine verifies what the machine built.

Autonomous Flow

static/* files modified (detected by auto-review-hook or E2E testkit)
    ↓
peekaboo image --mode screen → ~/.maggy/visual-verify/after-{ts}.png
    ↓
Compare with latest baseline (previous after-*.png)
    ↓
AI evaluation: Gemini Flash analyzes screenshot for visual regressions
    ↓
Report: CLEAN or REGRESSION_DETECTED with specific issues

Quick Commands

# Install
brew install steipete/tap/peekaboo

# Capture full system screenshot
peekaboo image --mode screen --retina --path /tmp/screen.png

# Capture specific window
peekaboo image --mode window --app "Google Chrome" --path /tmp/window.png

# Verify Maggy dashboard after code change
peekaboo image --mode window --app "Google Chrome" --path ~/.maggy/visual-verify/after-$(date -u +%Y%m%d-%H%M%S).png

# Compare two screenshots
ls -la ~/.maggy/visual-verify/after-*.png  # review before/after pairs

Autonomous Verification Flow (Claude Code)

# After making any static/ file change, Claude should:
1. git add maggy/maggy/static/ && git diff --stat HEAD  # check what changed
2. Restart Maggy: lsof -ti :8080 | xargs kill && python3 -m maggy.main &
3. Wait for health: curl -s http://localhost:8080/api/health
4. Capture screenshot: peekaboo image --mode screen --path ~/.maggy/visual-verify/after-$(date -u +%Y%m%d-%H%M%S).png
5. Compare with latest baseline in ~/.maggy/visual-verify/
6. AI evaluation: ~/bin/gemini-api --flash "Analyze this screenshot for visual regressions"
7. Report findings

Maggy Dashboard Verification

# One-shot verification
curl -s http://localhost:8080/api/health && \
peekaboo image --mode screen --path ~/.maggy/visual-verify/verify.png && \
echo "✓ Dashboard verified — screenshot at ~/.maggy/visual-verify/verify.png"

Integration Points

Auto-Review Hook (already wired)

• Detects `static/` changes in git diff
• Auto-captures Peekaboo screenshot
• Saves before/after pairs in `~/.maggy/visual-verify/`

E2E Testkit Plugin

• Visual regression testing as part of `POST /api/testkit/run`
• Compares screenshots against baselines
• Flags pixel differences above threshold

Build-in-Public Plugin

• Peekaboo screenshots replace AI-generated images
• Real product captures for LinkedIn/X posts

When to Use

| Scenario | Command | |----------|---------| | After static/ change | `peekaboo image --mode screen --path ~/.maggy/visual-verify/after.png` | | Before committing UI change | Run verification flow above | | Reviewing dashboard | Screenshot + AI analysis | | Build-in-public post | Auto-captured by plugin | | Cross-browser check | `peekaboo image --mode window --app "Safari"` |