# Visual Validation

Autonomous screenshot verification, captures, compares, and AI-evaluates UI changes...

- Repository: https://github.com/alinaqi/maggy (710 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-13
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add alinaqi/maggy --skill visual-validation -g -a claude-code -y`
Codex: `npx skills add alinaqi/maggy --skill visual-validation -g -a codex -y`
Cursor: `npx skills add alinaqi/maggy --skill visual-validation -g -a cursor -y`
Gemini CLI: `npx skills add alinaqi/maggy --skill visual-validation -g -a gemini-cli -y`

## Description

Autonomous screenshot verification, captures, compares, and AI-evaluates UI changes for visual regressions

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

```bash
# 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)

```bash
# 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

The rest: https://github.com/alinaqi/maggy/blob/HEAD/skills/visual-validation/SKILL.md