Customization

Before executing, check for user customizations at: ~/.claude/skills/CORE/USER/SKILLCUSTOMIZATIONS/Browser/

If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.

Browser v2.0.0 - Debug-First Browser Automation

Debugging visibility by DEFAULT. Console logs, network requests, and errors are always captured. No opt-in required.

Philosophy

Debugging shouldn't be opt-in. Like good logging frameworks - you don't turn on logging when you have a problem, you have it enabled from the start so the data exists when problems occur.

Headless by default. All automation runs in headless mode. When the user says "show me" or wants to see what the assistant is seeing, open the URL in their preferred browser from ~/.claude/skills/CORE/USER/TECHSTACKPREFERENCES.md:

# Open URL in user's preferred browser
open -a "$BROWSER" "<url>"  # BROWSER from tech stack prefs

v2.0.0 Changes:

Session auto-starts on first use (no explicit session start)
Console and network capture always enabled
Diagnostic output included by default
30-minute idle timeout (auto-cleanup)
New primary command: Browse.ts <url> for full diagnostics

Quick Start

# Navigate with full diagnostics (PRIMARY COMMAND)
bun run ~/.claude/skills/Browser/Tools/Browse.ts https://example.com

# Output:
# 📸 Screenshot: /tmp/browse-1704614400.png
# 🔴 Console Errors (2): ...
# 🌐 Failed Requests (1): ...
# 📊 Network: 34 requests | 1.2MB | avg 120ms
# ✅ Page: "Example" loaded successfully

Session auto-starts. No setup needed.

Commands

Primary - Navigate with Diagnostics

bun run Browse.ts <url>

Navigates to URL, takes screenshot, and reports:

Console errors and warnings
Failed network requests (4xx, 5xx)
Network statistics
Page load status

Query Commands

bun run Browse.ts errors      # Console errors only
bun run Browse.ts warnings    # Console warnings only
bun run Browse.ts console     # All console output
bun run Browse.ts network     # All network activity
bun run Browse.ts failed      # Failed requests only (4xx, 5xx)

Interaction Commands

bun run Browse.ts click <selector>           # Click element
bun run Browse.ts fill <selector> <value>    # Fill input
bun run Browse.ts type <selector> <text>     # Type with delay
bun run Browse.ts screenshot [path]          # Take screenshot
bun run Browse.ts navigate <url>             # Navigate without report
bun run Browse.ts eval "<javascript>"        # Execute JavaScript
bun run Browse.ts open <url>                 # Open in user's preferred browser (from tech stack prefs)

Management Commands

bun run Browse.ts status      # Session info
bun run Browse.ts restart     # Fresh session (clears logs)
bun run Browse.ts stop        # Stop session (rarely needed)

Debugging Workflow

Scenario: "Why isn't the user list loading?"

# Step 1: Load the page
$ bun run Browse.ts https://myapp.com/users

📸 Screenshot: /tmp/browse-xxx.png

🔴 Console Errors (1):
   • TypeError: Cannot read property 'map' of undefined

🌐 Failed Requests (1):
   • GET /api/users → 500 Internal Server Error

📊 Network: 23 requests | 847KB | avg 89ms
⚠️ Page: "Users" loaded with issues

Immediately know:

API returning 500
Frontend JS crashing because no data
Specific error location

Step 2: Dig deeper

# Full console output
$ bun run Browse.ts console

# All network activity
$ bun run Browse.ts network

# Just the failures
$ bun run Browse.ts failed

Architecture

Auto-Start Session

First command auto-starts a persistent browser session:

Any command → ensureSession() → Session running?
                                    ├─ Yes → Execute command
                                    └─ No → Start session → Execute command

No explicit session start needed.

Always-On Event Capture

From the moment the browser launches:

Console logs - All console.log, console.error, etc.
Network requests - Every request with headers, timing, size
Network responses - Status codes, response times, sizes
Page errors - Uncaught exceptions, promise rejections

Idle Timeout

Session auto-closes after 30 minutes of inactivity:

No zombie processes
No manual cleanup needed
Restarts automatically on next command

Comparison to v1.x

Aspect	v1.x	v2.0.0
Session management	Manual `session start/stop`	Automatic
Console capture	Only in session mode	Always
Network capture	Only in session mode	Always
Error visibility	Must query explicitly	Default in output
Idle cleanup	Manual stop	Auto 30-min timeout
Primary command	`screenshot <url>`	`<url>` (full diagnostic)

API Reference

CLI Tool

Location: ~/.claude/skills/Browser/Tools/Browse.ts

Command	Description
`<url>`	Navigate with full diagnostics
`errors`	Show console errors
`warnings`	Show console warnings
`console`	Show all console output
`network`	Show network activity
`failed`	Show failed requests
`screenshot [path]`	Take screenshot
`navigate <url>`	Navigate without report
`click <selector>`	Click element
`fill <sel> <val>`	Fill input
`type <sel> <text>`	Type with delay
`eval "<js>"`	Execute JavaScript
`open <url>`	Open in user's preferred browser (tech stack prefs)
`status`	Session info
`restart`	Fresh session
`stop`	Stop session

Server Endpoints

Location: ~/.claude/skills/Browser/Tools/BrowserSession.ts

Endpoint	Method	Description
`/diagnostics`	GET	Full diagnostic summary
`/console`	GET	Console logs
`/network`	GET	Network logs
`/health`	GET	Health check
`/session`	GET	Session info
`/navigate`	POST	Navigate (clears logs)
`/click`	POST	Click element
`/fill`	POST	Fill input
`/screenshot`	POST	Take screenshot
`/evaluate`	POST	Run JavaScript
`/stop`	POST	Stop server

TypeScript API

For complex automation, use the TypeScript API directly:

import { PlaywrightBrowser } from '~/.claude/skills/Browser/index.ts'

const browser = new PlaywrightBrowser()
await browser.launch({ headless: true })
await browser.navigate('https://example.com')

// Get diagnostics
const errors = browser.getConsoleLogs({ type: 'error' })
const failed = browser.getNetworkLogs({ status: [400, 404, 500] })
const stats = browser.getNetworkStats()

await browser.close()

Full API: See index.ts for all methods.

VERIFY Phase Integration

MANDATORY for verifying web changes:

# Before claiming any web change is "live" or "working":
bun run Browse.ts https://example.com/changed-page

# Check the screenshot AND diagnostics
# If errors or failed requests exist, the change is NOT verified

If you haven't LOOKED at the rendered page and its diagnostics, you CANNOT claim it works.