Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Multi-Agent Browser Sessions with Isolated State

Sessions let you run multiple agents at once without interference. Each session is an isolated sandbox with its own state object. Variables, pages, and listeners persist between calls. Browser tabs are shared, but state is not.

Creating sessions

playwriter session new # => 1 playwriter session new # => 2 # List all sessions with their stored keys playwriter session list # ID State Keys # -------------- # 1 page, userData # 2 -
Pass -s <id> to all commands to use a specific session:
playwriter -s 1 -e "state.users = ['Alice', 'Bob']" playwriter -s 2 -e "console.log(state.users)" # undefined (isolated)

State persistence

The state object persists between execute calls within the same session. Use it to store pages, data, listeners, and anything else you need across calls:
// Call 1: store data state.page = await context.newPage() await state.page.goto('https://example.com') state.results = [] // Call 2: data is still there console.log(state.results.length) // 0 state.results.push(await state.page.title())

Pages are shared, state is not

context.pages() returns all browser tabs with Playwriter enabled, shared across all sessions. Multiple agents see the same tabs. There is no default page. Always create your own page:
// First call: create a tab and navigate immediately state.page = await context.newPage() await state.page.goto('https://example.com') // Use state.page for ALL subsequent operations
Navigate in the same call as creating the page.

Handle page closures

The user may close your tab. Always check before using it:
if (!state.page || state.page.isClosed()) { state.page = await context.newPage() } await state.page.goto('https://example.com')

Using existing pages

Only use a page from context.pages() if the user points you to a specific tab. Find it by URL. findLast picks the most recently opened match:
state.page = context.pages().findLast((p) => p.url().includes('myapp.com')) if (!state.page) throw new Error('No myapp.com page found')

Tab groups per session

Tabs a session creates are grouped in a Chrome tab group named playwriter by default. Use the shortest clear single-word name with no spaces, such as docs, shop, test, or scrape.
# Tabs created by this session join a group named "docs" playwriter session new --tab-group docs # Pick the group color yourself (any Chrome color) playwriter session new --tab-group docs --tab-group-color blue # Rename the group later — moves the session's existing tabs playwriter session update 1 --tab-group research # Change only the color — also works on the default playwriter group playwriter session update 1 --tab-group-color red
Park work on another screen. Give the session its own group, then right-click the group and choose Move group to new window. New tabs from that session follow the group, even if the window is minimized:
playwriter session new --tab-group scrape --tab-group-color grey
Split concurrent agents. Each agent should use its own --tab-group. That keeps many open tabs readable instead of one mixed strip:
playwriter session new --tab-group agent1 --tab-group-color blue playwriter session new --tab-group agent2 --tab-group-color pink
Collapse groups you don't care about. Click the group name in Chrome to collapse it. Use a clear name so leftover work takes less space without closing the tabs:
playwriter session new --tab-group done --tab-group-color grey
Renaming a session that still uses the default playwriter group only moves tabs that session created. Manually enabled tabs and other sessions' tabs stay in the default group. Renaming a custom group moves everything in it, including tabs you dragged in.
Without --tab-group-color, each custom group gets a deterministic color derived from its name (the default playwriter group stays green). The flag accepts every Chrome group color: grey, blue, red, yellow, green, pink, purple, cyan, orange. playwriter session list shows the group per session in the GROUP column.
Tab groups are cosmetic:
  • Dragging a tab between playwriter groups is fine — the connection is kept and the tab simply adopts the new group.
  • Dragging a tab out of all playwriter groups disconnects it (same as before).
  • Dragging an unrelated tab into any playwriter group connects it.
  • Moving a whole group to another window (Chrome's "Move group to new window") keeps the tabs connected.
Only extension sessions support tab groups. Headless, direct CDP, and cloud sessions have no browser UI to group.

Node API

Use connectViaExtension() from the playwriter package. It starts the relay if needed, waits for the Chrome extension, creates a session, and connects over CDP.
import { connectViaExtension } from 'playwriter' await using connection = await connectViaExtension({ tabGroup: 'email-check', tabGroupColor: 'grey', }) // the page closes its tab when the scope ends, also on throw await using page = await connection.browser.contexts()[0].newPage() await page.goto('https://example.com')
tabGroupColor is typed as Chrome's tab group colors: grey, blue, red, yellow, green, pink, purple, cyan, orange. await using calls close() at scope end: it disconnects CDP and deletes the session. It needs Node 24+ (or a TypeScript 5.2+ / tsx build). Without await using, call await connection.close() in finally.
Close your own tabs. connection.close() does not close any tab. Use await using page or call page.close() for every tab your script opens. Pass closeTabsOnEnd: true to make close() also close every tab this connection opened, plus popups they opened (never other sessions' tabs).

Keeping tabs across processes

A tab you do not close stays open. A later process finds it in context.pages():
// process A await using a = await connectViaExtension({ tabGroup: 'job' }) await (await a.browser.contexts()[0].newPage()).goto('https://example.com') // process B, later await using b = await connectViaExtension({ tabGroup: 'job' }) const page = b.browser.contexts()[0].pages().findLast((p) => p.url() === 'https://example.com/')
Match tabs by their exact url, never startsWith or includes. context.pages() lists every Playwriter tab, also tabs other sessions opened for unrelated work (a download tab, a song page), and a loose match picks one of those.

Sharing one tab between processes

Scripts that only call fetch inside a signed-in site can share one tab instead of each loading the site again. Two rules make it safe:
  • Never pass closeTabsOnEnd: true. It closes the tab when the session that created it ends, while another process still uses it.
  • Keep the holder list inside the tab with page.evaluate. The page runs JS on one thread, so each evaluate is atomic. The last holder closes the tab.
process A ──▶ no tab with exact url ──▶ open it ──▶ window.__shared = { holders: [A] } process B ──▶ finds it ──▶ evaluate: closing? no ──▶ holders: [A, B] A leaves ──▶ evaluate: holders: [B] tab stays open B leaves ──▶ evaluate: holders: [], closing = true ──▶ page.close()
import { randomUUID } from 'node:crypto' import { connectViaExtension, type Page, type PlaywriterBrowserConnection } from 'playwriter' type Shared = { holders: string[]; closing: boolean } const APP_URL = 'https://example.com/app' // exact url of the shared tab const me = `${process.pid}:${randomUUID()}` const alive = (holder: string) => { try { process.kill(Number(holder.split(':')[0]), 0) return true } catch (e) { return (e as NodeJS.ErrnoException).code === 'EPERM' } } // false when the tab is not set up yet (loading, reloaded), closing, or closed const join = (page: Page) => page .evaluate((me) => { const shared = (window as any).__shared as Shared | undefined if (!shared || shared.closing) return false shared.holders.push(me) return true }, me) .catch(() => false) // true when we were the last live holder async function leave(page: Page) { const holders: string[] = await page.evaluate(() => (window as any).__shared?.holders ?? []) const remove = [me, ...holders.filter((h) => !alive(h))] // crashed processes never block the close return page.evaluate((remove) => { const shared = (window as any).__shared as Shared | undefined if (!shared) return false // list wiped by a reload: never close a tab we cannot account for shared.holders = shared.holders.filter((h) => !remove.includes(h)) if (shared.holders.length === 0) shared.closing = true return shared.closing }, remove) } async function claim(connection: PlaywriterBrowserConnection) { const context = connection.browser.contexts()[0] for (const page of context.pages().filter((p) => p.url() === APP_URL)) { if (await join(page)) return page } const page = await context.newPage() let ready = false try { await page.goto(APP_URL, { waitUntil: 'load' }) await page.evaluate((me) => { ;(window as any).__shared = { holders: [me], closing: false } satisfies Shared }, me) ready = true return page } finally { if (!ready) await page.close().catch(() => {}) // never leak a half-set-up tab } } await using connection = await connectViaExtension({ tabGroup: 'app' }) const page = await claim(connection) try { const user = await page.evaluate(() => fetch('/api/me').then((r) => r.json())) } finally { if (await leave(page).catch(() => false)) await page.close().catch(() => {}) }
  • No race with a closing tab: the last holder sets closing in the same evaluate that empties the list, so a joiner either gets in first or skips that tab and opens a new one.
  • Ctrl+C: finally does not run when the process is killed by a signal. Handle SIGINT/SIGTERM by running the same leave() first. Holders of crashed processes are dropped by the next leave().
  • Never navigate or reload the shared page. It wipes window.__shared, and the tab is then never closed. Open your own tab for navigation, and close it yourself.
  • Two processes that start at the same moment with no tab open may both open one. Each tab still closes correctly.
  • The pid check works only for processes on the same machine.

Choosing a browser

If the extension runs in more than one browser or profile (Chrome, Brave, Ghost, a work profile), pass selectBrowser. It gets every connected browser and returns the one to use. Without it, connecting fails when more than one browser is connected.
import { connectViaExtension, listBrowsers } from 'playwriter' await using connection = await connectViaExtension({ selectBrowser: (browsers) => { // [{ id, browser: 'Brave', email: 'me@work.com', activeTabs, playwriterVersion }] return browsers.find((b) => b.browser === 'Brave' && b.email === 'me@work.com') }, }) console.log(connection.extensionBrowser.id) // same list, without connecting const browsers = await listBrowsers()
id is stable across restarts, so you can save it and match on it later. email is null when the profile is not signed in.
Do not POST /cli/session/new yourself. Do not call chromium.connectOverCDP(getCdpUrl(...)) unless you already have a session from the CLI.

Session management

# Reset a session (reconnect browser, clear state) playwriter session reset 1 # Delete a session playwriter session delete 1 # List all sessions playwriter session list

Context variables

Every session has access to these globals:
VariableDescription
statePersisted object, isolated per session
contextBrowser context, access all pages via context.pages()
requireLoad Node.js modules (path, fs, crypto, etc.)
fetchStandard fetch API
Buffer, URL, URLSearchParamsStandard globals
setTimeout, setIntervalTimers
crypto, processNode.js globals
There is no default page global. Reading page throws. Store your own page in state.page.
Popup windows (window.open, OAuth login flows, target=_blank) are auto-relocated to tabs in the main window by the extension. The new tab appears in context.pages():
await state.page.locator('button:has-text("Login with Google")').click() await state.page.waitForTimeout(1000) // New tab is the last page const pages = context.pages() const loginPage = pages[pages.length - 1] await loginPage.locator('[data-email]').first().click()
You'll receive a [WARNING] New page opened from current page (index N, initial url: ...) message pointing to the new tab.

Clean up

Always clean up listeners at the end of your message to prevent memory leaks:
state.page.removeAllListeners()
Never call browser.close() or context.close(). Only close pages you created yourself.