playwriter - Playwright Browser Automation for AI Agents

Playwriter connects AI agents to your running Chrome browser instead of spawning a new headless instance. Your existing logins, cookies, extensions, and tab state are all preserved.

When to use this skill

• Automate sites that require login (Gmail, GitHub, internal tools) without re-authenticating

• Control your real browser tab with full Playwright API access

• Run stateful automation that spans multiple steps (shopping carts, multi-step forms)

• Use MCP integration for Claude Desktop / AI agent browser control

• Record browser sessions or debug with CDP inspection

• Remote browser automation via tunnels

vs. agent-browser: agent-browser spawns a fresh headless browser (isolated, CI-friendly). playwriter connects to your existing Chrome session (authenticated, stateful, with your extensions).

Installation

Step 1: Install Chrome Extension

Install the Playwriter Chrome extension from the Web Store (search "Playwriter MCP" or use extension ID jfeammnjpkecdekppnclgkkffahnhfhe ).

After installing, click the extension icon on any tab you want to allow automation on. The icon turns green when a tab is enabled for control.

Step 2: Install CLI

npm install -g playwriter

or run without installing:

npx playwriter@latest --help

The extension auto-starts a WebSocket relay server at localhost:19988 .

Core workflow

Always follow the Observe → Act → Observe pattern:

1. Create a session

playwriter session new

2. Navigate and observe

playwriter -s 1 -e 'await page.goto("https://example.com")' playwriter -s 1 -e 'await snapshot({ page })'

3. Interact based on snapshot output

playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

4. Re-observe after action

playwriter -s 1 -e 'await snapshot({ page })'

Session management

Create a new isolated stateful session

playwriter session new

List all active sessions (shows browser, profile, state info)

playwriter session list

Delete a session and clear its state

playwriter session delete <sessionId>

Reset the CDP connection and clear execution environment

playwriter session reset <sessionId>

The -e / --eval flag

Execute arbitrary Playwright code in a session:

Navigate to a URL

playwriter -s 1 -e 'await page.goto("https://github.com")'

Fill a form field

playwriter -s 1 -e 'await page.fill("#search", "playwriter"); await page.keyboard.press("Enter")'

Get accessibility snapshot (preferred over screenshots for text content)

playwriter -s 1 -e 'await snapshot({ page })'

Take screenshot with visual accessibility labels (color-coded by element type)

playwriter -s 1 -e 'await screenshotWithAccessibilityLabels({ page })'

Store state between calls (state object persists within session)

playwriter -s 1 -e 'state.url = page.url(); state.title = await page.title()' playwriter -s 1 -e 'console.log(state.url, state.title)'

Quoting rules: Wrap code in single quotes. For multiline code, use heredoc:

playwriter -s 1 -e "$(cat <<'EOF' const text = await page.textContent('h1'); state.heading = text; await snapshot({ page }); EOF )"

MCP Integration

Claude Desktop config (~/.claude/settings.json or Claude Desktop MCP settings)

{ "mcpServers": { "playwriter": { "command": "npx", "args": ["-y", "playwriter@latest"] } } }

Remote relay server

{ "mcpServers": { "playwriter": { "command": "npx", "args": ["-y", "playwriter@latest"], "env": { "PLAYWRITER_HOST": "your-relay-host", "PLAYWRITER_TOKEN": "your-secret-token", "PLAYWRITER_SESSION": "1" } } } }

MCP tools exposed

Tool Description

execute

Run arbitrary JavaScript Playwright code (code , timeout params)

reset

Recreate CDP connection, clear state — use after connection failures

Built-in globals (in execute sandbox)

Global Description

page

Current Playwright page

context

Browser context

state

Persistent object — survives multiple -e calls in same session

snapshot({ page })

Accessibility tree as text (token-efficient)

screenshotWithAccessibilityLabels({ page })

Screenshot with color-coded element markers

getPageMarkdown()

Article text via Mozilla Readability

waitForPageLoad()

Smart load detection

getLatestLogs()

Browser console errors/logs

getCleanHTML()

Cleaned DOM HTML

getLocatorStringForElement()

Get selector for a DOM element

getReactSource()

React component source tree

Accessibility labeling

screenshotWithAccessibilityLabels({ page }) overlays color-coded markers on interactive elements:

Color Element type

Yellow Links

Orange Buttons

Coral Inputs

Pink Checkboxes

Peach Sliders

Click a labeled element using aria-ref :

playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

Network interception and state persistence

Intercept network requests

playwriter -s 1 -e 'state.requests = []; page.on("request", r => state.requests.push(r.url()))'

Check collected requests later

playwriter -s 1 -e 'console.log(state.requests.slice(-5).join("\n"))'

Screen recording

playwriter -s 1 -e 'await recording.start()'

... do actions ...

playwriter -s 1 -e 'const video = await recording.stop(); state.video = video'

Remote access

Control Chrome on a remote machine via tunnel:

On the machine with Chrome:

playwriter serve --token my-secret --replace

From agent machine:

playwriter --host <ip-or-hostname> --token my-secret -s 1 -e 'await page.goto("https://example.com")'

Best practices

• Observe → Act → Observe: always call snapshot({ page }) before and after each action

• Prefer snapshot() over screenshots for text inspection (fewer tokens, faster)

• Never chain actions blindly — verify state between steps

• Use stable selectors: prefer aria-ref , data-testid , or accessible roles

• Store context in state : avoid repeated navigation by persisting page references

• Use reset on failures: CDP disconnects recover cleanly with playwriter session reset

Troubleshooting

Issue Solution

Extension not connecting Click extension icon on the tab; icon must be green

connection refused :19988

Extension auto-starts server; check Chrome is running with extension installed

Code execution timeout Increase with --timeout 30000 flag

Click fails silently Use snapshot({ page }) — a modal likely intercepts the click

Stale session Run playwriter session reset <id> to restore CDP connection

Remote access failing Confirm playwriter serve is running and token matches

References

• GitHub: remorses/playwriter

• Chrome Extension Web Store

• playwriter skill — print full usage guide from CLI

• playwriter logfile — view relay server + CDP log paths