Persistent Puppeteer browser on your desktop for visual debugging. Claude uses it to screenshot pages, inspect JS errors, evaluate expressions, and iterate on web visualizations. Every pup API call (screenshot, eval, reload, navigate) is logged to the Timeline tab automatically.

Screenshots

JS Errors

Reloads

Total Events

What is Pup Debug?

A persistent Puppeteer-controlled Chrome browser running on your Windows desktop (port 8851). Claude uses it to visually verify web output — taking screenshots, checking for JavaScript errors, and evaluating expressions in real-time. The browser stays open between commands so 3D tiles, maps, and animations remain loaded.

The visible browser window on your desktop is the Pup Debug instance. It's never headless by default — you can see exactly what Claude sees.

How It Works

1. Launch — Claude opens a visible Chrome browser on your desktop via Puppeteer
2. Navigate — Points the browser at a development URL (e.g., your local server)
3. Debug Loop — Claude edits code, reloads the page, takes screenshots, checks for JS errors, and iterates
4. Evaluate — Runs JS expressions in the page context for state inspection
5. Stay Open — Browser persists between commands; 3D tiles and state stay loaded

Connection Details

Server: localhost:8851
Status: Ready — events log pup API traffic
Browser: —
Page: —

Live Updates

This widget receives events in real-time as Claude interacts with the Puppeteer browser. Screenshots appear with dimension badges showing they've been resized for Claude's vision (max 1568px). JS errors, page reloads, and navigation events are all logged to the Timeline tab.

All commands are sent via HTTP to the Puppeteer server on localhost:8851. Claude sends these automatically during debug loops via Desktop Conduit. The pup-debug skill triggers this automatically when Claude works on visual projects.

Browser Management

POST /launch

Launch browser and navigate to a URL. Responds immediately; browser opens in background. Always visible — never headless unless explicitly requested.

{"url":"http://localhost:8797/","pupshotUrl":"https://coder.../proxy/8797/api/pupshot"}

POST /navigate

Navigate to a new URL in the existing browser. Clears error log.

{"url":"http://localhost:8797/newpage.html"}

POST /reload

Reload the current page. Clears error log. Use after editing code files.

GET /status

Check if browser is connected and page is open. Returns error count and pupshotUrl.

Visual Debugging

GET /screenshot

Take a JPEG screenshot (80% quality). Saves locally on desktop and posts to container's pupshot API for Claude-safe resizing (max 1568px on longest side).

GET /wait?ms=5000

Wait for tiles/animations to settle before screenshotting. Max 30 seconds.

POST /resize

Change browser viewport size. Default is 1920x1080.

{"width":1280,"height":720}

Error & State Inspection

GET /errors

Get all collected console errors and exceptions since last reload. Supports ?since=timestamp filter.

POST /clear-errors

Clear the error log manually.

POST /eval

Evaluate a JavaScript expression in the page context. Returns the result. Great for inspecting state without console.log.

{"expr":"document.title"} {"expr":"viewer.camera.positionCartographic"}

Debug Loop Pattern

1. Edit the source code
2. Reload — POST /reload
3. Wait — GET /wait?ms=5000 (for 3D tiles to settle)
4. Screenshot — GET /screenshot, then Read the resized image
5. Check errors — GET /errors
6. Analyze screenshot + errors
7. If issues found, go to step 1