agent-eyes

Agent Eyes

Browser automation toolkit for accessibility audits, screenshots, visual diffs, and DOM inspection.

Prerequisites

Install dependencies before first use:

uv pip install playwright Pillow
playwright install chromium

Browser Connection Modes

1. Connect to Existing Browser (Recommended for interactive work)

Start Chrome with remote debugging:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
chrome.exe --remote-debugging-port=9222

Scripts then connect via --cdp-url http://localhost:9222.

2. Navigate to URL (For automated tasks)

Scripts launch a new browser and navigate to the specified URL. Use --headless for CI/automation.

Workflows

Accessibility Audit

Generate an a11y report for any website:

# Audit URL directly
uv run scripts/a11y_audit.py --url https://example.com

# Audit current page in connected browser
uv run scripts/a11y_audit.py --cdp-url http://localhost:9222

# Custom standards (wcag2a, wcag2aa, wcag21aa, best-practice)
uv run scripts/a11y_audit.py --url https://example.com --standards wcag21aa

Output: a11y-[domain].md with severity levels, affected elements, and remediation links.

Screenshot Capture

# Basic screenshot
uv run scripts/screenshot.py --url https://example.com -o screenshot.png

# Full-page capture
uv run scripts/screenshot.py --url https://example.com --full-page -o full.png

# Screenshot specific element
uv run scripts/screenshot.py --url https://example.com --selector "#hero" -o hero.png

# Custom viewport
uv run scripts/screenshot.py --url https://example.com --width 375 --height 812 -o mobile.png

# From connected browser
uv run scripts/screenshot.py --cdp-url http://localhost:9222 -o current.png

Visual Diff Comparison

Compare two screenshots to detect visual regressions:

# Basic diff (highlights changes in red)
uv run scripts/visual_diff.py --before baseline.png --after current.png -o diff.png

# Side-by-side comparison
uv run scripts/visual_diff.py --before a.png --after b.png --mode side-by-side -o compare.png

# Adjust sensitivity (lower = more sensitive)
uv run scripts/visual_diff.py --before a.png --after b.png --threshold 5 -o diff.png

# JSON output with metrics
uv run scripts/visual_diff.py --before a.png --after b.png --json

Element Picker (Edit Mode)

Interactively select elements to get DOM context:

# Pick from connected browser
uv run scripts/element_picker.py --cdp-url http://localhost:9222

# Pick from URL
uv run scripts/element_picker.py --url https://example.com

# Basic context only
uv run scripts/element_picker.py --cdp-url http://localhost:9222 --context basic

Returns JSON with:

• CSS selector
• Element attributes
• Computed styles
• outerHTML/innerHTML
• Parent chain, siblings, children (extended context)

Browser Info

Get information about the current page:

uv run scripts/browser.py info --cdp-url http://localhost:9222

Common Patterns

A11y Audit Workflow

When user asks "Is this website accessible?" or "Run an a11y audit":

1. Determine target (URL or connected browser)
2. Run a11y_audit.py with appropriate standards
3. Read the generated report
4. Summarize critical/serious issues
5. Provide remediation guidance

Visual Regression Workflow

When comparing before/after changes:

1. Capture baseline: screenshot.py --url [url] -o baseline.png
2. User makes changes
3. Capture current: screenshot.py --url [url] -o current.png
4. Generate diff: visual_diff.py --before baseline.png --after current.png
5. Report findings with diff percentage

DOM Context Workflow

When user needs to modify specific elements:

1. Run element_picker.py to let user select element
2. Use the returned selector and context
3. Provide modification suggestions based on element structure

Script Reference

Error Handling

• "playwright not installed": Run uv pip install playwright && playwright install chromium
• "No browser contexts found": Open a page in the browser before connecting
• "Failed to connect": Ensure browser started with --remote-debugging-port=9222
• "Element not found": Verify selector exists on page