Summary

AmElmo/proofshot addresses the critical gap in AI coding agent development: the inability of agents to visually verify their work. This open-source, agent-agnostic CLI provides AI coding agents with "eyes" by recording browser sessions, capturing screenshots, collecting errors, and bundling all artifacts. This empowers human reviewers to efficiently verify AI-generated features, ensuring correctness and closing the development loop without vendor lock-in or cloud dependency.

How It Works

ProofShot operates on a simple three-step workflow: start, test, and stop. Upon start, it launches a browser, begins video recording, and captures server logs. The AI agent then interacts with the application using commands like agent-browser open or agent-browser fill. Finally, stop bundles the session video, interactive HTML viewer, markdown reports, screenshots, and detailed logs into a timestamped artifact folder. This approach provides auditable proof of agent actions and outcomes, directly addressing the "blindness" of current AI coding agents.

Quick Start & Requirements

Installation involves two steps: npm install -g proofshot to install the CLI globally, followed by proofshot install to detect and configure skills for supported AI coding tools. Prerequisites include Node.js and npm. For full functionality, the GitHub CLI (gh) is required for PR integration, and ffmpeg is recommended for video format conversion. Official documentation on architecture and test apps is available within the repository.

Highlighted Details

• Agent-Agnostic: Seamlessly integrates with Claude Code, Cursor, Codex, Gemini CLI, Windsurf, GitHub Copilot, and any agent capable of running shell commands.
• Comprehensive Artifacts: Generates detailed proof packages including session videos (.webm), an interactive HTML viewer with synced logs, markdown reports, and step-specific screenshots.
• Automated Error Detection: Captures server logs across over 10 languages (e.g., JavaScript, Python, Go, Java, Rust, PHP) and browser console output.
• GitHub Integration: The proofshot pr command automatically uploads artifacts as inline comments to GitHub Pull Requests.

Maintenance & Community

The project is built with TypeScript (ESM-only), utilizing tsup for builds and vitest for tests. The README does not specify notable contributors, sponsorships, or dedicated community channels like Discord or Slack.

Licensing & Compatibility

ProofShot is released under the MIT license, a permissive open-source license that generally allows for commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

While proofshot install automates skill configuration for supported agents, users may need to manually integrate ProofShot commands into custom agent workflows. The effectiveness of error detection relies on the accuracy of provided error patterns, which may require updates for less common languages or specific application frameworks. The project's reliance on agent-browser means its capabilities are also bound by that component.