AI 코딩 에이전트에게 시각적 능력을 부여하는 오픈 소스, 에이전트 불가지론적 (agent-agnostic) CLI.

에이전트가 기능을 구축하면 — ProofShot은 그것이 작동한다는 비디오 증거를 기록합니다.

Claude Code · Cursor · Codex · OpenCode · Gemini CLI · Windsurf · GitHub Copilot · 셸 명령어를 실행하는 모든 에이전트와 함께 작동합니다.

AI 코딩 에이전트들은 눈이 먼 상태로 UI 기능을 구축합니다. 코드는 작성하지만, 결과물이 제대로 보이는지, 올바르게 작동하는지, 또는 에러가 발생하지 않는지 검증할 수 없습니다.

ProofShot은 이 루프를 닫습니다: 어떠한 AI 코딩 에이전트에도 연결할 수 있는 오픈 소스 CLI로서 검증 워크플로(verification workflow)를 제공합니다 — 실제 브라우저에서 테스트하고, 비디오 증거를 기록하며, 에러를 수집하고, 사람이 검토할 수 있도록 모든 것을 하나로 묶습니다.

사람은 비디오 녹화본, 주요 순간의 스크린샷, 그리고 발견된 콘솔 또는 서버 에러 보고서를 받게 됩니다. 아티팩트(artifacts)를 로컬에서 확인하거나, proofshot pr을 실행하여 모든 내용을 GitHub PR에 인라인 댓글로 업로드할 수 있습니다. 특정 벤더 종속성(vendor lock-in)이 없으며, 클라우드 의존성도 없습니다.

인터랙티브 뷰어: 스크러브 바(scrub bar), 액션 마커, 단계별 타임라인이 포함된 비디오 녹화

가장 많이 받는 질문: "왜 그냥 Playwright MCP / Chrome DevTools MCP / agent-browser를 직접 사용하지 않나요?"

짧은 답변: 해당 도구들은 브라우저를 제어합니다. ProofShot는 사람이 검토할 수 있도록 증거 아티팩트를 묶어주는 검증 워크플로입니다.

ProofShot은 agent-browser 위에 구축되었습니다. ProofShot은 세션 관리, 서버 로그 캡처, 에러 탐지, 비디오 트리밍, 타임스탬프 동기화, 인터랙티브 뷰어, 그리고 PR 업로드 워크플로를 추가합니다. 브라우저 기본 기능(primitives)은 agent-browser에서 가져오며 — ProofShot은 검증 계층(verification layer) 역할을 합니다.

개발 중 실시간 디버깅(debugging)이나 DOM 검사(inspection)가 필요하다면 Playwright MCP 또는 DevTools MCP를 사용하세요. 몇 초 안에 검토하거나 PR(Pull Request)에 첨부할 수 있는 번들링된 증거 아티팩트(proof artifacts)를 원한다면 ProofShot을 사용하세요.

npm install -g proofshot
proofshot install

첫 번째 명령은 CLI와 agent-browser(headless Chromium 포함)를 설치합니다. 두 번째 명령은 사용자의 AI 코딩 도구들을 감지하고 사용자 레벨에서 ProofShot 스킬(skill)을 설치하며, 모든 프로젝트에서 자동으로 작동합니다.

3단계 워크플로우: start, test, stop.

# 1. Start — 브라우저를 열고, 녹화를 시작하며, 서버 로그를 캡처합니다
proofshot start --run "npm run dev" --port 3000 --description "Login form verification"
# 2. Test — AI 에이전트가 브라우저를 제어합니다
...

스킬 파일은 에이전트에게 이 워크플로우를 자동으로 학습시킵니다. 사용자는 그저 *"proofshot으로 이것을 검증해줘(verify this with proofshot)"*라고 말하기만 하면 에이전트가 나머지를 처리합니다.

각 세션은 ./proofshot-artifacts/ 디렉토리에 타임스탬프가 찍힌 폴더를 생성합니다.

:

단일 검증 세션에 대해 생성된 아티팩트

뷰어에는 콘솔 및 서버 로그를 탐색할 수 있는 탭도 포함되어 있으며, 에러 하이라이팅(highlighting)과 비디오에 동기화된 타임스탬프가 제공됩니다:

에러 하이라이팅과 비디오 동기화 타임스탬프가 포함된 콘솔 로그 탭

머신에 있는 AI 코딩 도구를 감지하고 ProofShot 스킬을 설치합니다. 머신당 한 번만 실행하면 됩니다.

proofshot install # 대화형 도구 선택
proofshot install --only claude # 특정 도구에만 설치
proofshot install --skip cursor # 특정 도구 건너뛰기
...

검증 세션 시작: 브라우저, 녹화, 에러 캡처.

proofshot start # 서버가 이미 실행 중인 경우
proofshot start --run "npm run dev" --port 3000 # 서버를 시작하고 캡처
proofshot start --description "Verify checkout flow" # 보고서에 설명 추가
...

또한 proofshot.config.json에서 브라우저 실행 동작을 설정할 수 있습니다:

{
"browser": {
"configPath": "./agent-browser.local.json",
...

ProofShot이 ~/.agent-browser/config.json을 상속받는 대신 프로젝트별 설정에 따라 agent-browser를 실행해야 할 때 browser.configPath를 설정하세요. 상대 경로는 proofshot.config.json이 포함된 디렉토리를 기준으로 해석됩니다.

녹화 중지, 에러 수집, 증거 아티팩트 (proof artifacts) 생성.

proofshot stop # 세션을 중지하고 브라우저를 닫음
proofshot stop --no-close # 중지하지만 브라우저는 열어둠

자동 세션 로깅과 함께 agent-browser로 전달됩니다. 타임스탬프, 요소 데이터 (element data)를 캡처하고 스크린샷 경로를 해결합니다.

ProofShot 세션이 활성화되어 있는 동안, proofshot exec는 proofshot start가 해당 실행을 위해 생성한 동일한 격리된 agent-browser 세션을 재사용합니다. 이를 통해 스크린샷, 콘솔 로그, 비디오 녹화 및 브라우저 동작이 동일한 브라우저 세션을 가리키도록 유지합니다.

proofshot exec click @e3
proofshot exec screenshot step-checkout.png

시각적 회귀 (visual regression)를 위해 현재 스크린샷을 베이스라인 (baseline)과 비교합니다.

proofshot diff --baseline ./previous-artifacts

세션 아티팩트를 GitHub에 업로드하고 PR에 검증 댓글을 게시합니다. 현재 브랜치에서 기록된 모든 세션을 찾아 스크린샷과 비디오를 업로드하고, 스크린샷이 포함된 서식화된 댓글을 게시합니다.

proofshot pr # 현재 브랜치에서 PR 자동 감지
proofshot pr 42 # 특정 PR 지정
proofshot pr --dry-run # 게시하기 전에 마크다운 미리보기
...

기본적으로 ProofShot은 공식 GitHub 리포지토리 콘텐츠 API를 사용하며 아티팩트를 전용 proofshot-artifacts 브랜치에 업로드합니다. 이는 일반적인 gh 명령과 함께 작동합니다.

인증 (authentication) 및 GH_TOKEN

.

github-web-attachments 프로바이더 (provider)는 여전히 인라인 GitHub 호스팅 미디어에 사용할 수 있지만, GitHub의 내부 웹 업로드 엔드포인트 (endpoint)에 의존하므로 브라우저 기반의 gh auth login OAuth 세션 (sessions)을 거부할 수 있습니다.

ffmpeg를 사용할 수 있는 경우 .webm 비디오를 .mp4로 변환합니다.

./proofshot-artifacts/ 디렉토리 (directory)를 삭제합니다.

proofshot clean

설정 경로 (config path), 브라우저 모드 (browser mode), 뷰포트 (viewport), 설치된 바이너리 (binaries) 및 활성화된 모든 세션 (sessions)을 포함한 현재 ProofShot 환경을 출력합니다.

proofshot doctor

proofshot install

다음 에이전트 (agents)를 위한 스킬 (skills)을 감지하고 구성합니다:

모든 스킬은 **사용자 레벨 (user level)**로 설치되므로, 프로젝트별 설정이 필요하지 않습니다.

이 저장소 (repo)에는 사용자의 프로젝트 없이도 ProofShot가 작동하는 모습을 볼 수 있도록 샘플 앱 (sample apps)이 포함되어 있습니다.

git clone https://github.com/AmElmo/proofshot.git
cd proofshot
npm install && npm run build && npm link
...

test/fixtures/sample-app/ 디렉토리에서 AI 에이전트를 열고 다음과 같이 프롬프트 (prompt)를 입력하세요:

proofshot으로 샘플 앱을 검증해줘. 홈페이지에서 시작해서 히어로 섹션 (hero section)을 확인하고, 대시보드 (Dashboard)로 이동하여 지표 (metrics)를 확인한 다음, 설정 (Settings)으로 가서 프로필 이름을 업데이트해줘. 각 페이지를 스크린샷 (screenshot) 찍어줘.

또는 에이전트 없이 자동화된 테스트 스크립트 (test script)를 실행할 수 있습니다:

bash test-proofshot.sh

비디오, 스크린샷 및 보고서 (report)를 확인하려면 proofshot-artifacts/를 확인하세요.

ProofShot은 10개 이상의 언어(JavaScript/Node.js, Python, Ruby/Rails, Go, Java/Kotlin, Rust, PHP, C#/.NET, Elixir/Phoenix 등)에 걸쳐 서버 로그 (server logs)에서 오류를 자동으로 감지합니다. 새로운 언어를 위한 패턴은 src/utils/error-patterns.ts에 추가할 수 있습니다.

Architecture (아키텍처)— ProofShot이 내부적으로 작동하는 방식, agent-browser를 선택한 이유, 세션 라이프사이클 (session lifecycle), 뷰어 내부 구조 (viewer internals), 그리고 설계 결정 사항에 대해 다룹니다. Test Apps (테스트 앱)— 다양한 UI 패턴(SaaS 대시보드, 칸반 보드, 채팅 인터페이스)에 대해 ProofShot을 엔드 투 엔드 (end-to-end)로 테스트할 수 있도록 바로 사용 가능한 프롬프트가 포함된 세 가지 샘플 앱을 제공합니다.

기여를 환영합니다! 이 프로젝트는 TypeScript (ESM 전용)를 사용하며, 빌드에는 tsup을, 테스트에는 vitest를 사용합니다.

npm install
npm run build # 빌드 (변경 사항 적용 후 필수)
npm test # 테스트 실행
...

test/fixtures/에 있는 세 가지 샘플 앱은 엔드 투 엔드 (end-to-end) 테스트를 위한 다양한 UI 패턴을 다룹니다: SaaS 대시보드(sample-app), 칸반 보드(todo-app), 그리고 채팅 인터페이스(chat-app)입니다.

Vercel의 agent-browser를 기반으로 구축되었습니다.