# Chrome Fleet — Multi-Agent Browser Pool with Shared Login State

> Multi-agent control plane for chrome-devtools-mcp. Two modes: (1) shared main Chrome — N CDP proxies on 9401/9402/9403... all multiplexing onto one logged-in Chrome :9222 so every agent inherits your real cookies/extensions, with focus protection and ID isolation handled by cdp-proxy.mjs; (2) isolated agent Chromes — dedicated Chrome instance per agent on :930N with its own user-data-dir for multi-account / persona-isolation testing. Includes a status tool to inspect the running fleet.

## Install

Merge the JSON below into your `.mcp.json`:

# Chrome Fleet — Multi-Agent Browser Pool with Shared Login State

Run several MCP-driven sub-agents against **one** main Chrome — preserving
your real login state — without focus stealing, ID collisions, or "agents
stomping each other's tabs". This is the multi-agent control plane built on
top of `cdp-proxy.mjs` from the **Chrome MCP Background Proxy** bundle.

## Two modes

### Mode 1: Shared main Chrome (`chrome-fleet.sh`)

```
Agent 1 → CDP Proxy :9401 ─┐
Agent 2 → CDP Proxy :9402 ─┼→ main Chrome :9222 (shared login state)
Agent 3 → CDP Proxy :9403 ─┘
```

Every agent gets its own proxy and its own client-state bucket inside
`cdp-proxy.mjs`, but they all multiplex onto the same Chrome — so all your
existing sessions, cookies, and extensions are available to every agent.

```bash
bash ~/scripts/chrome-fleet.sh start 3   # launches proxies on 9401/9402/9403
bash ~/scripts/chrome-fleet.sh status    # show which proxies are alive
bash ~/scripts/chrome-fleet.sh stop      # stop all proxies (Chrome stays up)
```

`.mcp.json` per agent:

```json
"chrome": {
  "command": "npx",
  "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9401"]
}
```

Bump the port (`9402`, `9403`, …) for each additional agent.

### Mode 2: Isolated agent Chromes (`chrome-agent.sh` / `chrome-agent-status.sh`)

When you actually want **separate** browser profiles per agent (e.g. testing
N independent logins), spin one Chrome instance per agent on its own profile
+ debug port:

```bash
bash ~/scripts/chrome-agent.sh 1   # → Chrome :9301, profile agent-1
bash ~/scripts/chrome-agent.sh 2   # → Chrome :9302, profile agent-2
bash ~/scripts/chrome-agent-status.sh   # list running agent Chromes (9301-9310)
```

Each agent's Chrome window is positioned with a slight offset so you can see
which is which. `.mcp.json` per agent points at its own browser URL.

## When to use which

| Use case | Mode |
|----------|------|
| Multiple agents driving the *same* logged-in user (parallel research, batch automation, social-media operations) | Shared main Chrome |
| Multiple agents simulating *different* users (multi-account testing, persona isolation) | Isolated agent Chromes |
| One agent, one session | Just `chrome-mcp-proxy.sh` from the parent bundle |

## Files

| File | Role |
|------|------|
| `chrome-fleet.sh` | Launch / stop / status for N proxies on `940X` against shared main Chrome `:9222` |
| `chrome-agent.sh <N>` | Boot a dedicated Chrome on `:930N` with profile `~/chrome-profiles/agent-N` |
| `chrome-agent-status.sh` | Show all running agent Chromes (ports 9301–9310) plus the default 9222 |

## Dependencies

- `cdp-proxy.mjs` from the **Chrome MCP Background Proxy** bundle in
  `~/scripts/cdp-proxy.mjs`.
- `chrome-mcp-proxy.sh` if you also want the popup-suppression layer for the
  shared-Chrome mode (`chrome-fleet.sh start` already wires the proxy in).


---
Source: https://tokrepo.com/en/workflows/chrome-fleet-multi-agent-browser-pool-shared-login-state-20bc3ffd
Author: henuwangkai