Multi-Session Browser Server

HTTP server providing isolated browser contexts for multi-agent browser automation. Each session has its own cookies, localStorage, and continuous screencast stream.

When to Use Proactively

Use without being asked when:

• Verifying frontend changes visually
• Debugging UI issues or layout problems
• Scraping or extracting content from web pages
• Testing web features across multiple isolated sessions
• Multiple agents need simultaneous browser access without interference

Key advantage: Sessions are fully isolated. Each agent gets its own browser context with separate cookies, storage, and authentication state.

Session Lifecycle

Keep sessions alive during the conversation. Do not delete a session after a single operation - the user may want to:

• Navigate to additional pages
• Take more screenshots
• Interact with the page further

Only delete sessions when:

• The user explicitly says they're done with the browser
• The conversation/task is clearly complete
• Starting fresh with a new context is needed

Sessions auto-cleanup via server idle timeout, so leaving them is safe.

Prerequisites

Install dependencies once:

cd ${CLAUDE_PLUGIN_ROOT} && npm install

Architecture

Chrome (headless) :9222
       ↓ CDP
browser-server.js :9223
       ↓ HTTP API
   [Agent 1]  [Agent 2]  [Agent 3]
   session-a  session-b  session-c

• Chrome runs on port 9222 with CDP enabled
• Browser server connects to Chrome and exposes HTTP API on port 9223
• Each session creates an isolated browser context via browser.createBrowserContext()
• Continuous screencast keeps the latest frame always ready (~15ms retrieval)

Starting the Server

node ${CLAUDE_PLUGIN_ROOT}/scripts/browser-server.js --headless

Options:

• --headless - Run Chrome without visible window (recommended for agents)
• --profile - Copy default Chrome profile (includes cookies, logins)

The server automatically starts Chrome if not already running. Output:

Starting Chrome on :9222 (headless)...
Connected to Chrome
Browser server running on http://localhost:9223

Keep the server running. It manages sessions for all agents and auto-shuts down after 5 minutes idle.

API Reference

Base URL: http://localhost:9223

Session Management

Create session:

curl -X POST http://localhost:9223/session
# {"id":"abc12345"}

List sessions:

curl http://localhost:9223/sessions
# {"sessions":[{"id":"abc12345","frames":42,"lastFrame":"..."}],"count":1}

Destroy session:

curl -X DELETE http://localhost:9223/session/abc12345
# {"ok":true}

Session Operations

All operations require a valid session ID.

Navigate to URL:

curl -X POST http://localhost:9223/session/abc12345/navigate \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
# {"ok":true,"url":"https://example.com"}

Get cached frame (fast ~15ms):

curl http://localhost:9223/session/abc12345/frame > frame.jpg

Returns JPEG from continuous screencast. Always ready, no rendering delay.

Get full screenshot (accurate ~100ms):

curl http://localhost:9223/session/abc12345/screenshot > screenshot.png

Returns PNG with full resolution. Better for text readability and OCR.

Get session status:

curl http://localhost:9223/session/abc12345/status
# {"id":"abc12345","url":"https://example.com","frames":42,"lastFrame":"...","age":1234}

Server Status

curl http://localhost:9223/status
# {"connected":true,"sessions":3}

Typical Workflows

Single Agent Scraping

Run each command separately. The session ID from step 1 is used in subsequent steps.

# Step 1: Create session - note the ID from response
curl -s -X POST http://localhost:9223/session
# Response: {"id":"abc12345"}

# Step 2: Navigate (replace abc12345 with actual ID)
curl -X POST http://localhost:9223/session/abc12345/navigate \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# Step 3: Get screenshot for visual inspection
curl http://localhost:9223/session/abc12345/screenshot > /tmp/page.png

# Step 4: Clean up when done
curl -X DELETE http://localhost:9223/session/abc12345

Multi-Agent Parallel Testing

Each agent creates its own session. Sessions are isolated - cookies set in one session don't affect others.

# Agent 1: Create session, note the ID
curl -s -X POST http://localhost:9223/session
# Use returned ID for all Agent 1 operations

# Agent 2: Create separate session, note the ID
curl -s -X POST http://localhost:9223/session
# Use returned ID for all Agent 2 operations

# Sessions run simultaneously without interference

Authenticated Sessions

Use --profile to copy your default Chrome profile with existing logins:

node ${CLAUDE_PLUGIN_ROOT}/scripts/browser-server.js --profile --headless

Sessions will have access to cookies from your normal Chrome profile.

Screenshot Strategy

Two methods available with different trade-offs:

Method	Endpoint	Speed	Format	Use Case
Frame	/frame	~15ms	JPEG	Quick visual checks, animations
Screenshot	/screenshot	~100ms	PNG	Text reading, OCR, archiving

Recommendations:

• Use /frame for rapid iteration during development
• Use /screenshot when reading text content or precision matters
• Frame is from screencast (already rendered); screenshot triggers fresh render

Error Handling

"Failed to connect to Chrome after starting it"

• Chrome failed to start
• Check Chrome is installed at expected path
• On macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

"Session not found"

• Session ID invalid or already destroyed
• Create a new session with POST /session

"No frame available yet"

• Page just navigated, screencast hasn't captured yet
• Wait briefly or use /screenshot instead

Performance Notes

• Persistent CDP connection: ~100ms for screenshot vs ~5s with fresh connection (50x faster)
• Continuous screencast: frames always ready, no rendering wait
• Session creation: ~200ms (creates new browser context)
• Memory: each session holds one page; destroy sessions when done

Cleanup

Sessions persist until explicitly destroyed. Always clean up:

# Destroy specific session (replace with actual ID)
curl -X DELETE http://localhost:9223/session/abc12345

# Check remaining sessions
curl http://localhost:9223/sessions

Stop the server with Ctrl+C - it gracefully closes all sessions.