playwriter AGENTS.md

this is the playwriter codebase

the extension uses chrome.debugger to manage the user browser

read ./README.md for an overview of how this extension and mcp work read playwriter/src/skill.md to understand the MCP docs (source of truth)

backward compatibility

breaking changes to the WS protocol MUST never be made. publishing the extension code will never be instant, which means the extension must keep working with newer versions of the MCP and WS relay server.

architecture

• user installs the extension in chrome. we assume there is only one chrome window for now, the first opened.
• extension connects to a websocket server on port 19988. if this server is not yet open, it retries connecting in a loop
• the MCP spawns the ws server if not already listening on 19988, in background. the mcp then connects to this same server with a playwright client
• the server exposes /cdp/client-id which is used by playwright clients to communicate with the extension
• the extension instead connects to /extension which is used to receive cdp commands and send responses and cdp events.
• some events are treated specially for example because
  • we need to send attachedToTarget to let playwright know which pages are available
  • we need to send detachedFromTarget when we disable the extension in a tab
  • a few more events need custom handling
• tabs are identified by sessionId or targetId (CDP concepts) or tabId (chrome debugger concept only)

mcp.ts MUST never use console.log. only console.error

write code that will run on all platforms: mac, linux, windows. especially around paths handling and command execution

development

running MCP locally

to test the MCP server with local changes, add it to your MCP client config with tsx:

{
  "mcpServers": {
    "playwriter": {
      "command": "tsx",
      "args": ["/path/to/playwriter/playwriter/src/mcp.ts"]
    }
  }
}