Playwriter

playwriter

Playwriter is the running-browser browser-automation skill. It connects an agent to Chrome/Chromium that is already part of the user’s real workflow instead of spawning a clean disposable browser. That makes it useful for authenticated flows, extension-dependent pages, and long-lived tab context — but less reproducible than a fresh-session browser tool.

When to use this skill

Use playwriter when the task needs one or more of these:

• the browser the user already has open
• existing logins, cookies, or trusted-device state
• extension-dependent workflows
• passkey / SSO / MFA-heavy flows where manual login handoff is realistic
• live-tab continuity with a human and agent sharing the same browser
• MCP-based browser control for Claude / Codex / Gemini using the running browser

Do not use playwriter by default for:

• CI-style repeatable browser checks
• fresh-session verification that should not touch the user’s real browser profile
• simple scraping or deterministic form checks that fit browser-harness
• tasks that need the strongest isolation or the least user-state coupling

Quick routing rule

Instructions

Step 1: Pick the right browser runtime

Use playwriter only when running-browser reuse is the requirement. If the task is really about a clean disposable browser or CI-style reproducibility, route to browser-harness instead.

Step 2: Follow the core workflow

Always follow the same loop:

1. Prepare the running-browser bridge 2. Create or select a session 3. Observe first with snapshot({ page }) 4. Act once 5. Observe again before the next action

Step 1: Install the extension and CLI

# install the CLI
npm install -g playwriter
# or use it without global install
npx playwriter@latest --help

Install the Playwriter Chrome extension, then click the extension icon on the tab you want to control. The tab should show the connected/green state before you assume automation is available.

Step 2: Start browser support and create a session

Use the upstream browser/session flow, not a vague “extension auto-starts everything” assumption:

# start the managed browser/runtime if needed
playwriter browser start

# create a stateful sandbox session
playwriter session new

# inspect current sessions
playwriter session list

Notes:

• playwriter browser start can launch Chrome for Testing / Chromium with the Playwriter extension available.
• playwriter session new creates a stateful sandbox and returns a session id.
• Browser tabs are shared, but session state is isolated.

Step 3: Observe → act → observe

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

# observe current page state
playwriter -s 1 -e 'console.log(await snapshot({ page }))'

# act using a fresh aria-ref from the snapshot
playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

# observe again after the action
playwriter -s 1 -e 'console.log(await snapshot({ page }))'

Rules:

• Never keep using old aria-ref values after navigation or major DOM changes.
• Prefer snapshot({ page }) over screenshots when text structure is enough.
• Use screenshots or recordings only when visual evidence matters.

High-value command patterns

Navigation and state

playwriter browser start
playwriter session new
playwriter session list
playwriter session reset 1
playwriter session delete 1

Execute Playwright code in a session

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

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

# save reusable state between calls
playwriter -s 1 -e 'state.lastUrl = page.url(); state.heading = await page.textContent("h1")'
playwriter -s 1 -e 'console.log(state.lastUrl, state.heading)'

Multiline code safely

playwriter -s 1 -e "$(cat <<'EOF'
const title = await page.title();
state.title = title;
console.log(await snapshot({ page }));
EOF
)"

Use heredocs when the JavaScript would become fragile with quoting.

MCP integration

Use Playwriter when a model client needs browser tooling for the running browser, not when it simply needs any browser tool.

Example MCP config

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

Common uses:

• Claude / Codex / Gemini can call into Playwriter through MCP.
• MCP gives the agent a transport layer; Playwriter still owns the browser/session behavior.
• Session reuse, browser visibility, and tab consent remain Playwriter concerns, not MCP concerns.

Safety and expectations

• playwriter is privileged mode because it can touch the user’s real browser session.
• Prefer it only when session reuse is genuinely required.
• Expect lower reproducibility than a clean isolated browser because tabs, extensions, and humans can mutate state.
• Manual login / MFA / CAPTCHA handoff is normal in this lane; don’t pretend full autonomy is guaranteed.
• Detach or reset cleanly; do not assume it is safe to kill the user’s browser.

Troubleshooting

Examples

Example 1: Logged-in SaaS workflow

• Prompt: "Use my already logged-in Chrome to update a Jira ticket without re-authenticating."
• Expected skill behavior: choose playwriter, mention running-browser reuse, create a session, observe first, then act.

Example 2: Clean browser verification

• Prompt: "Run a repeatable headless checkout test in CI and compare screenshots."
• Expected skill behavior: route away from playwriter to browser-harness or another fresh-session tool because isolation matters more than session reuse.

Example 3: MCP browser bridge

• Prompt: "Connect Codex or Claude to the browser I already have open so it can use my current tabs and cookies."
• Expected skill behavior: choose playwriter, explain MCP config, and make the running-browser assumption explicit.

Best practices

1. Choose playwriter because the browser state matters, not because the word “browser” appears. 2. Start with snapshot({ page }) before any action that could hit the wrong tab or stale UI state. 3. Re-snapshot after each meaningful action; live browser state drifts faster than isolated automation state. 4. Use heredocs for non-trivial JavaScript to avoid shell-quoting bugs. 5. Treat manual login / MFA / CAPTCHA handoff as normal in this lane. 6. Report why a running browser was necessary and when a fresh-session tool would have been safer.

References

Deep-dive docs in this skill:

• modes-and-routing
• session-workflow
• mcp-integration

Primary sources:

• https://raw.githubusercontent.com/remorses/playwriter/main/README.md
• https://playwright.dev/docs/auth
• https://playwright.dev/docs/api/class-browsertype#browser-type-connect-over-cdp
• https://modelcontextprotocol.io/introduction

Output expectations

When using this skill, report:

• why playwriter was chosen instead of a fresh-session browser tool
• session/runtime assumptions
• key actions taken
• evidence captured (snapshot, screenshot, recording, logs)
• any manual handoff or auth-related limitation encountered

Playwriter MCP integration

What MCP does here

MCP is the transport/integration layer that lets a model client expose Playwriter as a tool server.

It does not replace Playwriter’s runtime decisions:

• running browser vs fresh browser
• session reuse vs isolated session
• artifact capture
• auth handoff expectations

Minimal MCP config

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

Good trigger examples

Use Playwriter over a generic browser server when the prompt sounds like:

• “use the browser I already have open”
• “don’t make me log in again”
• “work in my current Chrome session”
• “keep my extensions and tabs”

Bad trigger examples

Route elsewhere when the task sounds like:

• “run this browser test in CI”
• “verify a flow from a clean state”
• “take isolated repeatable snapshots across environments”

Playwriter modes and routing

Use Playwriter for the running-browser lane

Choose playwriter when the task depends on one or more of these:

• the browser the user already has open
• existing cookies or trusted-device session state
• installed extensions
• passkey / SSO / MFA flows where manual login is expected
• live-tab continuity with a human using the same browser

Route away from Playwriter when these matter more

Choose browser-harness or another fresh-session browser tool when the task needs:

• disposable isolation
• CI-style reproducibility
• deterministic verification against a clean state
• automation that should not touch the user’s real browser profile

Why the boundary matters

playwriter is valuable because it solves a different runtime problem than a fresh browser:

• Running-browser reuse trades determinism for access to the real browser state.
• Fresh-session automation trades local continuity for reproducibility and isolation.

Do not flatten both into “browser automation.” The trigger quality of the skill depends on making this boundary explicit.

Playwriter session workflow

Upstream-oriented flow

playwriter browser start
playwriter session new
playwriter -s 1 -e 'await page.goto("https://example.com")'
playwriter -s 1 -e 'console.log(await snapshot({ page }))'

Observe → act → observe

1. Create or pick a session. 2. Observe current state with snapshot({ page }). 3. Take one action. 4. Observe again before the next action.

This is the safest pattern for live-browser work because the browser state can change outside the agent’s control.

Useful commands

playwriter session list
playwriter session reset 1
playwriter session delete 1

Failure recovery

• If the wrong tab appears active, observe again before acting.
• If the connection feels stale, use playwriter session reset <id>.
• If quoting breaks your -e code, switch to a heredoc.
• If the browser state is too messy, restart with a fresh session or route to a fresh-session browser tool.