pw-pool

One browser per agent session for the Playwright MCP.

@playwright/mcp assumes one server and one browser. If you run two agent sessions on one machine and they either fail on the profile lock or, with a shared browser, work in the same tab space and navigate each other's pages. pw-pool gives every session its own Chrome and remembers which one is whose.

Profiles

Chrome keeps everything about a "person" in a profile directory (--user-data-dir): cookies, local storage, saved passwords, open tabs. That is what keeps you signed in between runs. Only one Chrome can use a profile at a time. pw-pool creates one profile per session, keeps it between runs, and can seed a new one from a template — a copy of the login files of a profile you are already signed in with — so a new session starts signed in without sharing a browser with anyone.

Install

Needs Node 22+ and macOS or Linux.

git clone https://github.com/ckarnell/pw-pool && cd pw-pool
npm install            # pins @playwright/mcp and patches it
node bin/pw-pool.js install    # checks the setup; offers to download Chrome for Testing if missing

Or globally, which puts pw-mcp and pw-pool on your PATH: npm install -g github:ckarnell/pw-pool.

Then use pw-mcp as the Playwright MCP command. Claude Code (~/.claude.json or a project .mcp.json):

"playwright": { "type": "stdio", "command": "pw-mcp" }

(or "command": "node", "args": ["/path/to/pw-pool/bin/pw-mcp.js"] for a clone that is not on PATH).

Other MCP flags (--caps, --output-dir, …) can be added to args; they pass through. --headless is applied to the pool's launch. --cdp-endpoint, --user-data-dir, --isolated and --browser are dropped with a warning, because the pool chooses the browser.

By default browsers are Playwright's Chrome for Testing. To use the Chrome already installed on the machine: pw-pool config set channel '"chrome"' (also chrome-beta, chrome-canary, msedge), or config.chrome for an explicit path.

Optional, to start every session signed in:

pw-pool template save main --from ~/path/to/a/signed-in/user-data-dir
pw-pool config set defaultTemplate '"main"'

Switching while sessions are open

You can change the MCP config at any time; nothing running is affected. An MCP server is started once per session, so sessions that are already open keep their old server and browser until they restart. Sessions that start (or restart, for example claude --resume) after the change use pw-pool. Order that works:

1. Save a template from the browser you use today and set it as the default (above), so the new browsers are signed in.
2. Change the MCP entry to pw-mcp.
3. Nothing else. Old sessions continue; new ones get their own browser.

To go back, restore the old MCP entry. Browsers that pw-pool started are reaped after the idle TTL, or at once with pw-pool stop all. A browser you ran before (for example a shared one on a fixed CDP port) is not touched by pw-pool and can keep running beside it.

How it works

session A ─▶ pw-mcp ─▶ registry ─▶ Chrome :9300, profiles/A/ ◀─ @playwright/mcp --cdp-endpoint
session B ─▶ pw-mcp ─▶ registry ─▶ Chrome :9301, profiles/B/ ◀─ @playwright/mcp --cdp-endpoint

• pw-mcp replaces npx @playwright/mcp as the MCP server command. It finds out which session is calling, takes that session's browser from the pool (launching one if needed), and runs the bundled @playwright/mcp against it over CDP. Stdio passes straight through.
• When the MCP exits, the browser stays up. A resumed session gets the same browser, tabs and all.
• A browser with no open tabs and no active session is stopped at once; one that still has tabs is stopped 1 hour after its session ends (tabs saved). A later start relaunches it on the same profile and reopens the tabs. Unused profiles are deleted after 30 days. An active session holds a lease and is never reaped.
• Nothing raises a window: browsers start with no window, and tabs are opened in the background. The bundled MCP carries a two-line patch for the same reason (see Focus).

No daemon. State is a JSON registry under ~/.pw-pool/, guarded by a lock.

Which session is which

pw-mcp needs a stable key per session. In order:

1. --key / PW_POOL_KEY — explicit. Any harness can set this. PW_POOL_NAME labels the window.
2. CLAUDE_CODE_SESSION_ID — Claude Code (2.1.239+) sets it in the MCP server's environment.
3. ~/.claude/sessions/<parent pid>.json — Claude Code writes its session id, name and cwd there.
4. The parent pid — fallback; the browser is deleted when the lease ends.

Same key, same browser. claude --resume keeps the session id, so it gets its browser back.

Templates

pw-pool template save <name> --from <dir> copies the login files of a profile (cookies, local storage, IndexedDB, saved passwords, preferences — a few MB; no caches). A new session's profile is seeded from --template <name>, PW_POOL_TEMPLATE, or config.defaultTemplate, once, when it is created. After that each profile evolves on its own. --fresh forces an empty profile.

Templates and profiles contain live credentials. Keep ~/.pw-pool/ out of repositories. A template is a point-in-time copy: save it again after signing in to something new.

CLI

pw-pool install [--yes]            first-time setup; asks before downloading Chrome
pw-pool ls                         registered browsers: key, name, port, pid, status, tabs, leases
pw-pool cdp [key] [--ensure]       CDP endpoint of a session's browser (default: the calling session)
pw-pool tabs [key]
pw-pool gc [--force] [--dry-run]   reap stale leases, idle browsers, old profiles
pw-pool stop <key|all> [--rm]      stop a browser (tabs saved); --rm also deletes its profile
pw-pool template save <name> [--from <dir>] | ls | rm <name>
pw-pool config [get <key> | set <key> <json>]
pw-pool doctor

<key> is a full key, a unique prefix, or a session name. pw-pool cdp --ensure lets scripts drive the same browser as their session's MCP. Every pw-mcp start runs gc; for machines where sessions are rare, run pw-pool gc from cron or launchd.

Config lives in ~/.pw-pool/config.json (pw-pool config): portRange [9300, 9399], idleTtlHours 1, profileTtlDays 30, defaultTemplate, sourceProfile, chrome, channel, headless, sandbox (off, like Playwright's chromiumSandbox), profileTheme, windowCascade, windowSize, extraChromeArgs, launchTimeoutMs. PW_POOL_HOME moves the whole state directory; PW_POOL_HEADLESS=1 runs browsers headless (servers, containers).

profileTheme: true tints each browser's toolbar a stable color derived from its key, so several pool windows are easy to tell apart on screen (macOS Cmd-Tab still shows one icon per instance; this colors the window itself). A fixed "R,G,B" themes every pool browser the same.

Focus

On macOS, two things activate a Chrome app and take focus from the person using the machine: a window created at startup, and a tab created in the foreground. pw-pool launches Chrome with --no-startup-window and opens tabs with CDP's background: true. @playwright/mcp has no option for this, so scripts/patch-focus.js changes two lines in the bundled copy (browser_tabs new → background tab, browser_tabs select → no bringToFront). The patch is applied on npm install; pw-pool doctor verifies it; PW_MCP_FOREGROUND_TABS=1 restores the original behaviour.

One case is outside the patch's reach: when a page itself opens a popup (window.open or a target="_blank" link on a click), macOS activates the browser to show it, the same as any Chrome. Browsers are headed by default, matching @playwright/mcp. If that focus-stealing matters on a shared machine, run headless: pw-pool config set headless true, PW_POOL_HEADLESS=1, or per session pw-mcp --headless (and --headed to force headed when the default is headless). Headless renders identically for snapshots and screenshots.

Troubleshooting

• The MCP disconnects ("Connection closed") right after a browser_evaluate. The result was larger than the client's per-message limit (16 MB in Claude Code), so the client closed the connection. This is not specific to pw-pool. The client restarts the server within seconds and pw-mcp reattaches to the same browser, tabs included; call the tool again and return smaller values. Claude Code keeps the server's log under ~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-playwright/.
• "Chrome exited during startup" or "did not answer": the error quotes the end of ~/.pw-pool/logs/<key>.chrome.log. Common causes: no display on Linux (use headless or Xvfb), a binary that cannot run (pw-pool doctor).
• A browser seems to belong to nobody: pw-pool ls shows leases; ! marks a holder that has exited. pw-pool gc clears those; pw-pool stop <key> stops a browser you are sure about.

Development

npm test               # unit tests (no browser needed)
npm run test:e2e       # real browsers, throwaway pool home: isolation, reattach, concurrency, recovery, templates
npm run test:docker    # the same on Linux in a container

The @playwright/mcp version is pinned. To bump it, change the version, run npm install, and fix scripts/patch-focus.js if the install fails (the bundle changed shape).

Releasing

Publishing uses npm trusted publishing (OIDC from GitHub Actions) — no tokens. One-time setup on npmjs.com: the package's Settings → Trusted Publisher → this repo's publish.yml workflow. After that, release by tagging: npm version patch && git push --follow-tags. The workflow runs the tests and npm publish --provenance. (The first ever publish, before the package exists, is done once locally with npm publish --access public --auth-type=web.)

License

MIT