browser

name	browser
description	Debug-first browser automation with always-on visibility. Console logs, network requests, and errors captured by default. USE WHEN browser, screenshot, debug web, verify UI, troubleshoot frontend.
version	2.0.0
cluster	browser-automation

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

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: 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 ($BROWSER or default)
status	Session info
restart	Fresh session
stop	Stop session

Server Endpoints

Location: 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 '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.