Installation

Install the Playwriter Chrome extension, CLI, and optional skill for AI agents.

Playwriter consists of three components: the Chrome extension (required), the CLI tool (recommended), and an optional skill for AI agents.

Chrome extension

1. Install from Chrome Web Store

   Install the Playwriter extension from the Chrome Web Store.

2. Enable on a tab

   Click the extension icon on any tab. The icon turns green when the tab is connected and ready for automation.

   Only tabs where you click the extension icon can be automated. This is an explicit security feature.

3. Verify connection

   The extension automatically connects to the WebSocket relay server on localhost:19988. If Chrome is not running, start it first:

   macOS

   open -a "Google Chrome" --args --profile-directory=Default
   

CLI tool

The CLI is the recommended way to use Playwriter. It provides session management and code execution.

1. Install globally

   npm

   npm install -g playwriter
   

   Or use without installing:

   npx

   npx playwriter@latest session new
   

   When using npx or bunx, always use @latest for the first session command to ensure you’re using the latest version.

2. Verify installation

   Create a test session and run a simple command:

   playwriter session new
   # outputs: 1
   
   playwriter -s 1 -e 'await page.goto("https://example.com")'
   playwriter -s 1 -e 'console.log(await page.title())'
   

   You should see the page title printed to the console.

3. Check logs (optional)

   If you encounter issues, view the relay server logs:

   playwriter logfile
   # prints log file path, typically: ~/.playwriter/relay-server.log
   

   The relay log contains extension, MCP, and WebSocket server logs. A separate CDP JSONL log is created alongside it.

Skill for AI agents

Install the Playwriter skill so AI agents know how to use the tool effectively.

1. Install the skill

   npx -y skills add remorses/playwriter
   

   This adds agent-specific instructions and best practices to your AI agent’s context.

MCP setup (alternative)

If you prefer to use Playwriter as an MCP server instead of the CLI, see the MCP setup guide.

The CLI with the skill (recommended above) is the preferred approach. Direct MCP configuration is for advanced use cases.

Add to your MCP client settings:

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

Or auto-configure:

```bash
npx -y @playwriter/install-mcp playwriter@latest

Optional: Enable automatic tab capture

For screen recording without manual extension clicks, add Chrome flags:

macOS

open -a "Google Chrome" --args --profile-directory=Default \
  --allowlisted-extension-id=jfeammnjpkecdekppnclgkkffahnhfhe \
  --auto-accept-this-tab-capture

Next steps

Quickstart

Run your first automation

CLI usage

Learn session management and code execution