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

123456789playwriter session new    # => 1
playwriter session new    # => 2

# List all sessions with their stored keys
playwriter session list
# ID  State Keys
# --------------
# 1   myPage, userData
# 2   -

Pass -s <id> to all commands to use a specific session:

12playwriter -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:

12345678// Call 1: store data
state.page = context.pages().findLast(p => p.url() === 'about:blank') ?? 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. To avoid interference, always get your own page:

1234// First call: grab an empty tab or create one, navigate immediately
state.page = context.pages().findLast(p => p.url() === 'about:blank') ?? await context.newPage()
await state.page.goto('https://example.com')
// Store in state.page and use it for ALL subsequent operations

Navigate in the same call as creating the page. This prevents another agent from grabbing the same about:blank tab between execute calls.

Handle page closures

The user may close your tab. Always check before using it:

1234if (!state.page || state.page.isClosed()) {
  state.page = context.pages().findLast(p => p.url() === 'about:blank') ?? await context.newPage()
}
await state.page.goto('https://example.com')

Using existing pages

Only use a page from context.pages() if the user explicitly asks you to control a specific tab:

123const pages = context.pages().filter(x => x.url().includes('myapp.com'))
if (pages.length === 0) throw new Error('No myapp.com page found')
state.targetPage = pages[0]

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.

1234567891011# 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:

1playwriter 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:

12playwriter 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:

1playwriter 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.

Session management

12345678# 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:

Variable	Description
`state`	Persisted object, isolated per session
`page`	Default page (shared, prefer `state.page`)
`context`	Browser context, access all pages via `context.pages()`
`require`	Load Node.js modules (`path`, `fs`, `crypto`, etc.)
`fetch`	Standard fetch API
`Buffer`, `URL`, `URLSearchParams`	Standard globals
`setTimeout`, `setInterval`	Timers
`crypto`, `process`	Node.js globals

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():

1234567await 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:

1state.page.removeAllListeners()

Never call browser.close() or context.close(). Only close pages you created yourself.