Pursr

pursr

Visual QA, audit, and MCP for the browser. Capture - sweep - diff - audit - repeat - from the CLI, an MCP server, or as a library.

Install · 30 seconds · CLI · MCP · Library · Plugins · Roadmap

---

Why pursr?

Most teams need five separate tools to do visual QA: a screenshot CLI, a regression diff runner, an accessibility auditor, a way to share captures with an AI assistant, and a way to turn all of that into a PDF report for stakeholders. pursr is all five - built as a single Node.js package with:

• A unified CLI (pursr) for every capture, diff, sweep, and audit.
• An agent-grade MCP stdio server (pursr-mcp) built on the official Model Context Protocol SDK, with persistent tabs, direct image responses, rendered-state inspection, actions, diagnostics, screenshots, sweeps, and resources.
• Visual Operator sessions with a rendered cursor, target labels, click markers, visible Chrome windows, and authenticated Chrome attachment over CDP.
• A library API with 25 subpath modules, so you can embed the browser and QA primitives in your own tooling.
• A plugin system for custom viewports, sweep ops, and capture hooks.
• PDF reports + AI diff summaries built in - render a sweep to a styled PDF or ask a vision LLM to describe the regression in plain language.
• Zero browser bundled - drives your system Chrome, Edge, Brave, or Chromium via Playwright. No surprise browser download during install.
• First-run doctor + update notices - diagnose missing browser/runtime pieces and get lightweight release notifications without breaking CI or JSON output.

Install

npm install pursr
npm install --save-dev playwright-core   # peer dep - bring your own Chrome

Then verify:

pursr doctor                    # check Node, playwright-core, browser, and SKILL.md
pursr setup                     # print next steps if anything is missing
pursr viewports                 # list 10+ registered viewport presets
pursr probe https://example.com # health check

Pursr intentionally does not download browsers during npm install. Install Chrome, Edge, Brave, or Chromium yourself, or point Pursr at a Chrome-compatible executable:

# Windows
setx PURSR_BROWSER_PATH "C:\Program Files\Google\Chrome\Application\chrome.exe"

# macOS/Linux
export PURSR_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Browser discovery checks standard global installs, user installs, Dev/Beta/Canary/Nightly channels, and executable names found in PATH across Windows, macOS, and Linux. Current target is Chromium-family browsers; Firefox/WebKit are planned, but not claimed as stable targets yet.

CLI update notifications are cached for 24 hours, written to stderr, and disabled automatically in CI/non-interactive runs. Disable them manually with PURSR_NO_UPDATE_NOTIFIER=1.

30 seconds

# 1. Capture a screenshot with overlays
pursr shoot https://example.com shot.png \
  --preset desktop-1280 --grid --grid-tile 64

# 2. Save it as a visual baseline
pursr baseline save myapp shot.png home --url https://example.com

# 3. Next time you run, compare against the baseline
pursr diff https://example.com \
  ~/.pursr/baselines/myapp//home.png \
  diff.png

# 4. Or: run a batched sweep + a11y audit + parallel workers
pursr sweep ./plan.json   # see plans/ for an example

Features

| Feature | Description | CLI flag | | --- | --- | --- | | Multi-viewport capture | 10+ presets (mobile, tablet, desktop, ultrawide) | --preset mobile-375 | | Layered states | entity / terrain / hud / ui isolation | --layer entity | | Animation freeze | pause CSS/JS animations for stable frames | --no-animation | | Cursor overlay | pointer / grab / grabbing / crosshair | --cursor crosshair | | Visual Operator | rendered cursor, target labels, click markers, WebM recording, headed and CDP sessions | operator CLI + MCP session tools | | Grid overlay | spacing guides, custom color + tile size | --grid --grid-tile 64 | | Camera control | zoom + pan via mouse wheel/drag | --zoom 1.5 --panX 200 | | Frame timeline | N captures at intervalMs for animations | pursr frames 8 200 | | Hover capture | text=/role=/aria=/placeholder= matchers | pursr hover "text=Login" | | Pixel diff | pixelmatch against any reference PNG | pursr diff | | Visual baselines | save / approve / diff with stable IDs | pursr baseline save ... | | Parallel sweep | opt-in worker pool across independent steps | { "parallel": 4 } | | Accessibility audit | axe-core WCAG 2.1 AA + highlighted screenshot | pursr audit | | DOM snapshot | serialized HTML + computed styles + selector map | pursr dom | | Sweep plans | JSON-driven batch with per-step ops | pursr sweep plan.json | | HTML report | dark-themed grid of every capture + meta | auto-generated index.html | | CI output | JUnit XML, GitHub Actions annotations, Markdown | written on every sweep | | Auto-heal selectors | fallback chain + named matchers | ["text=Login", "#login"] | | HAR capture | HAR 1.2 spec, written next to your shot | --har ./req.har.json | | Auth state | Playwright storageState, reuse logged-in sessions | --auth-state admin | | Plugins | custom viewports, sweep ops, before/after hooks | pursr-plugin-* | | MCP server | Official MCP SDK transport, 16 tools, and resources for Claude/Cursor/Codex | npx pursr-mcp | | PDF report | render sweep.json to a styled, embedded-PNG A4 PDF | pursr report --sweep ./sweep.json | | AI diff summary | vision LLM describes the diff in plain language | pursr diff ... --ai |

CLI

# Health check
pursr probe https://example.com

# Screenshot (simple)
pursr shot https://example.com ./out/shot.png

# Rich capture: viewport preset + cursor + grid
pursr shoot https://example.com \
  --preset desktop-1280 \
  --cursor crosshair \
  --grid --grid-tile 64

# Isolate a layer
pursr layer https://example.com entity

# Animation timeline
pursr frames https://example.com 8 200 ./frames/

# Hover an element
pursr hover https://example.com "text=Login"

# Pixel diff vs reference
pursr diff https://example.com ./ref.png ./out/diff.png

# Batched plan
pursr sweep ./plan.json

# Accessibility audit
pursr audit https://example.com --tags wcag2a,wcag2aa

# DOM + selector map snapshot
pursr dom https://example.com

# HAR capture during a shoot
pursr shoot https://example.com shot.png --har ./req.har.json

# Auth state reuse
pursr shoot https://my.app/dashboard shot.png \
  --auth-state admin --auth-project myapp

# Visual baselines
pursr baseline save myapp shot.png home --url https://example.com
pursr baseline list myapp
pursr baseline approve myapp ./new.png home --url https://example.com

# Plan validation
pursr validate ./plan.json

Subcommands

Flags are order-independent. Both commands below are valid, and explicit output paths override Pursr's default output directory:

pursr shot --preset desktop-1280 https://example.com --out ./captures/home.png
pursr full https://example.com --preset desktop-1280 --out-dir ./captures

--out is a complete file path. --out-dir is a directory where Pursr writes the command's standard filename.

| Subcommand | Purpose | | --- | --- | | doctor | Diagnose Node, playwright-core, browser discovery, and packaged skill availability | | setup | Print first-run setup guidance without auto-installing browsers | | probe | Health check (HTTP status, page title) | | shot / full | Viewport / full-page screenshot | | eval | Execute JS in the page, return result | | click / type / wait / seq | Interaction primitives | | operator | Run a visible action plan with cursor feedback, screenshot, trace, diagnostics, and optional WebM video | | diff | Pixel-level diff vs a reference PNG | | viewports | List all registered viewport presets | | shoot | Rich capture (overlays, freeze, camera, plugins) | | layer | Capture one isolated layer (entity/hud/ui/terrain) | | frames | N-frame animation timeline at interval | | hover | Hover state capture | | sweep | Batched capture plan -> HTML report + CI output | | audit | axe-core WCAG accessibility audit + highlighted screenshot | | dom / dom-snapshot | Serialized DOM + CSS selectors + XPath + bounding rects | | every-viewport | Capture once per preset in parallel (3-wide pool) | | baseline | save / list / approve / show visual baselines | | auth | save / load / list / delete Playwright storageState | | validate | Validate a sweep plan JSON without running it |

Agent Skill

The npm package includes [SKILL.md](./SKILL.md), a compact operating guide for coding agents. Point an agent at node_modules/pursr/SKILL.md, or copy it into the skill directory used by your agent host. It explains when to use CLI versus MCP, correct argument order, action plans, visual verification, and safety boundaries.

MCP Server

pursr-mcp exposes every capability as MCP tools over stdio - works with Claude Code, Cursor, Continue, and any MCP host.

npx pursr-mcp
# or with verbose logging:
npx pursr-mcp --verbose

Exposed Tools

| Tool | Description | | --- | --- | | pursr_session_open | Open a headless, visible, or CDP browser session with optional Visual Operator | | pursr_sessions | List active browser sessions | | pursr_snapshot | Visible rendered nodes, geometry, semantics, and computed styles | | pursr_act | Interact plus move cursor, annotate targets, and clear visual feedback | | pursr_screenshot | Return the current PNG directly to the vision model | | pursr_inspect | Inspect exact geometry, computed styles, and stacking ancestors | | pursr_diagnostics | Read console, page errors, failed requests, and HTTP failures | | pursr_session_close | Close the tab and release its browser process | | pursr_shoot | Rich screenshot capture (viewport, grid, layer, cursor, camera, animation freeze, HAR) | | pursr_diff | Pixel-diff a URL against a reference PNG | | pursr_sweep | Execute a batch sweep plan | | pursr_frames | Capture an N-frame animation timeline | | pursr_probe | Health-check a URL | | pursr_audit | axe-core WCAG audit + highlighted screenshot | | pursr_dom_snapshot | Full DOM + selector map snapshot | | pursr_check | CI visual regression check against a stable baseline |

Agent workflow

Use persistent sessions for the same inspect-act-verify loop as an interactive browser agent:

1. Call pursr_session_open once with a stable sessionId.
2. Call pursr_snapshot to understand the rendered page before acting.
3. Use pursr_act for a small, ordered interaction sequence.
4. Call pursr_screenshot when visual judgment matters; the model receives the PNG directly.
5. Use pursr_inspect for layout, clipping, typography, or stacking problems.
6. Read pursr_diagnostics, then reload and verify after source changes.
7. Call pursr_session_close when the review is complete.

Example action arguments:

{
  "sessionId": "farm",
  "actions": [
    { "type": "hover", "selector": "role=button|Build" },
    { "type": "click", "selector": "text=Barn" },
    { "type": "wait", "selector": "role=dialog" }
  ]
}

Visual Operator

Set visual: true to render the agent cursor and interaction feedback into screenshots. mode: "visible" enables it automatically and opens a Chrome window that a developer can watch.

CLI: scripted tutorials and repeatable recordings

Use the CLI when the steps are already known. It needs no MCP host and produces a final screenshot, JSON trace, diagnostics, and an optional WebM recording.

pursr operator http://localhost:3000 @plans/operator-tutorial.json \
  --visible \
  --start-delay 3000 \
  --slow-mo 100 \
  --video ./recordings \
  --out ./recordings/final.png

The action plan is a JSON array. The same action objects work through pursr_act in MCP:

[
  { "type": "annotate", "selector": "role=button|Build", "label": "Open build menu" },
  { "type": "click", "selector": "role=button|Build", "durationMs": 350, "settleMs": 500 },
  { "type": "click", "x": 640, "y": 420, "durationMs": 250 },
  { "type": "drag", "fromX": 520, "fromY": 400, "toX": 760, "toY": 520, "steps": 30 },
  { "type": "keyDown", "key": "Shift" },
  { "type": "keyUp", "key": "Shift" },
  { "type": "press", "key": "Escape" },
  { "type": "sleep", "ms": 800 },
  { "type": "clearAnnotations", "keepCursor": true }
]

Chrome records the browser viewport as silent WebM video. Add narration or system audio in your editor, and convert to MP4 when needed:

ffmpeg -i recording.webm -c:v libx264 -pix_fmt yuv420p tutorial.mp4

MCP: adaptive agent operation

Use MCP when the agent must inspect the current page, decide the next action, verify visual results, or pause for human approval. MCP is not required for CLI recording. Both interfaces use the same session and Visual Operator engine.

{
  "url": "http://localhost:3000",
  "sessionId": "visual-review",
  "mode": "visible",
  "operatorColor": "#ff2ea6",
  "slowMo": 80
}

Add recordVideoDir to record an MCP session in headless or visible mode. The final video path is returned by pursr_session_close. CDP sessions preserve an existing browser profile but cannot record video because Chrome owns that context.

Visual actions use the regular pursr_act tool:

{
  "sessionId": "visual-review",
  "actions": [
    { "type": "move", "x": 640, "y": 360, "durationMs": 300 },
    { "type": "annotate", "selector": "role=button|Publish", "label": "Primary CTA" },
    { "type": "click", "selector": "role=button|Publish" },
    { "type": "clearAnnotations", "keepCursor": true }
  ]
}

To use an existing authenticated Chrome profile, start Chrome with a dedicated remote-debugging profile and attach using CDP. Do not expose the debugging port beyond localhost.

chrome --remote-debugging-port=9222 --user-data-dir=/tmp/pursr-chrome

{
  "url": "https://app.example.com",
  "sessionId": "signed-in-review",
  "mode": "cdp",
  "cdpUrl": "http://127.0.0.1:9222",
  "visual": true
}

Pursr opens a new tab in Chrome's default context, preserving that profile's cookies and login state. Closing the Pursr session disconnects without terminating the owner browser.

Exposed Resources

| URI | Description | | --- | --- | | pursr://shoot/ | Last screenshot PNG (image/png) | | pursr://sweep/ | Last sweep summary JSON (application/json) |

Resources are persisted to ~/.pursr/mcp/mcp-index.json (override with PURSR_MCP_STATE).

Visual Regression Baselines

pursr baseline save myapp ./out/shoot.png home --url https://my.app
pursr baseline approve myapp ./out/shoot.png home --url https://my.app
pursr baseline list myapp
pursr baseline show myapp home --url https://my.app

Baselines live under ~/.pursr/baselines///.png + manifest.json. Override with PURSR_BASELINES_DIR. The id is a 16-char SHA1 prefix of url|viewport|flags so re-running a sweep maps to the same slot deterministically.

import { diffKey, saveBaseline, loadBaseline } from "pursr/baseline";
const id = diffKey({ url: "https://my.app", viewport: { width: 1280, height: 800, dpr: 1 }, flags: { preset: "desktop-1280" } });
saveBaseline({ project: "myapp", id, step: "home", png: "./shot.png", meta: { url: "https://my.app" } });

Sweep Plan Validation

pursr validate ./plan.json
# { "valid": false, "errors": ["steps[2].frames.count: must be a number between 1 and 120"] }

Catches: empty steps, unknown ops, out-of-range numbers, duplicate names, missing required fields. pursr sweep runs the same validator before executing - fail-fast.

{
  "name": "homepage-matrix",
  "base": "https://example.com",
  "parallel": 4,
  "steps": [
    { "name": "baseline",   "shoot":  { "p

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [0xheycat](https://github.com/0xheycat)
- **Source:** [0xheycat/pursr](https://github.com/0xheycat/pursr)
- **License:** MIT
- **Homepage:** https://pursr.xyz/

Install and usage instructions live in the source repository linked above.