Playwright Server

A local HTTP server that gives AI agents (and humans) full browser control via simple curl commands. Built on Playwright, it exposes navigation, interaction, screenshots, accessibility snapshots, activity monitoring, and raw Playwright code execution through a clean REST API.

Claude Code Plugin

Install as a Claude Code plugin to give Claude browser automation capabilities:

/plugin marketplace add eran-broder/playwright-server
/plugin install playwright-server@eran-broder-playwright-server

Then use the /playwright-server:browse skill or just ask Claude to browse - it will auto-detect when to use it.

Setup

npm install
npx playwright install chromium

Run

npm run dev

Server runs on http://localhost:3456 (configurable via PORT env var).

API Overview

Category	Endpoints	Description
Browser	POST /browser/start|stop|restart	Lifecycle management
Navigation	POST /navigate, GET /url|title	Go to URLs, get current state
Snapshot	GET /snapshot	Accessibility tree as YAML (lightweight page understanding)
Interaction	POST /click|type|hover|select|keyboard|scroll|wait	Page interactions
Screenshots	POST /screenshot, GET /screenshots	Capture and list screenshots
Content	GET /content	Full page HTML
Code Exec	POST /execute/inline, POST /script/execute-playwright	Run JS or Playwright code
Activity	GET /activity/poll|check|log|summary	Network, console, error monitoring
Pages	GET /pages, POST /pages/switch|switch-latest	Multi-tab management

Key Features

Accessibility Snapshots

Get a structured YAML accessibility tree - 2-5KB vs 50-500KB for raw HTML:

curl http://localhost:3456/snapshot
curl "http://localhost:3456/snapshot?selector=nav"

- heading "Login" [level=1]
- textbox "Email" [focused]
- textbox "Password"
- button "Sign In"

Activity Recording

All browser events (network, console, errors, navigation, dialogs) are captured with incrementing IDs. Poll efficiently with watermarks:

# Get everything + initial watermark
curl "http://localhost:3456/activity/poll?since=0"

# After performing actions, get only new events
curl "http://localhost:3456/activity/poll?since=150"

Playwright Code Execution

Full access to Playwright's page, context, and browser objects - anything Playwright can do, this server can do:

curl -X POST http://localhost:3456/script/execute-playwright \
  -H "Content-Type: application/json" \
  -d '{"code": "await page.waitForSelector(\".loaded\"); return await page.title();"}'

Auth State Persistence

Drop an auth.json file in the project root (Playwright storage state format) and it auto-loads on browser start, restoring cookies and localStorage.

Quick Example

# Navigate
curl -X POST http://localhost:3456/navigate \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# See what's on the page
curl http://localhost:3456/snapshot

# Click something
curl -X POST http://localhost:3456/click \
  -H "Content-Type: application/json" \
  -d '{"selector": "a"}'

# Check what happened (network, errors, console)
curl "http://localhost:3456/activity/poll?since=0"

# Take a screenshot
curl -X POST http://localhost:3456/screenshot \
  -H "Content-Type: application/json" \
  -d '{"name": "after-click"}'

Documentation

• AI Agent Guide - Complete API reference with response shapes, activity types, workflows, and best practices
• Skill Instructions - Compact reference used by the Claude Code plugin

Project Structure

playwright-server/
├── .claude-plugin/       # Claude Code plugin manifest
│   └── plugin.json
├── skills/browse/        # Claude Code skill definition
│   └── SKILL.md
├── src/                  # Server source code
│   ├── server.ts         # Express routes
│   ├── browser-manager.ts
│   ├── activity-recorder.ts
│   ├── screenshot-manager.ts
│   ├── script-manager.ts
│   ├── file-manager.ts   # Generic base class
│   └── types.ts
├── screenshots/          # Captured screenshots (gitignored)
├── scripts/              # Saved scripts (gitignored)
└── auth.json             # Browser auth state (gitignored, optional)