Skip to content
Back to search

playwriter

Chrome extension & CLI to let agents control your browser. Runs Playwright snippets in a stateful sandbox. Available as CLI or MCP

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/remorses/playwriter with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/remorses/playwriter'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/remorses-playwriter/badge.svg)](/listings/remorses-playwriter)

HTML

<a href="/listings/remorses-playwriter"><img src="/api/listings/remorses-playwriter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. [**Install Extension**](https://chromewebstore.google.com/detail/playwriter/jfeammnjpkecdekppnclgkkffahnhfhe) from Chrome Web Store

2. Click extension icon on a tab → turns green when connected

3. Install the CLI and start automating the browser:

   npm i -g playwriter
   playwriter -s 1 -e 'state.page = await context.newPage(); await state.page.goto("https://example.com")'

4. Install the skill so your agent knows how to use Playwriter:

   npx -y skills add https://playwriter.dev

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 436 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align='center'>
  2. <br/>
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="banner-dark.png" />
  5. <source media="(prefers-color-scheme: light)" srcset="banner.png" />
  6. <img src="banner.png" alt="Playwriter - For browser automation MCP" width="400" height="278" />
  7. </picture>
  8. <br/>
  9. <br/>
  10. <p>Let your agents control your own Chrome, via CLI or MCP. Your logins, extensions, cookies — already there.</p>
  11. <br/>
  12. </div>
  13. https://github.com/user-attachments/assets/72fe022b-63ce-41f3-a1ff-1107286f5c2b
  14. Other browser MCPs spawn a fresh Chrome — no logins, no extensions, instantly flagged by bot detectors, double the memory. Playwriter connects to **your running browser** instead. One Chrome extension, full Playwright API, everything you're already logged into.
  15. ## Installation
  16. 1. [**Install Extension**](https://chromewebstore.google.com/detail/playwriter/jfeammnjpkecdekppnclgkkffahnhfhe) from Chrome Web Store
  17. 2. Click extension icon on a tab → turns green when connected
  18. 3. Install the CLI and start automating the browser:
  19. ```bash
  20. npm i -g playwriter
  21. playwriter -s 1 -e 'state.page = await context.newPage(); await state.page.goto("https://example.com")'
  22. ```
  23. 4. Install the skill so your agent knows how to use Playwriter:
  24. ```bash
  25. npx -y skills add https://playwriter.dev -g -y
  26. ```
  27. ## Quick Start
  28. ```bash
  29. playwriter browser start # starts Chrome for Testing/Chromium with bundled Playwriter extension
  30. playwriter session new # creates stateful sandbox, outputs session id (e.g. 1)
  31. playwriter -s 1 -e 'state.page = await context.newPage(); await state.page.goto("https://example.com")'
  32. playwriter -s 1 -e 'console.log(await snapshot({ page: state.page }))'
  33. playwriter -s 1 -e 'await state.page.locator("aria-ref=e5").click()'
  34. ```
  35. > **Tip:** Always use single quotes for `-e` to prevent bash from interpreting `$`, backticks, and `\` in your JS code. Use double quotes for strings inside the JS.
  36. ## CLI Usage
  37. Each session has **isolated state**. Browser tabs are **shared** across sessions.
  38. ```bash
  39. # Browser management
  40. playwriter browser start # auto-finds Chrome for Testing or Chromium
  41. playwriter browser start /path/to/browser-binary
  42. # Session management
  43. playwriter session new # creates stateful sandbox, outputs id (e.g. 1)
  44. playwriter session new --tab-group agent1 --tab-group-color blue
  45. playwriter session update 1 --tab-group research
  46. playwriter session list # show sessions + state keys + group
  47. playwriter session reset <id> # fix connection issues
  48. # Execute (always use -s)
  49. playwriter -s 1 -e 'state.page = await context.newPage(); await state.page.goto("https://example.com")'
  50. playwriter -s 1 -e 'await state.page.click("button")'
  51. playwriter -s 1 -e 'console.log(await state.page.title())'
  52. ```
  53. There is no default `page`. Create your own tab and store it in `state`. To use a tab the user already opened, find it by URL:
  54. ```bash
  55. playwriter -s 1 -e 'state.page = context.pages().findLast((p) => p.url().includes("github.com"))'
  56. ```
  57. ### Tab groups
  58. Local extension sessions use a Chrome **tab group** named `playwriter` by default. Remote-control sessions put the tabs they open into `remote`. Use the shortest clear single-word name with no spaces, such as `docs`, `shop`, `test`, or `scrape`.
  59. ```bash
  60. # Park a long scrape in its own group. The user can Move group to new window
  61. # (or another screen). New tabs from this session follow that group.
  62. playwriter session new --tab-group scrape --tab-group-color grey
  63. # Split concurrent agents so many open tabs stay readable
  64. playwriter session new --tab-group agent1 --tab-group-color blue
  65. playwriter session new --tab-group agent2 --tab-group-color pink
  66. # Name a group the user can collapse when they don't care about it
  67. playwriter session new --tab-group done --tab-group-color grey
  68. # Rename or recolor later
  69. playwriter session update 1 --tab-group research
  70. playwriter session update 1 --tab-group-color red
  71. # Remote tabs support the same title and color options
  72. playwriter session new --remote <id> --tab-group support
  73. playwriter session update 1 --tab-group review --tab-group-color cyan
  74. ```
  75. `--tab-group-color` accepts: `grey`, `blue`, `red`, `yellow`, `green`, `pink`, `purple`, `cyan`, `orange`. Without it, color is derived from the name. The default local `playwriter` group stays green.
  76. Node programs should use `connectViaExtension()` instead of posting `/cli/session/new` themselves:
  77. ```ts
  78. import { connectViaExtension } from 'playwriter'
  79. await using connection = await connectViaExtension({
  80. tabGroup: 'email-check',
  81. tabGroupColor: 'grey',
  82. })
  83. // the page closes its tab when the scope ends, also on throw
  84. await using page = await connection.browser.contexts()[0].newPage()
  85. await page.goto('https://example.com')
  86. ```
  87. `tabGroupColor` is typed as Chrome's tab group colors. `await using` calls `close()` at scope end: it disconnects CDP and deletes the session. It does **not** close tabs: close every tab your script opens with `await using page` or `page.close()`. Pass `closeTabsOnEnd: true` to make `close()` also close the tabs this connection opened (never other sessions' tabs). Without `await using`, call `await connection.close()` in `finally`.
  88. A tab you do not close stays open, so a later process can reuse it:
  89. ```ts
  90. // process A
  91. await using a = await connectViaExtension({ tabGroup: 'job' })
  92. await (await a.browser.contexts()[0].newPage()).goto('https://example.com')
  93. // process B, later
  94. await using b = await connectViaExtension({ tabGroup: 'job' })
  95. const page = b.browser.contexts()[0].pages().findLast((p) => p.url() === 'https://example.com/')
  96. ```
  97. Match tabs by their exact url: `context.pages()` also lists tabs other sessions opened.
  98. Several processes can share one tab for `fetch` calls inside a signed-in site, and the last one closes it. See [Sharing one tab between processes](https://playwriter.dev/docs/sessions#sharing-one-tab-between-processes).
  99. If the extension runs in more than one browser or profile, pass `selectBrowser`. It gets every connected browser and returns the one to use:
  100. ```ts
  101. await using connection = await connectViaExtension({
  102. selectBrowser: (browsers) => {
  103. // [{ id, browser: 'Brave', email: 'me@work.com', activeTabs, playwriterVersion }]
  104. return browsers.find((b) => b.email === 'me@work.com')
  105. },
  106. })
  107. ```
  108. `id` is stable, so you can save it and match on it later. `listBrowsers()` returns the same list without connecting.
  109. Multiline:
  110. ```bash
  111. playwriter -s 1 -e $'
  112. const title = await state.page.title();
  113. console.log({ title, url: state.page.url() });
  114. '
  115. ```
  116. ## Examples
  117. Variables in scope: `context`, `state` (persists between calls), `cloud` (local CLI sessions), `require`, `importModule`, native `import()`, and Node.js globals. Relative imports resolve from the session working directory. There is no default `page`; examples below assume `state.page` was set as shown above.
  118. **Persist data in state:**
  119. ```bash
  120. playwriter -e "state.users = await state.page.$$eval('.user', els => els.map(e => e.textContent))"
  121. playwriter -e "console.log(state.users)"
  122. ```
  123. **Intercept network requests:**
  124. ```bash
  125. playwriter -e "state.requests = []; state.page.on('response', r => { if (r.url().includes('/api/')) state.requests.push(r.url()) })"
  126. playwriter -e "await Promise.all([state.page.waitForResponse(r => r.url().includes('/api/')), state.page.click('button')])"
  127. playwriter -e "console.log(state.requests)"
  128. ```
  129. **Set breakpoints and debug:**
  130. ```bash
  131. playwriter -e "state.cdp = await getCDPSession({ page: state.page }); state.dbg = createDebugger({ cdp: state.cdp }); await state.dbg.enable()"
  132. playwriter -e "state.scripts = await state.dbg.listScripts({ search: 'app' }); console.log(state.scripts.map(s => s.url))"
  133. playwriter -e "await state.dbg.setBreakpoint({ file: state.scripts[0].url, line: 42 })"
  134. ```
  135. **Live edit page code:**
  136. ```bash
  137. playwriter -e "state.cdp = await getCDPSession({ page: state.page }); state.editor = createEditor({ cdp: state.cdp }); await state.editor.enable()"
  138. playwriter -e "await state.editor.edit({ url: 'https://example.com/app.js', oldString: 'const DEBUG = false', newString: 'const DEBUG = true' })"
  139. ```
  140. **Screenshot with labels:**
  141. ```bash
  142. playwriter -e "await screenshotWithAccessibilityLabels({ page: state.page })"
  143. ```
  144. **Live stream a tab to X Live / Twitch (RTMP, survives CLI exit):**
  145. ```bash
  146. playwriter -s 1 -e "state.page = await context.newPage(); await state.page.goto('https://example.com')"
  147. playwriter stream start -s 1 --rtmp rtmp://va.pscp.tv:80/x/<stream-key>
  148. playwriter stream status -s 1
  149. playwriter stream stop -s 1
  150. ```
  151. ## MCP Setup
  152. Using the CLI with the skill (step 4 above) is the recommended approach. For direct MCP server configuration, see [MCP.md](./MCP.md).
  153. ## Visual Labels
  154. Vimium-style labels for AI agents to identify elements:
  155. ```javascript
  156. await screenshotWithAccessibilityLabels({ page: state.page })
  157. // Returns screenshot + accessibility snapshot with aria-ref selectors
  158. await state.page.locator('aria-ref=e5').click()
  159. ```
  160. Color-coded: yellow=links, orange=buttons, coral=inputs, pink=checkboxes, peach=sliders, salmon=menus, amber=tabs.
  161. ## Comparison
  162. ### vs Playwright MCP
  163. | | Playwriter | Playwright MCP |
  164. | ------------- | --------------------------------- | ------------------------------------ |
  165. | Browser | **Uses your Chrome** | Separate managed profile by default |
  166. | Extensions | Your existing ones | None by default |
  167. | Login state | Already logged in | Persistent, but a separate profile |
  168. | Attach to your Chrome | Core design | `--extension` mode |
  169. | Bot handling | Real browser (disconnect to solve) | Managed automation profile |
  170. | Native video / raw CDP | Yes | Trace-based / not exposed |
  171. > **Note:** Playwriter video recording is **100x more efficient than Playwright video recording**, which sends **base64 images for every frame**.
  172. | | Playwriter | Playwright CLI |
  173. | --------------- | ----------------------------- | ---------------------------------- |
  174. | Browser | **Uses your Chrome** | New browser by default |
  175. | Login state | Already logged in | Persistent profile, separate |
  176. | Extensions | Your existing ones | None by default |
  177. | Captchas | Disconnect extension to solve | Managed automation profile |
  178. | Programmable JS | `execute` with persistent state | `run-code` (no cross-call state) |
  179. | Raw CDP access | First-class | Not exposed |
  180. | Video recording | CDP screencast + ffmpeg, page audio | Trace / screencast based |
  181. ### vs BrowserMCP
  182. | | Playwriter | BrowserMCP |
  183. | ------------- | ------------------------ | ------------------- |
  184. | Tools | **1 `execute` tool** | 12+ dedicated tools |
  185. | API | Full Playwright | Limited actions |
  186. | Context usage | Low | High (tool schemas) |
  187. | LLM knowledge | Already knows Playwright | Must learn tools |
  188. ### vs agent-browser
  189. | | Playwriter | agent-browser |
  190. | ------------------ | ------------------------------ | -------------------------------- |
  191. | Browser | **Uses your Chrome** | Fresh Chrome for Testing |
  192. | API surface | 1 `execute` + full Playwright | 50+ CLI commands, one per action |
  193. | Actions per turn | Real JS (loops, conditions) | `batch` of command strings |
  194. | Reusable logic | Import a `.js` function | Re-run bash sequences |
  195. | Skill recorder | Yes | No |
  196. | Cloud browsers | Built-in stealth + proxy | Plugin only |
  197. | Remote control tab | Yes (Devin, cloud bots) | No |
  198. ### vs Antigravity (Jetski)
  199. | | Playwriter | Jetski |
  200. | -------- | ---------------- | ---------------------------- |
  201. | Tools | **1 tool** | 17+ tools |
  202. | Subagent | Direct execution | Spawns for each browser task |
  203. | Latency | Low | High (agent overhead) |
  204. ### vs Claude Browser Extension
  205. | | Playwriter | Claude Extension |
  206. | -------------------- | ----------------------- | -------------------- |
  207. | Agent support | **Any MCP client** | Claude only |
  208. | Windows WSL | Yes | No |
  209. | Context method | A11y snapshots (5-20KB) | Screenshots (100KB+) |
  210. | Playwright API | Full | No |
  211. | Debugger/breakpoints | Yes | No |
  212. | Live code editing | Yes | No |
  213. | Network interception | Full | Limited |
  214. | Raw CDP access | Yes | No |
  215. ### vs Built-in Chrome CDP (`--remote-debugging-port`)
  216. | | Playwriter | Built-in CDP |
  217. | --------------------- | ---------------------------- | -------------------------------------------------- |
  218. | Setup | **Click extension icon** | Relaunch Chrome with special flags |
  219. | Your real profile | Yes | Blocked on default profile since Chrome 136 |
  220. | Permission prompt | None | "Allow remote debugging?" dialog agents can't click|
  221. | Autonomous agents | Fully autonomous | Blocked by dialog / throwaway profile |
  222. | Existing session | Uses your running browser | Must relaunch Chrome (lose state) |
  223. > Chrome's `--remote-debugging-port` is ignored on your default profile since **Chrome 136**, so you must use a throwaway `--user-data-dir` with none of your logins. Connecting an external CDP client also shows an "Allow remote debugging?" dialog an agent cannot click. Playwriter uses an in-Chrome extension instead: no dialog, no flags, your real profile.
  224. ## Architecture
  225. ```
  226. +---------------------+ +-------------------+ +-----------------+
  227. | BROWSER | | LOCALHOST | | MCP CLIENT |
  228. | | | | | |
  229. | +---------------+ | | WebSocket Server | | +-----------+ |
  230. | | Extension |<---------> :19988 | | | AI Agent | |
  231. | +-------+-------+ | WS | | | +-----------+ |
  232. | | | | /extension | | | |
  233. | chrome.debugger | | | | | v |
  234. | v | | v | | +-----------+ |
  235. | +---------------+ | | /cdp/:id <--------------> | execute | |
  236. | | Tab 1 (green) | | +-------------------+ WS | +-----------+ |
  237. | | Tab 2 (green) | | | | |
  238. | | Tab 3 (gray) | | Tab 3 not controlled | Playwright API |
  239. +---------------------+ (no extension click) +-----------------+
  240. ```
  241. ## Remote Control (share your browser with a remote agent)
  242. Let a remote agent (Devin, a cloud bot, a friend's CLI agent) drive **your own browser**. No playwriter install needed on your machine, only the extension. The agent sees every Playwriter tab and can open new ones, like a local agent.
  243. 1. Click the light-blue **Remote control** cloud button and confirm that the agent may read and control your browser
  244. 2. A prompt containing a secret tunnel URL is copied to your clipboard — paste it to the agent
  245. 3. The agent runs `playwriter session new --remote <id>` on its machine
  246. 4. Open **Remote ON** in any Playwriter tab and click **Stop sharing** anytime to **revoke**. The URL dies instantly. Tabs the agent opened are detached and left open.
  247. Opening that same link in **any browser** shows a live, clickable view of the tab where sharing started, so you can share with a person instead of an agent. The viewer page receives no tunnel id in its initial HTTP request because the id starts in the URL fragment. Its JavaScript then uses the id to connect to the tunnel path (`/tunnel/{id}/extension`), keeping the id out of DNS and TLS SNI.
  248. ```
  249. YOUR MACHINE (extension only) AGENT MACHINE (any box with npx)
  250. ┌───────────────────────────┐ ┌────────────────────────────────┐
  251. │ Chrome + Extension │ Cloudflare tunnel │ playwriter CLI + local relay │
  252. │ Playwriter tabs ◄────────┼───◄ playwriter.dev ◄──┼────── session new --remote │
  253. └───────────────────────────┘ /remote-control#id └────────────────────────────────┘
  254. ```
  255. Remote control is **not a sandbox**. The agent gets the same access as a local Playwriter agent, so share the id only with a person or agent you fully trust. A short denylist blocks only whole-profile cookie APIs and cache clears, so an agent cannot wipe every login by accident. The id contains 128 bits of randomness and is never reusable after revocation.
  256. Sharing also ends when you close or disconnect the tab where you started it.
  257. Use case: you are logged into a website and want an agent to do work in your authenticated session without giving it your password.
  258. ## Remote Access
  259. Control Chrome on a remote machine over the internet using [traforo](https://traforo.dev) tunnels:
  260. **On host:**
  261. ```bash
  262. npx -y traforo -p 19988 -t my-machine -- npx -y playwriter serve --token <secret>
  263. ```
  264. **From remote:**
  265. ```bash
  266. export PLAYWRITER_HOST=https://my-machine-tunnel.traforo.dev
  267. export PLAYWRITER_TOKEN=<secret>
  268. playwriter -s 1 -e 'state.page = await context.newPage(); await state.page.goto("https://example.com")'
  269. ```
  270. Also works on a LAN without traforo (`PLAYWRITER_HOST=192.168.1.10`). Full guide with use cases (remote Mac mini, user support, multi-machine control): [docs/remote-access.md](./docs/remote-access.md)
  271. ## Security
  272. - **Local by default**: The normal WebSocket relay stays on `localhost:19988`. Traffic leaves your machine only when you enable Remote control or configure remote access.
  273. - **Origin validation**: Only our extension IDs allowed (browsers can't spoof Origin)
  274. - **Controlled tab scope**: Tabs are controlled after an extension click. Playwriter never opens a tab on its own. New tabs are created only when code calls `context.newPage()`.
  275. - **Visible automation**: Chrome shows automation banner on controlled tabs
  276. - **No remote access**: Malicious websites cannot connect
  277. ## Telemetry
  278. The local relay sends **anonymous usage stats** to [Strada](https://strada.sh): event names, a random install id, Playwriter version, OS, session kind, and hourly execute counts. It never sends code, URLs, page content, emails, or hostnames.
  279. Opt out with an env var, then restart the relay:
  280. ```bash
  281. export PLAYWRITER_TELEMETRY=0 # or DO_NOT_TRACK=1
  282. playwriter serve restart
  283. ```
  284. ## Playwright API
  285. Connect programmatically (without CLI):
  286. ```typescript
  287. import { chromium } from 'playwright-core'
  288. import { startPlayWriterCDPRelayServer, getCdpUrl } from 'playwriter'
  289. const server = await startPlayWriterCDPRelayServer()
  290. const browser = await chromium.connectOverCDP(getCdpUrl())
  291. const page = await browser.contexts()[0].newPage()
  292. await page.goto('https://example.com')
  293. await page.screenshot({ path: 'screenshot.png' })
  294. // Don't call browser.close() - it closes the user's Chrome
  295. server.close()
  296. ```
  297. Or connect to a running server:
  298. ```bash
  299. npx -y playwriter serve --host 127.0.0.1
  300. ```
  301. ```typescript
  302. const browser = await chromium.connectOverCDP('http://127.0.0.1:19988')
  303. ```
  304. ## Troubleshooting
  305. View relay server logs to debug issues:
  306. ```bash
  307. playwriter logfile # prints the log file path
  308. # typically: ~/.playwriter/relay-server.log
  309. ```
  310. The relay log contains extension, MCP and WebSocket server logs. A separate CDP JSONL log is also created alongside it (see `playwriter logfile`). Both are recreated on each server start.
  311. Example: summarize CDP traffic counts by direction + method:
  312. ```bash
  313. jq -r '.direction + "\t" + (.message.method // "response")' ~/.playwriter/cdp.jsonl | uniq -c
  314. ```
  315. ## Support
  316. If Playwriter is useful to you, consider [sponsoring the project](https://github.com/sponsors/remorses).
  317. ## Known Issues
  318. - If all pages return `about:blank`, restart Chrome (Chrome bug in `chrome.debugger` API)
  319. - Browser may switch to light mode on connect ([Playwright issue](https://github.com/microsoft/playwright/issues/37627))

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.