AI Agent Integration

peek is designed specifically for AI coding agents that need quick visual verification of the UIs they build. This guide covers patterns for integrating peek into agent workflows.

Core Pattern

The fundamental pattern is simple: snap, read, decide.

# 1. Agent takes a screenshot
path=$(peek snap http://localhost:3000)

# 2. Agent reads the image with its vision capabilities
# (the path is an absolute file path like /tmp/peek/snap_2025-01-15_a3f2c1.png)

# 3. Agent decides what to do next based on what it sees

peek outputs just the file path to stdout. The agent reads the image separately using its vision capabilities. This separation of concerns keeps peek stateless and simple.

Why Stateless Matters

Traditional browser automation (Playwright, Selenium) maintains persistent sessions. For a single agent, that is fine. For multiple agents running in parallel – which is common in modern AI coding workflows – session management becomes a source of collisions and resource contention.

peek avoids this entirely:

  • No sessions to manage – Each peek snap or peek check call is independent
  • Shared browser pool – Multiple agents reuse the same Chrome instance safely via separate pages
  • File-based output – No WebSocket streams or session tokens to juggle

Snap + Check in One Pass

For maximum efficiency, combine screenshot and layout checks in a single call:

peek snap http://localhost:3000 --checks --format json

This returns a JSON object containing both the screenshot path and any layout issues found:

{
  "path": "/tmp/peek/snap_2025-01-15_a3f2c1.png",
  "target": "http://localhost:3000",
  "viewport": { "width": 1280, "height": 720 },
  "timestamp": "2025-01-15T10:30:00.000Z",
  "durationMs": 1200,
  "checks": {
    "url": "http://localhost:3000",
    "viewport": { "width": 1280, "height": 720 },
    "summary": { "passed": 5, "errors": 0, "warnings": 1 },
    "issues": [...]
  }
}

Native App Capture

Agents building native macOS apps can capture application windows directly:

peek snap --app "MyApp" -o /tmp/app.png
peek snap --pid 12345 -o /tmp/window.png

This uses ScreenCaptureKit (no browser involved) and requires screen recording permission on first use.

Dev Server Integration

For agents working on web projects, peek dev handles the full workflow:

# Auto-detect framework, start dev server, run checks on multiple routes
peek dev --routes /,/about,/settings --format json

peek auto-detects the framework (Next.js, SvelteKit, Vite, CRA, Remix, Astro, Nuxt), starts the dev server, waits for hydration when appropriate, and runs layout checks on each route.

Authenticated Pages

For pages behind login, provide a setup script:

// login.ts
export default async (page) => {
  await page.goto('http://localhost:3000/login');
  await page.type('#email', 'user@example.com');
  await page.type('#password', 'password');
  await page.click('button[type="submit"]');
  await page.waitForNavigation();
};
peek snap http://localhost:3000/dashboard --setup ./login.ts

The session cookies from the setup script persist for the duration of the command.

Scene Checks for Game Engines

Agents building game UIs with engines like Bevy or Unity can use the peek scene command to verify entity layouts. The game exports a scene manifest JSON, and peek checks for overlapping entities, out-of-bounds placement, zero-size entities, and off-camera visibility:

peek scene manifest.json --format json

No browser is needed for scene checks – they operate purely on the manifest data.

Performance Considerations

  • First call: ~3.8s (launches Chrome)
  • Subsequent calls: ~0.9s (connects to pooled browser)
  • Use --no-pool sparingly – it forces a fresh Chrome launch every time
  • Use peek clean periodically to remove old screenshots from /tmp/peek/
  • Kill the pool when done with peek pool kill to free resources
Built with Ptero