proofshot
- Repo stars 820
- License MIT
- Author repo proofshot
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @AmElmo · MIT
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
This opens a browser and begins recording. If the port is already in use, proofshot will kill the existing process automatically. Always use `--run` to let proofshot start and capture your dev server output (server logs appear in the proof report). Only omit `--run` if the server was explicitly started by the user or another process — without it, no server logs are captured. If a previous session was not stopped cleanly, add `--force` to override it.
Use proofshot exec to navigate, interact, and verify: Take screenshots at important moments — these become the visual proof. Verify what you expect to see by reading the snapshot output.
This stops recording, collects console + server errors, and generates a SUMMARY.md with video, screenshots, and error report.
This uploads screenshots and video to GitHub and posts a formatted comment on the PR. By default it uses the official GitHub contents API on a `proofshot-artifacts` branch. Use `--upload-provider github-web-attachments` if you specifically want GitHub attachment URLs.
# ProofShot — Visual Verification Workflow
ProofShot is an open-source, agent-agnostic CLI that lets you verify your own work in a real browser — video proof, screenshots, and error reports, no vendor lock-in.
## When to use
Use ProofShot after:
- Building a new UI feature or page
- Modifying existing UI components
- Fixing a visual bug
- Any change that affects what the user sees
## The workflow (always follow these 3 steps)
### Step 1: Start the session
```bash
proofshot start --run "your-dev-command" --port PORT --description "what you are about to verify"
```
This opens a browser and begins recording. If the port is already in use, proofshot will kill the existing process automatically.
**Always use `--run`** to let proofshot start and capture your dev server output (server logs appear in the proof report).
Only omit `--run` if the server was explicitly started by the user or another process — without it, no server logs are captured.
If a previous session was not stopped cleanly, add `--force` to override it.
### Step 2: Drive the browser and test
Use proofshot exec to navigate, interact, and verify:
```bash
proofshot exec snapshot -i # See interactive elements
proofshot exec open http://localhost:PORT/page # Navigate to a page
proofshot exec click @e3 # Click a button
proofshot exec fill @e2 "test@example.com" # Fill a form field
proofshot exec screenshot step-NAME.png # Capture key moments
```
Take screenshots at important moments — these become the visual proof.
Verify what you expect to see by reading the snapshot output.
### Step 3: Stop and bundle the proof
```bash
proofshot stop
```
This stops recording, collects console + server errors, and generates
a SUMMARY.md with video, screenshots, and error report.
### Step 4 (optional): Post proof to the PR
```bash
proofshot pr # Auto-detect PR from current branch
proofshot pr 42 # Target a specific PR number
```
This uploads screenshots and video to GitHub and posts a formatted comment on the PR. By default it uses the official GitHub contents API on a `proofshot-artifacts` branch. Use `--upload-provider github-web-attachments` if you specifically want GitHub attachment URLs.
## Tips
- Always include a meaningful --description so the human knows what was tested
- Take screenshots before AND after key actions (e.g., before form submit, after redirect)
- If you find errors during verification, fix them and re-run the workflow
- Use `proofshot pr` after stopping to attach proof directly to the pull request
Listed in source order.
sections -> When to use → The workflow (always follow these 3 steps) → Step 1: Start the session → Step 2: Drive the browser and test → Step 3: Stop and bundle the proof → Step 4 (optional): Post proof to the PR
terms -> Always use --run · This opens a browser and begins recording. · Always use --run to let proofshot start and capture your dev server output (server logs appear in the proof report). · If a previous session was not stopped cleanly, add --force to override it. · Take screenshots at important moments — these become the visual proof. · This stops recording, collects console + server errors, and generates a SUMMARY.md with video, screenshots, and error report. · This uploads screenshots and video to GitHub and posts a formatted comment on the PR.
files/cmd -> --run · --force · proofshot-artifacts · --upload-provider github-web-attachments · proofshot pr
body sha256 -> cce034d21656
When to use
Use ProofShot after: Building a new UI feature or page Modifying existing UI components Fixing a visual bug Any change that affects what the user sees
Step 1: Start the session
This opens a browser and begins recording. If the port is already in use, proofshot will kill the existing process automatically. Always use
--runto let proofshot start and capture your dev server output (server logs appear in the proof report). Only omit--runif the server was explicitly started by the user or another process — without it, no server logs are captured. If a previous session was not stopped cleanly, add--forceto override it.Step 2: Drive the browser and test
Use proofshot exec to navigate, interact, and verify: Take screenshots at important moments — these become the visual proof. Verify what you expect to see by reading the snapshot output.
Step 3: Stop and bundle the proof
This stops recording, collects console + server errors, and generates a SUMMARY.md with video, screenshots, and error report.
Step 4 (optional): Post proof to the PR
This uploads screenshots and video to GitHub and posts a formatted comment on the PR. By default it uses the official GitHub contents API on a
proofshot-artifactsbranch. Use--upload-provider github-web-attachmentsif you specifically want GitHub attachment URLs.