Open-source, agent-agnostic CLI that gives AI coding agents eyes.
Your agent builds a feature — ProofShot records video proof it works.
Works with Claude Code · Cursor · Codex · OpenCode · Gemini CLI · Windsurf · GitHub Copilot · any agent that runs shell commands
AI coding agents build UI features blind. They write code but can't verify the result looks right, works correctly, or throws no errors.
ProofShot closes the loop: an open-source CLI that plugs into any AI coding agent and gives it a verification workflow — test in a real browser, record video proof, collect errors, and bundle everything for the human to review.
The human gets a video recording, screenshots of key moments, and a report of any console or server errors found. View artifacts locally, or run proofshot pr to upload everything to the GitHub PR as an inline comment. No vendor lock-in. No cloud dependency.
The interactive viewer: video recording with scrub bar, action markers, and step-by-step timeline
The #1 question: "Why not just use Playwright MCP / Chrome DevTools MCP / agent-browser directly?"
Short answer: those tools control a browser. ProofShot is a verification workflow that bundles proof artifacts for human review.
| Playwright MCP | DevTools MCP | agent-browser | ProofShot | |
|---|---|---|---|---|
| Browser control | ✅ | ✅ | ✅ | ✅ (via agent-browser) |
| Video recording | ✅ | ❌ | ✅ | ✅ |
| Screenshot capture | ✅ | ✅ | ✅ | ✅ |
| Console error collection | ❌ | ✅ | ✅ | ✅ |
| Dev server log capture | ❌ | ❌ | ❌ | ✅ |
| Error detection (10+ languages) | ❌ | ❌ | ❌ | ✅ |
| Action timeline with timestamps | ❌ | ❌ | ❌ | ✅ |
| Interactive HTML viewer | ❌ | ❌ | ❌ | ✅ |
| Video-synced log playback | ❌ | ❌ | ❌ | ✅ |
PR comment upload (proofshot pr) |
❌ | ❌ | ❌ | ✅ |
Visual diff (proofshot diff) |
❌ | ❌ | ❌ | ✅ |
| Agent-agnostic skill install | ❌ | ❌ | ❌ | ✅ |
| Compact element refs (vs full a11y tree) | ❌ | N/A | ✅ | ✅ |
ProofShot sits on top of agent-browser. It adds session management, server log capture, error detection, video trimming, timestamp synchronization, the interactive viewer, and the PR upload workflow. The browser primitives come from agent-browser — ProofShot is the verification layer.
Use Playwright MCP or DevTools MCP if you want live debugging or DOM inspection during development. Use ProofShot if you want bundled proof artifacts you can review in seconds or attach to a PR.
npm install -g proofshot
proofshot installThe first command installs the CLI and the exact agent-browser 0.34.0 package. agent-browser requires Node 24; managed environments should expose it through a dedicated Node 24 launcher so project servers can continue using their repository runtime (for example, Node 22 from .nvmrc). The second command installs the ProofShot skill at user level.
Starting a dev server with --run also requires lsof on Linux/macOS; Windows uses PowerShell's Get-NetTCPConnection. Run proofshot doctor to verify the listener-inspection prerequisite.
Recording is temporarily supported only on Linux and macOS; see the proofshot start requirements.
Three-step workflow: start, test, stop.
# 1. Start — open browser, begin recording, capture server logs
proofshot start --run "npm run dev" --port 3000 --description "Login form verification"
# 2. Test — the AI agent drives the browser
proofshot exec snapshot -i # See interactive elements
proofshot exec open http://localhost:3000/login # Navigate
proofshot exec fill @e2 "test@example.com" # Fill form
proofshot exec click @e5 # Click submit
proofshot exec assert-visible "#account-home" # Record an expected selector
proofshot exec screenshot step-login.png # Capture proof
# 3. Stop — bundle video + screenshots + errors into proof artifacts
proofshot stopExploratory start / exec / stop sessions remain useful while refining a flow. Once the flow is stable, encode it with stable selectors and run proofshot replay case.json; replay rejects ephemeral @eN references before creating a session and writes the same high-level human instructions into the finalized evidence.
Each session produces a timestamped folder in ./proofshot-artifacts/:
| File | Description |
|---|---|
session.mp4 |
H.264 video recorded directly and finalized at stop |
viewer.html |
Standalone interactive viewer with scrub bar, canonical timeline, and grouped Environment/Browser source tabs |
SUMMARY.md |
Markdown report with errors, screenshots, and video |
step-*.png |
Screenshots captured at key moments |
session-log.json |
Action timeline with timestamps and element data |
evidence.json |
Canonical browser/environment events, incidents, source integrity, and media timing |
verdict.json |
Structured PASS, FAIL, INCOMPLETE, or BLOCKED verdict |
artifact-manifest.json |
Finalized repository/commit/runtime provenance and ordered artifact hashes |
network-summary.json |
Sanitized request method/status/timing/error metadata |
USER_TESTING.md |
High-level instructions generated from a replay case |
Raw agent-browser JSON, HAR, browser-console, and ProofShot-owned server evidence stays under the session's private/ directory with user-only permissions. It is excluded from manifests and publication; only curated media and sanitized summaries are reviewable artifacts.
Generated artifacts for a single verification session
The viewer includes grouped Environment and Browser evidence tabs, with incident highlighting and timed live rows synchronized to the video:
Console logs tab with error highlighting and video-synced timestamps
Detect AI coding tools on your machine and install the ProofShot skill. Run once per machine.
proofshot install # Interactive tool selection
proofshot install --only claude # Only install for specific tools
proofshot install --skip cursor # Skip specific tools
proofshot install --force # Overwrite existing installationsStart a verification session: browser, recording, error capture.
proofshot start # Server already running
proofshot start --run "npm run dev" --port 3000 # Start and capture server
proofshot start --description "Verify checkout flow" # Add description to report
proofshot start --url http://localhost:3000/login # Open specific URL
proofshot start --browser-executable /path/to/chrome # Reuse an exact browser binary
proofshot start --headed # Show browser (debugging)
proofshot start --force # Override a stale session from a previous crashYou can also configure browser launch behavior in proofshot.config.json:
{
"browser": {
"configPath": "./agent-browser.local.json",
"ignoreHttpsErrors": true,
"executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}
}Set browser.configPath for a project-specific agent-browser config. ProofShot validates it, rejects provider/CDP/profile/state/proxy and default JSON-output modes, and copies it into private per-session state. Without this option, ProofShot uses an empty per-session config instead of inheriting user or project agent-browser defaults.
ProofShot rejects inherited AGENT_BROWSER_JSON at session preflight and strips it from every agent-browser subprocess. ProofShot enables JSON only for individual internal calls whose structured output it parses; a global JSON mode would change normal command output and break evidence capture.
ProofShot requires agent-browser 0.34.0, a local Chrome/Chromium executable, an explicit target-domain allowlist, and a fresh isolated session. Cloud providers, shared CDP browsers, persistent profiles/state, and auto-connect are refused. If no runnable browser is found, start prints the exact agent-browser install action. An explicit --browser-executable takes precedence for one run.
--output changes only where evidence is written. Registry-backed control state remains discoverable across processes. Concurrent sessions in one worktree are supported; commands resolve a single live session automatically and require --session <id> when several live sessions match. --force recovers proven stale state only and refuses live processes or lifecycle operations.
Stop recording, collect errors, generate proof artifacts.
proofshot stop # Stop session and close browser
proofshot stop --session ID # Stop one exact session
proofshot stop --no-close # Stop but keep browser openstop is idempotent. With --no-close, ProofShot retains exact ownership metadata after bundling; run a later plain proofshot stop to close that browser without rebuilding the artifacts.
Pass-through to agent-browser with automatic session logging. Captures timestamps, element data, and resolves screenshot paths.
When a ProofShot session is active, proofshot exec reuses the same isolated agent-browser session that proofshot start created for that run. This keeps screenshots, console logs, video recording, and browser actions pointed at the same browser session.
proofshot exec click @e3
proofshot exec --session ID click @e3
proofshot exec assert-visible "#checkout-complete"
proofshot exec screenshot step-checkout.pngFailed assert-visible checks are recorded in session-log.json and contribute to the structured verdict.
Action receipts include sanitized intent, interaction category, timing, outcome, and page context. Synthetic DOM actions make final proof incomplete; they remain useful only for diagnosis.
Run one stabilized use case in a fresh isolated session:
proofshot replay ./proofshot.checkout.jsonThe version 1 JSON case owns a description, start options, ordered agent-browser command arrays, and high-level humanTesting instructions. It must use stable selectors, include assert-visible, and capture a screenshot. ProofShot addresses every action and cleanup operation with the exact returned session ID, writes USER_TESTING.md, and succeeds only when the canonical verdict is PASS.
Compare current screenshots against a baseline for visual regression.
proofshot diff --baseline ./previous-artifactsUpload one finalized, provenance-compatible session to GitHub and post a verification comment. ProofShot validates the target PR head, source state, artifact paths, and hashes before upload; it never combines historical sessions.
proofshot pr # Auto-detect PR from current branch
proofshot pr 42 # Target a specific PR
proofshot pr --session proofshot-2026-08-09_19-00-00
proofshot pr --session checkout-session --session receipt-session
proofshot pr --session proofshot-2026-08-09_19-00-00 --screenshot checkout.png --screenshot receipt.png
proofshot pr --dry-run # Preview the markdown without posting
proofshot pr --upload-provider github-web-attachments # Use GitHub's internal attachment flowBy default, ProofShot uses the official GitHub repository contents API and uploads artifacts to a dedicated proofshot-artifacts branch. This works with normal gh authentication and GH_TOKEN.
Auto-selection succeeds only when exactly one complete PASS or FAIL session matches the PR head. Repeat --session to publish several explicit compatible sessions, and repeat --screenshot to preserve exact artifact selection order. Pre-manifest sessions require both --session and --legacy-session; that opt-in cannot bypass a present or invalid finalized manifest. A partial upload never posts a PR comment.
The github-web-attachments provider is still available for inline GitHub-hosted media, but it relies on GitHub's internal web upload endpoint and may reject browser-based gh auth login OAuth sessions.
Inspect and clean durable recovery records after an interrupted or incomplete cleanup:
proofshot session list
proofshot session clean --session <session-id>
proofshot session clean --allCleanup validates persisted process identities and never widens to a name-, port-, or default-socket kill.
Remove the ./proofshot-artifacts/ directory.
proofshot cleanclean refuses while any matching registry state exists, including stale, starting, stopping, or recovery records. Run proofshot stop or proofshot session clean first so ProofShot does not discard evidence or exact process ownership metadata.
Print the current ProofShot environment, including config path, browser mode, viewport, installed binaries, TCP listener-inspection support, and any active session.
proofshot doctorproofshot install detects and configures skills for:
| Agent | Install location |
|---|---|
| Claude Code | ~/.claude/skills/proofshot/SKILL.md |
| Cursor | ~/.cursor/rules/proofshot.mdc |
| Codex (OpenAI) | ~/.codex/skills/proofshot/SKILL.md |
| OpenCode | ~/.config/opencode/skills/proofshot/SKILL.md |
| Gemini CLI | Appends to ~/.gemini/GEMINI.md |
| Windsurf | Appends to ~/.codeium/windsurf/memories/global_rules.md |
All skills install at user level — no per-project configuration needed.
The repo includes sample apps so you can see ProofShot in action without your own project.
git clone https://github.com/AmElmo/proofshot.git
cd proofshot
npm install && npm run build && npm link
# Set up the sample app
cd test/fixtures/sample-app
npm installOpen your AI agent in the test/fixtures/sample-app/ directory and prompt it:
Verify the sample app with proofshot. Start on the homepage, check the hero section, navigate to the Dashboard and check the metrics, then go to Settings and update the profile name. Screenshot each page.
Or run the automated test script without an agent:
bash test-proofshot.shCheck proofshot-artifacts/ for the video, screenshots, and report.
ProofShot automatically detects errors from server logs across 10+ languages: JavaScript/Node.js, Python, Ruby/Rails, Go, Java/Kotlin, Rust, PHP, C#/.NET, Elixir/Phoenix, and more. Add patterns for new languages in src/utils/error-patterns.ts.
- Architecture — How ProofShot works under the hood, why agent-browser was chosen, the session lifecycle, viewer internals, and design decisions.
- Test Apps — Three sample apps with ready-to-use prompts for testing ProofShot end-to-end across different UI patterns (SaaS dashboard, kanban board, chat interface).
Contributions welcome! The project uses TypeScript (ESM-only) with tsup for builds and vitest for tests.
npm install
npm run build # Build (required after changes)
npm test # Run tests
npm run dev # Watch modeThree sample apps in test/fixtures/ cover different UI patterns for end-to-end testing: a SaaS dashboard (sample-app), a kanban board (todo-app), and a chat interface (chat-app).
Built on agent-browser by Vercel.