What Is ProofShot? Visual QA for AI Coding Agents

The 30-Second Answer

ProofShot is a tool that gives AI coding agents eyes. When an AI agent builds a UI — a dashboard, a form, a landing page — it writes the code but never actually sees how it renders. ProofShot closes that gap: it takes a screenshot of the result and sends the image back to the agent, so the agent can look at what it produced and decide if it looks right.

That's the whole idea. It's not complicated in concept. But the problem it solves is genuinely significant, and the approach is clever enough that it hit the front page of Hacker News with 72 points and 55 comments — which, for a small developer tool, is notable signal.

The project lives at github.com/AmElmo/proofshot and is actively maintained. It's early-stage software, but usable and actively discussed by people building with AI coding agents.

The Problem It Solves

To understand why ProofShot matters, you first have to understand a fundamental limitation of how AI coding agents work right now.

An AI coding agent — whether that's Claude Code, Cursor's Composer, or a custom agent you've built — operates entirely through text. It reads code, writes code, runs commands, and reads the output of those commands. All of that is text. The agent is essentially a very capable reader and writer that can also execute terminal commands.

What the agent cannot do is look at a browser window. When it writes a React component or a CSS layout or an HTML page, it has no way of rendering that code and seeing what appears on screen. From the agent's perspective, if the code is valid and contains the right elements, the job is done.

But you've probably already spotted the problem.

Valid code doesn't mean correct output. A button can be off-screen. A grid can collapse into a single column. A modal can render behind another element so it's invisible. Text can overflow its container and get clipped. Colors can be wrong. Spacing can be completely off. An entire section can fail to render because of a missing import that doesn't throw an error.

None of these problems show up in the code itself. They only show up when someone looks at the result in a browser. And right now, "someone" always has to be you — because the agent genuinely cannot see the screen.

How It Works, in Plain English

ProofShot adds a visual feedback step to the agent's normal work loop. Here's the pattern, without any technical jargon:

Step 1: The Agent Builds Something

The agent writes or modifies code — a component, a page, a layout. This is the normal part. The agent does what agents do: it generates code based on your instructions and the existing state of the project.

Step 2: ProofShot Takes a Screenshot

After the agent's code changes are applied, ProofShot uses a headless browser (a browser that runs invisibly in the background, without a window) to render the result and capture a screenshot. Think of it like hiring someone to open the page in Chrome and take a photo of what they see — except it happens automatically and in milliseconds.

The screenshot is taken of the actual rendered output: the pixels on screen after HTML, CSS, and JavaScript have all done their jobs. It's not a preview or an approximation. It's exactly what a human would see if they opened the page themselves.

Step 3: The Screenshot Gets Fed Back to the Agent

This is the key part. The screenshot — as an actual image — gets passed back to the AI model alongside the agent's normal context. Modern AI models are multimodal, meaning they can look at images and reason about what they see. Claude can describe what's in a screenshot. GPT-4o can identify layout problems. They can compare what the code was supposed to produce with what actually appeared.

The agent now has something it's never had before: visual proof of what it built.

Step 4: The Agent Reviews and Corrects

With the screenshot in context, the agent can assess whether the UI looks correct. It can identify obvious problems — elements in the wrong place, broken layouts, missing content, unexpected blank areas — and then make corrections on its own before handing the result back to you.

The loop can run multiple times. Build something, screenshot it, review, fix, screenshot again, verify, done. Each iteration the agent gets tighter. And critically, you're not the one catching all the basic visual bugs anymore — the agent is doing a first pass before you ever look at the screen.

When You Actually Need ProofShot

Not every AI coding task involves a UI, and not every UI task involves visual complexity. Here's where ProofShot earns its place and where it's less relevant.

You Need ProofShot When...

You're building UI-heavy features with an agent. If you're asking Claude Code or Cursor to build an entire dashboard, a settings page, or an onboarding flow, the agent is making many interdependent layout decisions. Without visual verification, any one of those decisions can break the overall layout and the agent won't know it happened.

Your agent keeps producing layouts that look wrong. If you've found yourself repeatedly correcting the same kinds of visual errors — buttons in the wrong place, sections overflowing, responsive layouts breaking on mobile — ProofShot can catch those before they reach you.

You're iterating on visual design with AI assistance. Design iteration is inherently visual. When you're asking an agent to adjust spacing, tweak a color scheme, or rearrange a layout, you need to see each change. ProofShot makes that feedback loop much tighter.

You're using a long-running agentic workflow. If you run an agent on a task and come back 20 minutes later, you want to know the UI it produced actually looks right — not just that the code ran without errors. ProofShot gives you confidence without having to manually check every intermediate state.

You Probably Don't Need ProofShot When...

You're building backend code. APIs, database queries, server-side logic — none of this has a visual output to screenshot. ProofShot is specifically for UI work.

You're making small, targeted changes. If you're changing a single function or adding a field to a form, the visual impact is minimal and easy to verify yourself. ProofShot adds value when the surface area of change is large.

You have strong end-to-end tests already. If your project has comprehensive visual regression tests (tools like Percy or Chromatic), ProofShot is partially redundant. Where it still adds value is in the tighter feedback loop during active development — before you're ready to run the full test suite.

Setting Up ProofShot: A Walkthrough

ProofShot is a developer tool, which means setup involves a terminal. If you're comfortable with that, the process is straightforward. Here's what to expect.

What You'll Need

- Node.js installed (v18 or later recommended)
- A project that renders a UI in the browser
- An AI coding agent setup (Claude Code, Cursor, etc.)
- Basic comfort with running commands in a terminal

Clone and Install

git clone https://github.com/AmElmo/proofshot
cd proofshot
npm install

The install step pulls in the dependencies, including Playwright (which handles the headless browser and screenshot capture). Playwright's first run may also download a browser binary — this is normal and expected.

Configure It for Your Project

ProofShot needs to know where your development server is running — the URL it should navigate to when taking a screenshot. You configure this in a settings file. The README on GitHub covers the specific format, which can vary slightly between versions. The typical setup is pointing it at your local dev server (usually something like http://localhost:3000).

Connect It to Your Agent

This is the step that varies most depending on which AI coding agent you're using. The core idea is the same in all cases: you make ProofShot available as a tool the agent can call, so the agent can trigger a screenshot and receive the image back.

For Claude Code, this typically means exposing ProofShot as an MCP tool — a standardized way for Claude to call external tools. If you're not familiar with MCP yet, the article on What Is an MCP Server explains the concept in plain terms. For other agents, the integration approach depends on that agent's tool-use mechanism.

The GitHub README is the authoritative guide for the current integration approach — check it for the most up-to-date instructions, since ProofShot is under active development and the specifics may change between versions.

Test That It Works

npm run screenshot

# Should output: Screenshot saved to screenshots/output.png
# Open that file to confirm it captured your UI correctly

If the screenshot is a blank page or shows an error, the most common causes are: the dev server isn't running at the configured URL, or the page requires authentication that the headless browser doesn't have. Check the URL config first.

What Can Go Wrong

ProofShot is early-stage software. It works, but there are sharp edges worth knowing about before you rely on it.

The Agent Sees the Screenshot But Misses the Problem

Visual reasoning by AI models is genuinely good but not perfect. An agent looking at a screenshot will catch obvious problems — a blank screen, a layout that's clearly broken, elements stacked incorrectly. It's less reliable at catching subtle issues: slightly off spacing, a color that's close but not quite right, a font that's the wrong weight. ProofShot helps with the gross errors. Fine visual polish still needs human eyes.

Screenshots Don't Capture Interactions

A screenshot is a frozen moment — one state of the UI. It can't show you what happens when you hover over a button, open a dropdown, or submit a form. If an agent builds interactive components, ProofShot can verify the default state but not the interactive states. It's a static check, not a full functional test.

Headless Browser Rendering Can Differ from Real Browsers

In most cases, headless Chromium renders identically to regular Chrome. But there are exceptions: fonts that aren't installed on the system, platform-specific CSS behavior, features that behave differently without a real display. For most UI work this isn't a problem. For pixel-perfect design work, it's worth being aware of.

Setup Is Agent-Specific

There isn't yet a single plug-and-play integration that works for every AI coding agent. Getting ProofShot wired into your specific agent workflow may require reading through GitHub issues and adapting instructions for your setup. If you're using a less common agent or a custom pipeline, budget some time for troubleshooting.

It Adds Latency to the Agent Loop

Each screenshot takes a few seconds — the headless browser has to load the page, wait for rendering, and capture the image. In a tight agent loop making many rapid changes, this adds up. For most use cases this is fine. If you're running an agent that makes dozens of micro-changes in quick succession, you may want to configure ProofShot to screenshot only at specific checkpoints rather than after every change.

Why This Matters Beyond ProofShot

ProofShot is one tool solving one problem. But the problem it's solving points at something much bigger about where AI coding agents are headed.

Right now, AI agents are mostly working blind on anything visual. They can write code fluently, debug logical errors, refactor structure, and navigate large codebases. What they can't do is close the loop between what they wrote and what it looks like. That gap is responsible for a huge amount of friction in AI-assisted UI development: the agent is confident, the code is valid, and the result is still broken.

ProofShot is an early answer to this, and it's working in the right direction. The pattern — give the agent a way to perceive the output it produced, not just the code it wrote — generalizes well beyond screenshots. Future agents might listen to audio output they generated, execute code and observe runtime behavior in real time, or navigate a rendered UI like a user would.

The Hacker News discussion around ProofShot was notable because it surfaced just how widely builders have hit this exact problem. Comment after comment described the same experience: "I've been running the agent in circles on a layout issue because it can't see what's wrong." That's a solved problem now, at least for the cases ProofShot handles.

If you're building seriously with AI coding agents today — especially for frontend or full-stack work — visual feedback loops are going to be part of your toolkit. ProofShot is the earliest version of that.

Frequently Asked Questions

What to Learn Next

ProofShot fits into a broader picture of AI-assisted development and agentic coding workflows. These articles cover the surrounding territory.