Playwriter

Installation

1. Install Extension from Chrome Web Store

1. Click extension icon on a tab → turns green when connected

1. Install the CLI and start automating the browser:

   npm i -g playwriter
   playwriter -s 1 -e 'state.page = await context.newPage(); await state.page.goto("https://example.com")'
   

4. Install the skill so your agent knows how to use Playwriter:

   npx -y skills add https://playwriter.dev -g -y
   

MCP Setup

Using the CLI with the skill (step 4 above) is the recommended approach. For direct MCP server configuration, see MCP.md.

Quick Start

playwriter browser start  # starts Chrome for Testing/Chromium with bundled Playwriter extension
playwriter session new  # creates stateful sandbox, outputs session id (e.g. 1)
playwriter -s 1 -e 'state.page = await context.newPage(); await state.page.goto("https://example.com")'
playwriter -s 1 -e 'console.log(await snapshot({ page: state.page }))'
playwriter -s 1 -e 'await state.page.locator("aria-ref=e5").click()'

Tip: Always use single quotes for -e to prevent bash from interpreting $, backticks, and \ in your JS code. Use double quotes for strings inside the JS.

CLI Usage

Each session has isolated state. Browser tabs are shared across sessions.

```bash

Examples

Variables in scope: context, state (persists between calls), cloud (local CLI sessions), require, importModule, native import(), and Node.js globals. Relative imports resolve from the session working directory. There is no default page; examples below assume state.page was set as shown above.

Persist data in state:

playwriter -e "state.users = await state.page.$$eval('.user', els => els.map(e => e.textContent))"
playwriter -e "console.log(state.users)"

Intercept network requests:

playwriter -e "state.requests = []; state.page.on('response', r => { if (r.url().includes('/api/')) state.requests.push(r.url()) })"
playwriter -e "await Promise.all([state.page.waitForResponse(r => r.url().includes('/api/')), state.page.click('button')])"
playwriter -e "console.log(state.requests)"

Set breakpoints and debug:

playwriter -e "state.cdp = await getCDPSession({ page: state.page }); state.dbg = createDebugger({ cdp: state.cdp }); await state.dbg.enable()"
playwriter -e "state.scripts = await state.dbg.listScripts({ search: 'app' }); console.log(state.scripts.map(s => s.url))"
playwriter -e "await state.dbg.setBreakpoint({ file: state.scripts[0].url, line: 42 })"

Live edit page code:

playwriter -e "state.cdp = await getCDPSession({ page: state.page }); state.editor = createEditor({ cdp: state.cdp }); await state.editor.enable()"
playwriter -e "await state.editor.edit({ url: 'https://example.com/app.js', oldString: 'const DEBUG = false', newString: 'const DEBUG = true' })"

Screenshot with labels:

playwriter -e "await screenshotWithAccessibilityLabels({ page: state.page })"

Live stream a tab to X Live / Twitch (RTMP, survives CLI exit):

playwriter -s 1 -e "state.page = await context.newPage(); await state.page.goto('https://example.com')"
playwriter stream start -s 1 --rtmp rtmp://va.pscp.tv:80/x/<stream-key>
playwriter stream status -s 1
playwriter stream stop -s 1

Remote tabs support the same title and color options

playwriter session new --remote <id> --tab-group support playwriter session update 1 --tab-group review --tab-group-color cyan

`--tab-group-color` accepts: `grey`, `blue`, `red`, `yellow`, `green`, `pink`, `purple`, `cyan`, `orange`. Without it, color is derived from the name. The default local `playwriter` group stays green.

Node programs should use `connectViaExtension()` instead of posting `/cli/session/new` themselves:

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. `await using` calls `close()` at scope end: it disconnects CDP and deletes the session. It does **not** close tabs: close every tab your script opens with `await using page` or `page.close()`. Pass `closeTabsOnEnd: true` to make `close()` also close the tabs this connection opened (never other sessions' tabs). Without `await using`, call `await connection.close()` in `finally`.

A tab you do not close stays open, so a later process can reuse it:

// 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: `context.pages()` also lists tabs other sessions opened.

Several processes can share one tab for `fetch` calls inside a signed-in site, and the last one closes it. See [Sharing one tab between processes](https://playwriter.dev/docs/sessions#sharing-one-tab-between-processes).

If the extension runs in more than one browser or profile, pass `selectBrowser`. It gets every connected browser and returns the one to use:

`id` is stable, so you can save it and match on it later. `listBrowsers()` returns the same list without connecting.

Multiline:

Playwright API

Connect programmatically (without CLI):

import { chromium } from 'playwright-core'
import { startPlayWriterCDPRelayServer, getCdpUrl } from 'playwriter'

const server = await startPlayWriterCDPRelayServer()
const browser = await chromium.connectOverCDP(getCdpUrl())
const page = await browser.contexts()[0].newPage()

await page.goto('https://example.com')
await page.screenshot({ path: 'screenshot.png' })
// Don't call browser.close() - it closes the user's Chrome
server.close()

Or connect to a running server:

npx -y playwriter serve --host 127.0.0.1

const browser = await chromium.connectOverCDP('http://127.0.0.1:19988')

Comparison

vs Playwright MCP

Note: Playwriter video recording is 100x more efficient than Playwright video recording, which sends base64 images for every frame.

vs BrowserMCP

vs agent-browser

vs Antigravity (Jetski)

vs Claude Browser Extension

vs Built-in Chrome CDP (`--remote-debugging-port`)

Chrome's --remote-debugging-port is ignored on your default profile since Chrome 136, so you must use a throwaway --user-data-dir with none of your logins. Connecting an external CDP client also shows an "Allow remote debugging?" dialog an agent cannot click. Playwriter uses an in-Chrome extension instead: no dialog, no flags, your real profile.

Troubleshooting

View relay server logs to debug issues:

```bash playwriter logfile # prints the log file path