devtools-fleet-mcp 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,9 @@
+{
+  "name": "pluginslab-devtools-fleet",
+  "version": "1.0.0",
+  "description": "devtools-fleet: chrome-devtools-mcp for ten agents at once",
+  "owner": { "name": "PluginsLab" },
+  "plugins": [
+    { "name": "devtools-fleet", "source": "./", "description": "One isolated Chrome per agent, running Google's chrome-devtools-mcp tools, with saved login states and origin allowlists" }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "devtools-fleet",
+  "version": "0.1.0",
+  "description": "One isolated Chrome per agent, running Google's chrome-devtools-mcp tools, with saved login states and origin allowlists",
+  "author": {
+    "name": "Marcel Schmitz",
+    "url": "https://github.com/pluginslab"
+  },
+  "homepage": "https://github.com/pluginslab/devtools-fleet-mcp",
+  "repository": "https://github.com/pluginslab/devtools-fleet-mcp",
+  "license": "MIT",
+  "mcpServers": {
+    "devtools-fleet": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "devtools-fleet-mcp"
+      ]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [0.1.0] - 2026-10-01
+
+First version, built against `SCOPE.md`.
+
+- One isolated Chrome per agent session, running chrome-devtools-mcp's tools unchanged (`--browserUrl` passthrough).
+- Browsers outlive the MCP connection and are re-adopted by the same client session; a background reaper closes the rest.
+- Saved login states (cookies + localStorage, Playwright storageState format) via `devtools-fleet login`; restore never contacts the site.
+- Per-state origin allowlists, enforced before the call and inside the browser. Strict mode locks the whole network in Chrome itself (dead proxy + bypass list): fetch, WebSockets, WebRTC, workers, also while no agent is connected.
+- No `file:` URLs or file arguments into `~/.devtools-fleet`; no extra browser contexts under an allowlist; client MCP roots passed through to chrome-devtools-mcp.
+- Recovery from Chrome or chrome-devtools-mcp crashes.
+- CLI: `ls`, `show` (live DevTools inspector), `kill`, `gc`, `login`, `states`, `state show|rm|import`, `doctor`, `config`.
+- Claude Code plugin manifest and skill.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PluginsLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,364 @@
+<!-- TODO: banner at assets/banner.jpg, same style as the WordPress trio, then restore:
+<p align="center">
+  <img src="assets/banner.jpg" alt="devtools-fleet-mcp banner" />
+</p>
+-->
+
+**Give every one of your AI agents its own Chrome, running Google's full DevTools toolset, already logged in, and fenced to the sites it should touch.**
+
+## Why This Exists
+
+Google's [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) is the best browser toolset an agent can have when the job is *debugging* a web app: console, network, performance traces, Lighthouse, heap snapshots. It stops working the moment you run more than one agent:
+
+- Agent two starts → `The browser is already running for …`, because every server shares one Chrome profile
+- Switch on `--isolated` → every agent starts logged out and fights the wp-admin, staging or SSO login again, every time
+- The MCP connection drops → the browser, its tabs and its login die with it
+- Ten agents are running → ten invisible headless Chromes. Nothing lists them, nothing cleans up after a crash
+
+Other multi-agent browser tools solve pooling and logins, but on Playwright or through a browser extension. None of them carries Google's DevTools toolset.
+
+## The Solution
+
+`devtools-fleet-mcp` sits in front of chrome-devtools-mcp and manages the browsers. It doesn't reimplement a single browser tool: Google's tools are passed through unchanged, under the same names.
+
+```
+agent session A ─stdio─▶ devtools-fleet-mcp ─▶ chrome-devtools-mcp --browserUrl ─CDP─▶ Chrome A (own profile)
+agent session B ─stdio─▶ devtools-fleet-mcp ─▶ chrome-devtools-mcp --browserUrl ─CDP─▶ Chrome B (own profile)
+                               │
+                               └──▶ ~/.devtools-fleet/  ◀── devtools-fleet CLI: ls, show, kill, gc, login, states
+```
+
+1. **One browser per agent, zero config.** The first browser tool call launches that session's own Chrome. Up to 10 at once by default.
+2. **Browsers outlive the connection.** An agent that reconnects inside the same session gets its browser back, tabs open. A small background reaper closes the browsers nobody comes back for.
+3. **Saved logins.** You log in once, by hand, in a real window (2FA, SSO and captchas are fine). Any number of agents can then start from that login in parallel, each in its own browser.
+4. **Origin allowlists.** A browser started from a saved login can only reach that login's origins. Typed URLs, link clicks, redirects and popups elsewhere are blocked. Strict mode locks the whole network in Chrome itself.
+5. **Recovery.** If Chrome or chrome-devtools-mcp dies, the next tool call brings it back and tells the agent what happened.
+6. **Watch any agent live.** `devtools-fleet show <id>` opens Chrome's DevTools inspector on that agent's page without disturbing it.
+
+## Quick Start
+
+Requires **Node.js 22.12+** and **Google Chrome** (or point `chromePath` at another Chromium build).
+
+### Install as a Claude Code plugin (recommended)
+
+The plugin installs the MCP server **and** a skill that teaches agents the fleet workflow: check `state_list`, start from a saved login, respect the allowlist, recover after a crash.
+
+Inside Claude Code:
+
+```
+/plugin marketplace add pluginslab/devtools-fleet-mcp
+/plugin install devtools-fleet@pluginslab-devtools-fleet
+```
+
+Or from your terminal:
+
+```bash
+claude plugin marketplace add pluginslab/devtools-fleet-mcp
+claude plugin install devtools-fleet@pluginslab-devtools-fleet
+```
+
+Restart Claude Code and check that `devtools-fleet` shows up under `/mcp`.
+
+**Already using chrome-devtools-mcp?** Remove it (`claude mcp remove chrome-devtools`, or disable its plugin). devtools-fleet exposes the same tools under the same names, and two servers with identical tool names confuse agents.
+
+**Updating:** `/plugin marketplace update pluginslab-devtools-fleet`, then restart. The server runs through `npx`, so it picks up new npm releases on its own.
+
+### Install the CLI
+
+The plugin gives agents the MCP tools. Saving logins, watching agents and cleaning up are done by **you**, from the CLI:
+
+```bash
+npm install -g devtools-fleet-mcp
+devtools-fleet doctor
+```
+
+No global install? Every command also works as `npx -p devtools-fleet-mcp devtools-fleet <command>`.
+
+### Other MCP clients
+
+Claude Code without the plugin:
+
+```bash
+claude mcp add devtools-fleet -- npx -y devtools-fleet-mcp
+```
+
+Any other client (`.mcp.json`, Cursor, Claude Desktop, …):
+
+```json
+{
+  "mcpServers": {
+    "devtools-fleet": {
+      "command": "npx",
+      "args": ["-y", "devtools-fleet-mcp"]
+    }
+  }
+}
+```
+
+### First test
+
+Open two Claude Code sessions and ask both:
+
+> "Open http://localhost:3000 and check the console for errors."
+
+Each gets its own Chrome; neither hits the profile lock. Then, in a terminal:
+
+```bash
+devtools-fleet ls
+```
+
+### First saved login
+
+```bash
+devtools-fleet login staging-admin https://staging.example.com/wp-login.php
+```
+
+Log in in the window that opens, come back to the terminal, press Enter, confirm the allowlist. Then ask an agent:
+
+> "Using the staging-admin state, open the Plugins page and run a Lighthouse audit on it."
+
+The agent calls `state_list`, then `browser_start({ state: "staging-admin" })`, and starts already logged in.
+
+## MCP Tools
+
+devtools-fleet adds six tools. Everything else (`navigate_page`, `take_snapshot`, `click`, `evaluate_script`, `list_network_requests`, `performance_start_trace`, `lighthouse_audit`, …) is chrome-devtools-mcp's, with the same names and arguments, so its documentation and skills apply as-is.
+
+### `browser_start`
+
+Starts this session's browser, or picks it up again after a reconnect. Optional: any browser tool starts one with defaults.
+
+```
+→ browser_start({ state: "staging-admin", url: "https://staging.example.com/wp-admin/" })
+← Started: browser 3f9c2a, state "staging-admin", headless, stable
+  allowed origins: https://staging.example.com
+  tabs: https://staging.example.com/wp-admin/
+  uptime 2s
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `state` | string | Saved login to start from |
+| `headless` | boolean | Default from config (`true`) |
+| `viewport` | string | e.g. `"1280x720"` |
+| `channel` | string | `stable`, `beta`, `dev` or `canary` |
+| `url` | string | Open this in the first tab |
+| `allowedOrigins` | string[] | Without a state: restrict this browser voluntarily |
+
+### `browser_status`
+
+This session's browser: id, state, allowlist, mode, open tabs, uptime, blocked requests.
+
+```
+→ browser_status()
+← browser 3f9c2a, state "staging-admin", headless, stable
+  allowed origins: https://staging.example.com
+  tabs: https://staging.example.com/wp-admin/plugins.php
+  uptime 312s, 2 request(s) blocked so far
+```
+
+### `browser_restart`
+
+Relaunches keeping cookies, storage and tabs. `{ headless: false }` gives a visible window, for example so a person can solve a captcha.
+
+```
+→ browser_restart({ headless: false })
+← Restarted with a visible window; reopened 2 tab(s). Page ids have changed: call list_pages.
+```
+
+### `browser_stop`
+
+Closes the browser and deletes its temporary profile.
+
+```
+→ browser_stop()
+← Closed browser 3f9c2a.
+```
+
+### `state_save`
+
+Saves the current browser's login under a name. Parameters: `name`, `allowedOrigins` (defaults to the open tabs' origins), `strict`, `overwrite`. An agent can only narrow its own allowlist, never widen it, and never overwrites a state a person created.
+
+```
+→ state_save({ name: "local-shop" })
+← Saved state "local-shop": 4 cookie(s), localStorage for 1 origin(s). Allowed: http://localhost:3000.
+```
+
+### `state_list`
+
+Saved states with origins, cookie counts and expiry. Never values.
+
+```
+→ state_list()
+← staging-admin: https://staging.example.com | 6 cookies (0 expired) | saved 2026-10-01T09:12:44.512Z by cli
+  local-shop: http://localhost:3000 | 4 cookies (0 expired) | saved 2026-10-01T10:03:10.087Z by agent
+```
+
+## CLI Reference
+
+```bash
+# See every fleet browser: id, status, session, state, mode, current tab
+devtools-fleet ls
+devtools-fleet ls --json
+
+# Watch an agent's browser live in Chrome's DevTools inspector (doesn't disturb it)
+devtools-fleet show 3f9c2a
+devtools-fleet show 3f9c2a --tab 2 --print
+
+# Close browsers
+devtools-fleet kill 3f9c2a
+devtools-fleet kill --all
+
+# Close browsers whose session is gone; --detached also closes ones waiting for a reconnect
+devtools-fleet gc
+devtools-fleet gc --detached
+
+# Log in by hand and save a state
+devtools-fleet login staging-admin https://staging.example.com/wp-login.php
+devtools-fleet login shop http://localhost:3000/login --allow https://cdn.example.com --strict
+
+# Manage states (never prints cookie or storage values)
+devtools-fleet states
+devtools-fleet state show staging-admin
+devtools-fleet state rm staging-admin
+devtools-fleet state import shop ./storageState.json --allow http://localhost:3000
+
+# Check Node, Chrome, permissions and config; print effective config
+devtools-fleet doctor
+devtools-fleet config
+```
+
+Browser statuses: `active` (an agent is connected), `detached` (the connection dropped; waiting for that session to reconnect), `orphan` (the session is gone; closed on the next cleanup), `starting`.
+
+## How It Works
+
+### Process Management
+
+On the first browser tool call, devtools-fleet:
+
+1. **Checks the cap** under a machine-wide lock (`maxBrowsers`, default 10). A full fleet gets a clear error naming the running sessions and `devtools-fleet gc`
+2. **Launches Chrome** itself, on a port it picks, with its own temporary profile
+3. **Restores the state**, if one was asked for: cookies over CDP, `localStorage` through a throwaway tab whose request devtools-fleet answers itself, so the site is never contacted
+4. **Spawns chrome-devtools-mcp** from its own pinned `node_modules` with `--browserUrl`, and re-exports its tool list unchanged
+5. **Registers the browser** in `~/.devtools-fleet/browsers/<id>.json`
+
+When the connection drops, Chrome keeps running. When the same client session reconnects, it finds its browser in the registry and re-adopts it, tabs intact. A reaper process (one per machine, started on demand, gone when idle) closes orphans at once and detached browsers after `orphanTimeoutMinutes`.
+
+### How Sessions Are Recognised
+
+MCP clients start servers through wrappers (`npx`, `npm exec`, `node`, shells) and restart that whole chain on reconnect, while the client session itself (the `claude` process, an editor's extension host) keeps running. devtools-fleet walks up the process tree past the wrappers to that session process. The same session reconnecting finds the same process and gets its browser back; a second session in the same directory finds a different one and never shares.
+
+`DEVTOOLS_FLEET_SESSION=<label>` replaces the lookup with a fixed label, useful in CI or containers.
+
+### Saved Logins
+
+`devtools-fleet login` opens a real Chrome window. You log in, come back to the terminal, press Enter. devtools-fleet proposes an allowlist of where you started and where you ended up. Origins you only passed through, such as an SSO provider, are listed but left out: saving their cookies would hand agents your whole SSO session. Add one with `--allow` if the app really needs it.
+
+What gets saved: cookies and `localStorage` for the allowed origins, in [Playwright's `storageState` format](https://playwright.dev/docs/auth). Playwright loads these files directly, and `state import` takes Playwright or agent-browser files the other way.
+
+Rules that keep states safe to hand to an agent:
+
+- States are only written outside git work trees, with mode `0600` in a `0700` directory.
+- No listing, CLI or MCP, ever shows cookie or storage values.
+- A state is always bound to an allowlist. There is no "use these cookies anywhere" mode.
+
+### The Allowlist
+
+Allowlist entries are full origins:
+
+| Entry | Matches |
+|---|---|
+| `https://app.example.com` | exactly that scheme, host and port |
+| `http://127.0.0.1:3000` | ports matter: `:3001` is a different origin |
+| `https://*.example.com` | any subdomain, not `example.com` itself |
+
+Two layers enforce it:
+
+1. **Argument check.** `new_page` and `navigate_page` are checked before anything reaches the browser; the agent gets a plain error.
+2. **Navigation interception.** devtools-fleet's own CDP connection intercepts navigations in every tab, popup and frame and fails the ones outside the list. A tab that can't be put under interception is closed rather than left unguarded.
+
+A browser with an allowlist also refuses `file:` URLs and extra browser contexts (`new_page`'s `isolatedContext`), since pages there would sit outside the guard.
+
+**Strict mode** (`login --strict`) is enforced by Chrome itself: the browser launches with a proxy that goes nowhere, and only the allowed origins bypass it. Every other request fails in Chrome's network stack: `fetch()`, XHR, beacons, workers, WebSockets, QUIC. WebRTC is pinned to the dead proxy and DNS prefetching is off. The lock holds even while no agent is connected. It's off by default because it also blocks CDNs you haven't listed. At that layer an entry means host and port, so `http` and `https` on the same port aren't told apart there; the navigation guard still tells them apart.
+
+What the allowlist does **not** do:
+
+- It limits *where* the agent goes, not what it does there. On an allowed origin, `evaluate_script` can read anything the page can, including non-httpOnly cookies. Treat a saved login like handing someone your session.
+- Without strict mode, only navigations are guarded, and only while an agent is connected. A detached browser can still be navigated away by a script already running in its pages.
+
+### Files and Paths
+
+chrome-devtools-mcp only reads and writes files (screenshots, traces, uploads) inside the client's workspace roots and the temp directory. devtools-fleet passes your client's roots through, so `take_screenshot({ filePath: "<project>/shot.png" })` works as usual. Nothing may point into `~/.devtools-fleet`: not a `filePath`, not an `upload_file`, not a `file:` URL, symlinks included.
+
+### Data Storage
+
+```
+~/.devtools-fleet/
+  config.json          # Optional configuration (see below)
+  browsers/
+    <id>.json          # One registry entry per running browser
+  profiles/            # Temporary Chrome profiles, deleted on close
+  states/              # Saved logins (0700 dir, 0600 files)
+    <name>.json
+  locks/               # mkdir locks for the cap check and adoption
+```
+
+`DEVTOOLS_FLEET_HOME` moves the whole directory.
+
+## Configuration
+
+`~/.devtools-fleet/config.json`, every key optional. Environment variables override the file.
+
+| Key | Env | Default | |
+|---|---|---|---|
+| `headless` | `DEVTOOLS_FLEET_HEADLESS` | `true` | |
+| `viewport` | `DEVTOOLS_FLEET_VIEWPORT` | none | e.g. `"1280x720"` |
+| `channel` | `DEVTOOLS_FLEET_CHANNEL` | `stable` | |
+| `chromePath` | `DEVTOOLS_FLEET_CHROME_PATH` | detected | |
+| `maxBrowsers` | `DEVTOOLS_FLEET_MAX_BROWSERS` | `10` | across the machine |
+| `orphanTimeoutMinutes` | `DEVTOOLS_FLEET_ORPHAN_TIMEOUT_MINUTES` | `15` | how long a dropped connection's browser waits for a reconnect |
+| `launchTimeoutSeconds` | `DEVTOOLS_FLEET_LAUNCH_TIMEOUT_SECONDS` | `30` | |
+| `upstreamArgs` | | `[]` | extra chrome-devtools-mcp flags |
+| `chromeArgs` | | `[]` | extra Chrome flags, e.g. `["--no-sandbox"]` in containers |
+
+chrome-devtools-mcp collects usage statistics by default and may send performance trace URLs to Google's CrUX API. devtools-fleet keeps its defaults. Opt out with `"upstreamArgs": ["--no-usage-statistics", "--no-performance-crux"]`.
+
+## Limits
+
+- **Tested on macOS and Linux.** Windows should work apart from reconnect re-adoption, but is untested.
+- **Saved logins cover cookies and `localStorage`.** Not IndexedDB, `sessionStorage` or service worker caches.
+- **Sites with device-bound sessions** (Device Bound Session Credentials) won't accept copied cookies.
+- **Google accounts are not supported.** Google blocks automated sign-in and binds sessions to devices.
+- **Headless can't switch to a window in place.** `browser_restart` relaunches, and the pages reload.
+- **The debugging port is local-only but not authenticated,** the same as chrome-devtools-mcp and every CDP tool: other processes running as your user can drive these browsers.
+
+## Companion Tools
+
+devtools-fleet is the *look* step for the [PluginsLab](https://github.com/pluginslab) WordPress MCPs:
+
+| MCP | Purpose |
+|-----|---------|
+| [wp-devdocs-mcp](https://github.com/pluginslab/wp-devdocs-mcp) | Verified hooks/filters/APIs for writing plugin **code** |
+| [wp-blockmarkup-mcp](https://github.com/pluginslab/wp-blockmarkup-mcp) | Verified block schemas for generating **content** |
+| [wp-playground-mcp](https://github.com/pluginslab/wp-playground-mcp) | Ephemeral WordPress instances for **testing** |
+| **devtools-fleet-mcp** (this) | One DevTools-equipped Chrome per agent for **looking** at the result |
+
+Together: **author → validate → test → look**.
+
+## Requirements
+
+- **Node.js 22.12+**
+- **Google Chrome** (stable, beta, dev or canary), or any Chromium via `chromePath`
+- macOS or Linux
+
+## Development
+
+```bash
+npm install
+npm test                 # unit tests, no browser
+npm run test:integration # launches real Chrome; ~1 minute
+npm run lint
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { statSync } from 'node:fs';
+import { PATHS, loadConfig } from '../src/lib/config.js';
+import { listEntries, readEntry, removeEntry, classify } from '../src/lib/registry.js';
+import { isChromeAlive, listPages, inspectorUrl, resolveChromePath } from '../src/lib/chrome.js';
+import { reapOnce, closeEntryBrowser } from '../src/lib/reaper.js';
+import { listStates, readState, summarizeState, deleteState, importState } from '../src/lib/states.js';
+import { login } from '../src/lib/login.js';
+import { UPSTREAM_VERSION } from '../src/lib/upstream.js';
+import { withLock } from '../src/lib/lock.js';
+
+const { version } = createRequire(import.meta.url)('../package.json');
+const program = new Command();
+
+program
+  .name('devtools-fleet')
+  .description('See and manage the Chrome browsers devtools-fleet-mcp runs for your agents, and the login states they use.')
+  .version(`${version} (chrome-devtools-mcp ${UPSTREAM_VERSION})`);
+
+// ------------------------------------------------------------------ browsers
+
+program
+  .command('ls')
+  .description('List every fleet browser')
+  .option('--json', 'machine-readable output')
+  .action(async ({ json }) => {
+    const rows = [];
+    for (const e of listEntries()) {
+      const alive = await isChromeAlive(e);
+      const pages = alive ? await listPages(e).catch(() => []) : [];
+      rows.push({
+        id: e.id,
+        kind: e.kind,
+        status: alive ? classify(e) : 'dead',
+        session: `${e.anchorLabel ?? '?'}${e.anchorPid ? `:${e.anchorPid}` : ''}`,
+        state: e.state ?? null,
+        allowedOrigins: e.allowedOrigins,
+        mode: e.headless ? 'headless' : 'window',
+        tabs: pages.filter((p) => /^https?:/.test(p.url)).map((p) => p.url),
+        cwd: e.cwd,
+        idleSeconds: Math.round((Date.now() - e.lastSeen) / 1000),
+        port: e.port,
+      });
+    }
+    if (json) return console.log(JSON.stringify(rows, null, 2));
+    if (!rows.length) return console.log('No fleet browsers running.');
+    table(rows.map((r) => ({
+      ID: r.id,
+      STATUS: r.status,
+      SESSION: r.session,
+      STATE: r.state ?? '-',
+      MODE: r.mode,
+      TAB: r.tabs[0] ? truncate(r.tabs[0], 50) + (r.tabs.length > 1 ? ` (+${r.tabs.length - 1})` : '') : '-',
+      CWD: truncate(r.cwd ?? '', 40),
+    })));
+  });
+
+program
+  .command('kill')
+  .description('Close fleet browsers')
+  .argument('[ids...]', 'browser ids from `ls`')
+  .option('--all', 'close every fleet browser')
+  .action(async (ids, { all }) => {
+    if (!all && !ids.length) fail('Pass one or more ids, or --all.');
+    const targets = all ? listEntries() : ids.map((id) => readEntry(id) ?? fail(`No browser with id ${id}`));
+    // Deregister under the lock so nothing re-adopts them, then close.
+    const claimed = await withLock('registry', async () => targets.map((t) => readEntry(t.id)).filter(Boolean).map((e) => { removeEntry(e.id); return e; }));
+    for (const e of claimed) {
+      await closeEntryBrowser(e);
+      console.log(`closed ${e.id}${e.chromePid ? '' : ' (it had no Chrome yet)'}`);
+    }
+  });
+
+program
+  .command('gc')
+  .description('Close orphaned browsers now (sessions that ended), and detached ones past the timeout')
+  .option('--detached', 'also close browsers whose MCP connection dropped, without waiting for the timeout')
+  .action(async ({ detached }) => {
+    const config = loadConfig();
+    const actions = await reapOnce({ orphanTimeoutMinutes: config.orphanTimeoutMinutes, closeDetached: detached });
+    if (!actions.length) return console.log('Nothing to clean up.');
+    for (const { id, action } of actions) console.log(`${id}  ${action}`);
+  });
+
+program
+  .command('show')
+  .description("Watch a browser live: opens Chrome's DevTools inspector with a screencast of the page. Doesn't disturb the agent")
+  .argument('<id>', 'browser id from `ls`')
+  .option('--tab <n>', 'which tab (1-based, from the list printed)', (v) => Number(v))
+  .option('--print', 'print the URL instead of opening it')
+  .action(async (id, { tab, print }) => {
+    const e = readEntry(id) ?? fail(`No browser with id ${id}`);
+    if (!(await isChromeAlive(e))) fail(`Browser ${id} is not running.`);
+    const pages = await listPages(e);
+    if (!pages.length) fail(`Browser ${id} has no open tabs.`);
+    pages.forEach((p, i) => console.log(`${i + 1}. ${p.title || '(untitled)'}  ${p.url}`));
+    const index = tab ? tab - 1 : Math.max(0, pages.findIndex((p) => /^https?:/.test(p.url)));
+    const page = pages[index] ?? fail(`No tab ${tab}.`);
+    const url = inspectorUrl(e, page.id);
+    if (print) return console.log(url);
+    console.log(`\nOpening tab ${index + 1} in your default browser:\n${url}`);
+    openInBrowser(url);
+  });
+
+// -------------------------------------------------------------------- states
+
+program
+  .command('login')
+  .description('Open a visible browser, log in by hand, and save the session as a named state agents can use')
+  .argument('<name>', 'state name, e.g. staging-admin')
+  .argument('<url>', 'where to start, e.g. https://staging.example.com/login')
+  .option('--allow <origin...>', 'extra origins the state may be used on (visited origins are added automatically)')
+  .option('--strict', 'when used, block every request outside the allowlist, not just navigations')
+  .option('--overwrite', 'replace an existing state')
+  .option('-y, --yes', 'save without confirming the allowlist')
+  .option('--headless', 'no window (for scripted logins and tests)')
+  .action(async (name, url, opts) => {
+    await login({ name, url, allow: opts.allow ?? [], strict: Boolean(opts.strict), overwrite: Boolean(opts.overwrite), yes: Boolean(opts.yes), headless: Boolean(opts.headless), config: loadConfig() });
+    process.exit(0);
+  });
+
+program
+  .command('states')
+  .description('List saved login states (never shows cookie values)')
+  .option('--json', 'machine-readable output')
+  .action(({ json }) => {
+    const states = listStates();
+    if (json) return console.log(JSON.stringify(states, null, 2));
+    if (!states.length) return console.log('No saved states. Create one with `devtools-fleet login <name> <url>`.');
+    table(states.map((s) => s.error ? { NAME: s.name, ORIGINS: `unreadable: ${s.error}` } : {
+      NAME: s.name,
+      ORIGINS: s.allowedOrigins.join(', ') + (s.strict ? ' [strict]' : ''),
+      COOKIES: `${s.cookies}${s.expiredCookies ? ` (${s.expiredCookies} expired)` : ''}`,
+      SAVED: s.savedAt.slice(0, 16).replace('T', ' '),
+      BY: s.createdBy,
+    }));
+  });
+
+const state = program.command('state').description('Manage one saved state');
+
+state
+  .command('show')
+  .argument('<name>')
+  .description('Metadata for a state (never cookie values)')
+  .action((name) => console.log(JSON.stringify(summarizeState(readState(name)), null, 2)));
+
+state
+  .command('rm')
+  .argument('<name>')
+  .description('Delete a state')
+  .action((name) => {
+    deleteState(name);
+    console.log(`Deleted state "${name}".`);
+  });
+
+state
+  .command('import')
+  .argument('<name>')
+  .argument('<file>', 'a Playwright / agent-browser storageState JSON file')
+  .requiredOption('--allow <origin...>', 'origins the state may be used on')
+  .option('--strict', 'block every request outside the allowlist, not just navigations')
+  .description('Import a storageState file as a fleet state')
+  .action((name, file, { allow, strict }) => {
+    const { summary, droppedCookies } = importState({ name, file, allowedOrigins: allow, strict: Boolean(strict) });
+    console.log(`Imported "${summary.name}": ${summary.cookies} cookie(s)${droppedCookies ? `, ${droppedCookies} dropped (outside the allowlist)` : ''}.`);
+  });
+
+// --------------------------------------------------------------------- misc
+
+program
+  .command('doctor')
+  .description('Check Chrome, Node, permissions and configuration')
+  .action(async () => {
+    let ok = true;
+    const check = (label, fn) => {
+      try {
+        const detail = fn();
+        console.log(`ok    ${label}${detail ? `: ${detail}` : ''}`);
+      } catch (err) {
+        ok = false;
+        console.log(`FAIL  ${label}: ${err.message}`);
+      }
+    };
+    let config;
+    check('config', () => { config = loadConfig(); return PATHS.config; });
+    check('node', () => {
+      const [major, minor] = process.versions.node.split('.').map(Number);
+      if (major < 22 || (major === 22 && minor < 12)) throw new Error(`${process.versions.node}; need 22.12 or newer`);
+      return process.versions.node;
+    });
+    if (config) check(`chrome (${config.channel})`, () => resolveChromePath(config));
+    check('chrome-devtools-mcp', () => UPSTREAM_VERSION);
+    check('fleet home', () => {
+      try {
+        const mode = statSync(PATHS.home).mode & 0o777;
+        if (mode & 0o077) throw new Error(`${PATHS.home} is readable by others (mode ${mode.toString(8)}); run chmod 700`);
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+        return `${PATHS.home} (created on first use)`;
+      }
+      return PATHS.home;
+    });
+    check('states', () => `${listStates().length} saved`);
+    check('browsers', () => `${listEntries().length} registered`);
+    process.exitCode = ok ? 0 : 1;
+  });
+
+program
+  .command('config')
+  .description('Print the effective configuration and where it comes from')
+  .action(() => {
+    console.log(`config file: ${PATHS.config}`);
+    console.log(`fleet home:  ${PATHS.home}`);
+    console.log(JSON.stringify(loadConfig(), null, 2));
+  });
+
+program.parseAsync().catch((err) => fail(err.message));
+
+// -------------------------------------------------------------------- helpers
+
+function fail(message) {
+  console.error(`devtools-fleet: ${message}`);
+  process.exit(1);
+}
+
+function truncate(s, n) {
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
+function table(rows) {
+  const cols = Object.keys(rows[0]);
+  const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? '').length)));
+  const line = (cells) => cells.map((cell, i) => String(cell ?? '').padEnd(widths[i])).join('  ').trimEnd();
+  console.log(line(cols));
+  for (const r of rows) console.log(line(cols.map((c) => r[c])));
+}
+
+function openInBrowser(url) {
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+}