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 · 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
npm install -g proofshot
proofshot installThe first command installs the CLI and agent-browser (with headless Chromium). The second detects your AI coding tools and installs the ProofShot skill at user level — works across all your projects automatically.
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
agent-browser snapshot -i # See interactive elements
agent-browser open http://localhost:3000/login # Navigate
agent-browser fill @e2 "[email protected]" # Fill form
agent-browser click @e5 # Click submit
agent-browser screenshot ./proofshot-artifacts/step-login.png # Capture proof
# 3. Stop — bundle video + screenshots + errors into proof artifacts
proofshot stopThe skill file teaches the agent this workflow automatically. The user just says "verify this with proofshot" and the agent handles the rest.
Each session produces a timestamped folder in ./proofshot-artifacts/:
| File | Description |
|---|---|
session.webm |
Video recording of the entire session |
viewer.html |
Standalone interactive viewer with scrub bar, timeline, and Console/Server log 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 |
server.log |
Dev server stdout/stderr (when using --run) |
console-output.log |
Browser console output |
Generated artifacts for a single verification session
The viewer also includes tabs for browsing console and server logs, with error highlighting and timestamps synced 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 --headed # Show browser (debugging)
proofshot start --force # Override a stale session from a previous crashStop recording, collect errors, generate proof artifacts.
proofshot stop # Stop session and close browser
proofshot stop --no-close # Stop but keep browser openPass-through to agent-browser with automatic session logging. Captures timestamps, element data, and resolves screenshot paths.
proofshot exec click @e3
proofshot exec screenshot step-checkout.pngCompare current screenshots against a baseline for visual regression.
proofshot diff --baseline ./previous-artifactsUpload session artifacts to GitHub and post a verification comment on the PR. Finds all sessions recorded on the current branch, uploads screenshots and video, and posts a formatted comment with inline media.
proofshot pr # Auto-detect PR from current branch
proofshot pr 42 # Target a specific PR
proofshot pr --dry-run # Preview the markdown without postingRequires the GitHub CLI (gh) to be installed and authenticated. Converts .webm video to .mp4 if ffmpeg is available.
Remove the ./proofshot-artifacts/ directory.
proofshot 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 |
| 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:
Check 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.