Reinasboo/playwriter

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