# Playwriter: drive your own Chrome from a CLI or MCP agent

> Playwriter attaches Playwright to the browser you already have open instead of spawning a clean one. The trade-off is a Chrome extension that must stay connected, and a CLI with no session rollback.

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

- Repository: https://github.com/remorses/playwriter
- Website: https://playwriter.dev
- Stars: 3,931 · Forks: 186
- Language: HTML
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/remorses-playwriter

## The problem Playwriter solves is not automation, it is the empty browser

Most browser automation starts from nothing. A tool launches a fresh Chrome profile, and that profile has no cookies, no saved passwords, no installed extensions, and a fingerprint that anti-bot systems have seen a million times. The README states this directly: other browser MCPs "spawn a fresh Chrome" with no logins and no extensions, and are "instantly flagged by bot detectors". Playwriter takes the opposite position. It connects to the browser you are already running. Your logins, extensions and cookies are already there because it is your actual profile, not a copy of it.

The intended user is an engineer wiring an agent into a workflow that crosses an authenticated boundary: an internal dashboard behind SSO, a site where you have a paid session, a page that only renders correctly with a particular extension loaded. It is also aimed at people who already know Playwright. The README's comparison against BrowserMCP makes that explicit, arguing that Playwriter exposes one `execute` tool rather than a dozen named tools, so the model does not have to learn a new API surface before it can act.

## A Chrome extension plus a stateful sandbox, and how the two divide work

There are two moving parts. The first is a Chrome extension, installed from the Chrome Web Store, that connects the browser to the Playwriter CLI. The README describes the connection state visually: clicking the extension icon on a tab turns it green when connected. The second part is the CLI, which runs JavaScript against that connection.

The execution model is a session, identified by a number such as `1`. Each session has isolated state, but browser tabs are shared across sessions, which is why the README suggests creating your own page with `context.newPage()` when several agents are working at once. Inside a session, the variables in scope are `page`, `context`, `state`, `require`, `importModule`, native `import()`, and Node.js globals. `state` is the piece that makes this more than a one-shot script runner: it persists between calls, so you can collect data in one invocation and read it back in the next. Relative imports resolve from the session working directory.

The README also documents two capabilities that go past ordinary page scripting. `getCDPSession` exposes a raw CDP session, and on top of it `createDebugger` and `createEditor` let you list scripts, set a breakpoint by file and line, and patch a string in a live page script. That is a debugging surface, not just a driving surface, and it is the clearest difference from command-set browser tools.

## Installing Playwriter and running a first real snippet

The README gives a four-step path, and the extension comes first. Install the Playwriter extension from the Chrome Web Store, then click its icon on a tab. It turns green when connected. Only then install the CLI, because the CLI has nothing to attach to without that connection.

The global install and a first navigation look like this:

```bash
npm i -g playwriter
playwriter -s 1 -e 'await page.goto("https://example.com")'
```

The `-s 1` flag selects session 1 and `-e` carries the JavaScript. The README warns to always wrap `-e` in single quotes so bash does not interpret `$`, backticks or backslashes in your code, and to use double quotes for strings inside the JS. If you would rather not point the CLI at your day-to-day browser, the README offers a bundled path: `playwriter browser start` launches Chrome for Testing or Chromium with the Playwriter extension included, and `playwriter session new` creates a sandbox and prints its id.

For agents, the README recommends installing the skill rather than hand-writing MCP configuration:

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

Once a session exists, a useful first check is the accessibility snapshot, which returns aria-ref selectors you can click by name:

```bash
playwriter -s 1 -e 'console.log(await snapshot({ page }))'
playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'
```

The README describes the labels as Vimium-style and color-coded, with yellow for links, orange for buttons, coral for inputs, pink for checkboxes, peach for sliders, salmon for menus and amber for tabs. If the connection misbehaves, `playwriter session reset <id>` is the documented fix.

## Where Playwriter is the wrong tool

The extension is the single point of failure, and it is also the feature. If the tab is not connected, the CLI has no browser to drive. That means Playwriter is a poor fit for headless CI, for cron jobs on a server with no interactive Chrome, and for any pipeline where nobody can click an extension icon. The README's own framing supports this: the browser it targets is "your running browser", which presumes a person and a desktop session.

There is a second limitation that the README states as a benefit and that deserves to be read as a trade-off. The comparison table says Playwriter "can bypass" bot detection, with the parenthetical "disconnect extension". The mechanism for evading detection is therefore turning off the thing that makes Playwriter work. You cannot have both the extension connected and the anti-detection posture at the same time, and the documentation does not describe a way to toggle this per request.

A third gap is operational. The README documents `session new`, `session list` and `session reset`, and it shows state persisting across calls, but it does not document rollback of a session's state. If an agent writes a bad value into `state`, `session reset <id>` is described only as a fix for connection issues, not as a state rollback. Treat long-lived sessions as something you rebuild rather than rewind.

## Playwright MCP and BrowserMCP: the difference is the browser and the tool surface

The README compares Playwriter against two alternatives, and the comparisons are specific enough to be useful. Against Playwright MCP, the axis is the browser itself. Playwright MCP spawns a new Chrome; Playwriter uses yours. The consequences listed are extensions, login state, bot detection, and collaboration, where Playwriter puts the agent in the same window the user is working in rather than a separate one. If your task does not care about any of those four things, the distinction collapses and either tool will do.

Against BrowserMCP, the axis is the interface. The README counts 12 or more dedicated tools in BrowserMCP against one `execute` tool in Playwriter, and argues that the single tool keeps context usage low because the model does not need tool schemas, and that LLM knowledge is already there because the API is Playwright. That is a real architectural difference: BrowserMCP constrains what the agent can express to a fixed action set, while Playwriter hands over a general-purpose runtime and accepts the corresponding risk. A model that writes a bad Playwright snippet has more room to do damage than one choosing from twelve actions.

The README also compares Playwriter to the Playwright CLI, noting raw CDP access and native tab capture at 30 to 60fps against file-based tracing. It calls Playwriter's video recording "100x more efficient" than Playwright's, arguing that Playwright sends base64 images for every frame. That number is the project's own claim and the README does not show the measurement behind it.

## Licence, releases and the cost of keeping up

The repository is MIT licensed. The root `package.json` carries an empty `license` field, which is a packaging detail rather than a change to the terms, but if you vendor the workspace you should read the LICENSE file rather than the manifest. MIT places few obligations on you beyond preserving the notice; it also means there is no warranty, which matters when the tool drives a browser profile holding your real sessions.

The release cadence visible in the repository is uneven between the two artifacts. The CLI is versioned as `playwriter@0.5.0` and the extension as `extension@0.0.118`, both published on 2026-08-23, with the previous CLI release `playwriter@0.4.0` on 2026-06-25. The extension's version number is far ahead of the CLI's, which suggests the extension ships on its own schedule and updates through the Chrome Web Store rather than through npm. That has an upgrade consequence: a CLI update and an extension update are two separate actions, and the repository includes a `release:check-cli-version` script, which implies the two are expected to stay in step. The last push to the repository was on 2026-08-27.

For a team, the practical cost is not installation, which is a global npm package plus a store install. It is the version pairing. Before you pin the CLI in a lockfile, confirm which extension version it was tested against, because the README does not publish a compatibility table.

## Conclusion

Adopt Playwriter if your automation depends on sessions you are already signed into, or on extensions and cookies that a fresh Chrome would not have. Do not adopt it if you need unattended runs on a machine with no interactive Chrome, or if you cannot leave the extension connected. Before committing, verify three things: that `playwriter session list` shows the state keys you expect after a run, that disconnecting the extension actually changes how a target site responds to you, and that the CLI version installed by `npm i -g playwriter` is the one whose `execute` semantics your skill file was written against.

## FAQ

### What is the difference between Playwriter and Playwright?

Playwright is the automation library whose API Playwriter exposes; Playwriter is a Chrome extension plus CLI that runs Playwright snippets against your already-running browser rather than a freshly spawned one. The README frames the difference as logins, extensions and cookies being present instead of absent.

### Why is it called Playwright and not Playwriter?

The README does not discuss the origin of the Playwright name or its spelling. Playwriter is a separate project that reuses the Playwright API, so the two names are easy to confuse but refer to different things.

### Who is a playwriter?

In this context Playwriter is not a person but the tool: a Chrome extension and CLI from remorses/playwriter that lets agents control your own browser. The README describes it as running Playwright snippets in a stateful sandbox.

### What is Playwright used for?

Playwright is the browser automation API that Playwriter exposes inside its sessions, alongside `context`, `state` and Node.js globals. The README's comparison tables treat that full API as Playwriter's main advantage over fixed command-set browser tools.

## Sources

- [License: MIT](https://github.com/remorses/playwriter/blob/main/LICENSE)
- [Project website](https://playwriter.dev)
- [README](https://github.com/remorses/playwriter/blob/main/README.md)
- [Releases](https://github.com/remorses/playwriter/releases)
- [remorses/playwriter on GitHub](https://github.com/remorses/playwriter)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/remorses-playwriter