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 agent-browser
• tasks that need the strongest isolation or the least user-state coupling

Quick routing rule

If the job needs...	Use
The browser the user already has open	playwriter
Existing logins / cookies / extensions	playwriter
A clean, reproducible, disposable session	agent-browser
Headless verification / screenshot diffs / isolated checks	agent-browser
Hosted or cloud browser infrastructure	a provider-specific or cloud-browser skill

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 agent-browser 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

Issue	What to check
Nothing responds	Confirm the extension is installed and enabled on the target tab
Wrong tab/page state	Re-run snapshot({ page }) and confirm you are on the expected tab before clicking
Stale / broken session	playwriter session reset <id>
Quoting breaks JavaScript	Use a heredoc for -e input
Need repeatable isolated automation	Route to agent-browser instead
Browser state is too messy / human interference	Start a fresh session or use a fresh-session browser tool

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 agent-browser 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