Browser

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:

# Open URL in user's preferred browser ($BROWSER env var, or system default)
open -a "${BROWSER:-Safari}" "<url>"

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 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 ($BROWSER or default)

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:

1. API returning 500
2. Frontend JS crashing because no data
3. 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

API Reference

CLI Tool

Location: skills/browser/Tools/Browse.ts

Server Endpoints

Location: skills/browser/Tools/BrowserSession.ts

TypeScript API

For complex automation, use the TypeScript API directly:

import { PlaywrightBrowser } from '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.