# ProofShot: giving a coding agent a record of what it built > ProofShot is a CLI that wraps a browser session into a reviewable artefact: a video, screenshots, console and dev server logs, and a markdown report, so a human can check what an AI coding agent actually produced. It sits on top of agent-browser rather than replacing it, and the comparison table in its README is the sharpest statement of what it adds. **AmElmo/proofshot** — Give AI coding agents eyes. Records browser sessions, captures screenshots, collects errors, and bundles proof artifacts — so humans can verify what the agent built. - Repository: https://github.com/AmElmo/proofshot - Stars: 869 · Forks: 51 - Language: TypeScript - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/amelmo-proofshot ## The problem it names The README states it in one paragraph: AI coding agents build UI features blind. They write code but cannot verify that the result looks right, works correctly, or throws no errors. That gap is real and specific. An agent that edits a login form has no way to tell whether the form renders, whether the submit button is wired, or whether the console is full of exceptions, so its report on its own work is a claim rather than a demonstration. ProofShot closes the loop by plugging into any AI coding agent and giving it a verification workflow: test in a real browser, record video proof, collect errors, and bundle everything for the human to review. What the human gets is a video recording, screenshots of the key moments, and a report of any console or server errors found. ## How it differs from a browser control tool The README answers the first question a reader would ask, which is why not just use Playwright MCP, Chrome DevTools MCP or agent-browser directly. The short answer is that those tools control a browser while ProofShot is a verification workflow that bundles proof artefacts for human review. The comparison table then makes it row by row. Browser control, video recording, screenshot capture and console error collection are all available elsewhere. What the table marks as unavailable in the alternatives and present in ProofShot is the part that matters: dev server log capture, error detection across more than ten languages, an action timeline with timestamps, an interactive HTML viewer, video-synced log playback, PR comment upload through proofshot pr, visual diff through proofshot diff, agent-agnostic skill install, and compact element references rather than a full accessibility tree. ProofShot sits on top of agent-browser, which supplies the browser primitives, and ProofShot is the verification layer. ## Install and the skill file Two commands get you set up. ```bash npm install -g proofshot proofshot install ``` The first installs the CLI and agent-browser with headless Chromium. The second detects your AI coding tools and installs the ProofShot skill at user level, so it works across all your projects automatically. The install command itself has options for the automated case, with --only to install for a specific tool, --skip to exclude one, --force to overwrite existing installations, and no arguments for an interactive selection. The skill file is the mechanism that makes the workflow automatic: it teaches the agent the three-step sequence, so the user only has to say verify this with proofshot and the agent handles the rest. The named tools are Claude Code, Cursor, Codex, OpenCode, Gemini CLI, Windsurf and GitHub Copilot, and the claim is that it works with any agent that runs shell commands. ## Start, test, stop The workflow is three steps. Start opens the browser, begins recording and captures server logs. ```bash proofshot start --run "npm run dev" --port 3000 --description "Login form verification" ``` Then the agent drives the browser with agent-browser, taking a snapshot of the interactive elements, navigating, filling a field by element reference, clicking, and capturing a screenshot. ```bash agent-browser snapshot -i agent-browser open http://localhost:3000/login agent-browser fill @e2 "test@example.com" agent-browser click @e5 agent-browser screenshot ./proofshot-artifacts/step-login.png ``` Finally stop bundles the video, the screenshots and the errors into the proof artefacts. ```bash proofshot stop ``` The element references like @e2 and @e5 come from the snapshot step and are the compact reference scheme the comparison table contrasts with a full accessibility tree. ## What lands in the artefacts folder Each session produces a timestamped folder under ./proofshot-artifacts/ and the file list is the feature list. There is session.webm, the video recording of the entire session. There is viewer.html, a standalone interactive viewer with a scrub bar, a timeline, and Console and Server log tabs. There is SUMMARY.md, a markdown report with the errors, the screenshots and the video. There are step-*.png files, the screenshots captured at key moments. There is session-log.json, the action timeline with timestamps and element data. There is server.log, the dev server standard output and standard error, captured when you use --run. And there is console-output.log, the browser console output. The viewer highlights errors and syncs the log timestamps to the video, so the moment a red entry appears in the console is the moment you can scrub to. ## The session start options and the stale session problem The start command has more options than the workflow needs, and they are the ones you reach for when something has gone wrong. The bare form assumes your server is already running. The --run form starts your dev server and captures its output, and --port tells it which port to expect. --description adds a line to the report, --url opens a specific URL rather than the root, and --headed shows the browser, which is the debugging escape hatch. The last two are the interesting ones. --force overrides a stale session left behind by a previous crash, and the existence of that flag is a tell: a recording process that died can leave its session state behind, and the next start would otherwise refuse or attach to the wrong thing. ## Getting the artefacts in front of a reviewer The artefacts are for a human, and there are two routes for them. You can view them locally, using the standalone viewer.html, or run proofshot pr to upload everything to the GitHub pull request as an inline comment. The README is clear about the division of labour with the alternatives: use Playwright MCP or DevTools MCP if you want live debugging or DOM inspection during development, and use ProofShot if you want bundled proof artefacts you can review in seconds or attach to a pull request. The visual diff command, proofshot diff, sits in the same family, and the comparison table marks it as one of the capabilities the alternatives do not have. The design constraint behind all of it is that there is no vendor lock-in and no cloud dependency, so the artefacts are files on disk. ## Where ProofShot is the wrong choice Four limits apply. It depends on agent-browser as a peer dependency and on headless Chromium, so it inherits that project's failure modes and that browser's weight. It records video, which means it records your dev server and whatever data flows through it during the session, so the artefacts are as sensitive as the application you tested, and the README gives no retention or redaction story. It is aimed at user-facing features with a visible result, so a change to a background job or a library API produces a video of nothing happening. And it is a new layer in a stack that already has layers: an agent, an MCP server or agent-browser, and now a recorder and a viewer, and the value comes only from that extra layer being cheaper than re-running the session by hand. ## Conclusion Use ProofShot when an AI coding agent has built a user-facing feature and you need evidence rather than a description of what changed, because the bundled artefact answers whether it looks right and threw errors without you re-running the session yourself. Do not reach for it during development for live debugging, because the README says to use Playwright MCP or DevTools MCP for that. Verify first that agent-browser is available, since ProofShot runs on top of it and lists it as an optional peer dependency, that your agent can be given the ProofShot skill, and that the artefacts are captured somewhere you are willing to store a recording of your own dev server. ## FAQ ### What is ProofShot and what problem does it solve? It is an open source CLI that gives AI coding agents a verification workflow. Agents build UI features without being able to check that the result looks right, works, or throws no errors, and ProofShot records a browser session, captures screenshots, collects console and dev server errors, and bundles the evidence for human review. ### How is ProofShot different from Playwright MCP or DevTools MCP? Those tools control a browser, while ProofShot is a verification workflow that bundles proof artefacts. According to the comparison table, ProofShot adds dev server log capture, error detection across more than ten languages, an action timeline, an interactive HTML viewer, video-synced log playback, PR upload and visual diff. ### How do I install ProofShot? Run npm install -g proofshot, which installs the CLI and agent-browser with headless Chromium, then run proofshot install, which detects your AI coding tools and installs the ProofShot skill at user level so it applies across your projects. ### What files does a ProofShot session produce? A timestamped folder in ./proofshot-artifacts/ containing session.webm, viewer.html, SUMMARY.md, step-*.png screenshots, session-log.json, server.log when --run is used, and console-output.log. ### Does ProofShot need agent-browser? Yes. It sits on top of agent-browser, which supplies the browser primitives, and the package manifest lists agent-browser as an optional peer dependency with a version of 0.1.0 or newer, while a postinstall script attempts to run agent-browser install and prints a note if that does not succeed. ## Sources - [AmElmo/proofshot on GitHub](https://github.com/AmElmo/proofshot) - [Issues](https://github.com/AmElmo/proofshot/issues) - [License: MIT](https://github.com/AmElmo/proofshot/blob/main/LICENSE) - [README](https://github.com/AmElmo/proofshot/blob/main/README.md) - [Releases](https://github.com/AmElmo/proofshot/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/amelmo-proofshot