Multi-agent session isolation for extension/relay mode

[parkerhancock]

Problem

When using dev-browser in extension mode (connecting to the user's existing Chrome browser), multiple Claude Code instances cannot safely share the same relay server. If two agents both create a page named "github", they collide. Events from one agent's pages leak to all connected clients.

This is a real pain point for users running orchestrated multi-agent workflows where sub-agents need browser access to the user's logged-in sessions.

Existing Solutions Don't Cover This

I'm aware of the excellent work in:

• PR feat: add multi-port support for parallel server instances #15 (multi-port support) - Gives each agent its own server/browser
• PR Multi-agent concurrency and external browser mode #24 (multi-agent concurrency) - Dynamic port allocation for external browser mode

Both solve multi-agent for standalone/external browser modes. But for extension mode, where the user wants agents to share their logged-in Chrome browser, there's no solution. Running multiple relay servers doesn't help since the extension can only connect to one relay at a time.

Proposed Solution

Add session-based isolation to the relay server:

Claude Code 1 (session: abc) ──┐
                               ├──► Relay Server ──► Extension ──► User's Chrome
Claude Code 2 (session: xyz) ──┘

Each client gets an auto-generated session ID. Pages are namespaced internally (session:pagename), so two agents can both have a page named "github" without collision. CDP events are routed only to the owning session.

Implementation Highlights

• Backward compatible: No session header = "default" session (existing behavior)
• No extension changes: Session logic is entirely in relay server
• Minimal API change: Optional session parameter in connect()
• Idempotent startup: New start.sh/stop.sh scripts for daemon management

Working Implementation

I have a working implementation at https://github.com/parkerhancock/dev-browser (commit 8b01dba) that I'd be happy to submit as a PR once we align on the approach.

Changes Summary

File	Change
start.sh	New - Idempotent relay startup with PID file
stop.sh	New - Clean relay shutdown
src/client.ts	Add optional session parameter to connect()
src/relay.ts	Session tracking, page namespacing, event routing
SKILL.md	Document multi-agent support
README.md	Document multi-agent support

Test Results

• TypeScript check passes
• Existing tests pass (9/9)
• Manual testing with two Claude Code instances creating same-named pages confirms isolation works

Why Not Just Use PR #24's Approach?

PR #24's multi-agent support works by giving each agent its own server (on a different port) that connects to a shared external browser via CDP. This is great for external browser mode.

But in extension mode, we have a different constraint: the Chrome extension can only maintain one WebSocket connection (to one relay). We can't spawn multiple relay servers because the extension would only connect to one of them.

This solution keeps a single relay server and adds client-side session isolation within that relay. It complements PR #24 rather than competing with it.

[parkerhancock]

Fork Update: Additional Improvements

Since opening this issue, I've continued building out the extension mode functionality in my fork. Here's a summary of additional improvements that might be useful for upstream:

Commits Since Original PR

Commit	Description
b7ca586	Persist page mappings across extension disconnects
6dcd1f9	Add SessionStart hook for automatic session persistence
ffa04f5	Separate ports for standalone (9222) and extension (9224) modes
4a108d7	Fix CDP event routing: pass session in WebSocket URL
648f049	Fix extension mode: enable Page domain on debugger attach
cc0a0a6	Improve extension mode docs
4aa50c9	Multi-agent session isolation (original PR)

Key Improvements

1. Page Mapping Persistence (b7ca586)

Fixed a critical issue where the relay server would lose track of pages after extension disconnects. Pages created via client.page() are now persisted to ~/.dev-browser/pages.json and recovered when the extension reconnects.

• Relay persists {key, targetId, url, lastSeen} on page create/delete
• On extension reconnect, queries available tabs and re-attaches by URL match
• Extension preserves debugger attachments on unexpected disconnect (only detaches on explicit user disable)
• Stale entries auto-cleaned after 7 days

2. SessionStart Hook (6dcd1f9)

Automatic session ID injection for Claude Code users. A hook captures CLAUDE_SESSION_ID at session start and exports it to the environment, so pages persist across script executions within the same Claude Code session.

3. Port Separation (ffa04f5)

Standalone mode (9222) and extension mode (9224) now use separate ports, allowing both to run simultaneously without conflict.

4. CDP Event Routing Fix (4a108d7)

Fixed event routing so CDP events go to the correct session. Events are now routed based on targetToAgentSession mapping rather than being broadcast to all clients.

5. Page Domain Fix (648f049)

Fixed extension mode losing navigation events. The extension now enables Page.enable, Network.enable, and Runtime.enable immediately after attaching the debugger, before Playwright connects.

Testing

All changes pass TypeScript checks and existing tests. Manually tested multi-agent scenarios with session isolation and page recovery across disconnects.

Fork: https://github.com/parkerhancock/dev-browser

Happy to break any of these into separate PRs if there's interest in upstreaming specific improvements.

[parkerhancock]

Implementation Status Update

The session isolation feature proposed in this issue is now fully implemented and tested in our fork. Here's a summary of what's been built:

Core Features (on main)

Multi-Agent Session Isolation

• Each client receives an auto-generated session ID via connect({ session: "my-session" })
• Pages are namespaced internally (sessionId:pageName), preventing collisions
• Backward compatible—omitting session defaults to shared "default" session
• No extension modifications required for basic isolation

Session Persistence

• Page mappings persist across extension disconnects/reconnects
• CDP sessions survive client reconnections (tabs maintain debugger attachment)
• SessionStart hook enables automatic session recovery

Infrastructure

• Separate ports: 9222 (standalone), 9224 (extension/relay)
• Fixed CDP event routing via session parameter in WebSocket URL
• Page domain properly enabled on debugger attach

Additional Feature Branches

Tab Group Isolation (feature/tab-group-isolation)

• Visual separation of agent tabs using Chrome's native tab groups
• Each session gets its own colored, labeled tab group
• Helps users track which tabs belong to which agent

Network Debugging (feature/network-debugging)

• Captures Network.* CDP events per-page
• Search/filter requests by URL, method, status, resource type
• On-demand response body fetching
• HTTP API: GET /pages/:name/network, GET /pages/:name/network/:id/body

Next Steps

Happy to submit these as PRs if there's interest. The features are modular:

1. Core session isolation could be one PR
2. Session persistence as a follow-up
3. Tab group isolation and network debugging as separate features

The fork is at: https://github.com/parkerhancock/dev-browser

Would love feedback on whether this direction aligns with the project's goals.

[parkerhancock]

Virtual CDP Endpoint: Complete Multi-Agent Isolation

We've identified and solved a gap in the session isolation approach. The previous implementation namespaced the /pages HTTP API, but Playwright's CDP target discovery still saw all tabs.

The Problem

When Playwright connects via connectOverCDP(), it calls Target.setAutoAttach and Target.getTargets to discover all browser tabs. Even with session-namespaced page names, Agent B could "see" Agent A's tabs through raw Playwright APIs:

// Agent B could see Agent A's tabs via:
browser.contexts()[0].pages()  // All tabs visible!

The Solution: Virtual CDP Endpoint

Each agent session now gets a filtered view of CDP targets. The relay intercepts and filters key CDP commands:

Command	Behavior
Target.getTargets	Returns only session-owned targets
Target.attachToTarget	Claims unclaimed targets; rejects others'
Target.getTargetInfo	Filtered to owned/unclaimed targets
Target.attachedToTarget events	Only sent to owning session

How It Works

1. When a target is created, it starts "unclaimed"
2. First agent to call Target.attachToTarget claims ownership
3. Subsequent agents cannot see or attach to claimed targets
4. allTargets() intentionally bypasses isolation for tab management

Test Results

# Agent A creates a page
CLAUDE_SESSION_ID=agent-a npx tsx script.ts
# → pages: ['agent-a-page']

# Agent B sees nothing (isolated)
CLAUDE_SESSION_ID=agent-b npx tsx script.ts
# → pages: []  ✅ Isolated!

# allTargets() still shows all (for management)
# → 32 tabs visible  ✅ Bypass works

Implementation

Changes in src/relay.ts:

• Added getSessionTargets() helper to get session's target list
• Updated routeCdpCommand() to accept agentSession parameter
• Filtered all Target.* query commands and events

Commit: parkerhancock@2a3385d

This completes the multi-agent isolation story—agents are now fully isolated at both the HTTP API and CDP protocol levels.