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"`

visual-validation