hyper-playwright
# hyper-playwright
[](https://www.npmjs.com/package/hyper-playwright) [](https://nodejs.org) [](https://opensource.org/licenses/MIT)
## [Tools](#tools) | [CLI flags](#cli-flags) | [Security](#security)
hyper-playwright is a zero-setup, token-efficient [Model Context Protocol](https://modelcontextprotocol.io) server for Playwright — with **in-page multi-cursor swarm execution**.
Standard `@playwright/mcp` behaves like a slow single-cursor remote control: the LLM sends one action, waits for a full ARIA tree dump, reads thousands of noisy tokens, then sends the next action. hyper-playwright moves the spatial reading and the parallel execution **into the browser runtime**: pages load with bloat blocked, elements arrive as compact Semantic Markdown with stable `[eN]` references, and batches plus multi-tab swarms complete in a single turn.
## Get Started
Choose the path that fits your workflow:
| | Best for | Command |
|---|---|---|
| **[MCP server](#mcp-server)** | AI agents and LLM-driven automation | `npx -y hyper-playwright` |
| **[One-click install](#install--uninstall)** | Fresh machine, nothing to clone | `curl -fsSL https://raw.githubusercontent.com/vamsireddy4/hyper-playwright/main/install.sh \| bash` |
| **[Install script](#install--uninstall)** | Registering every local MCP client at once | `./install.sh` |
| **[Web apps](#web-apps)** | Driving the browser over Streamable HTTP | `npx hyper-playwright --transport http --port 8787` |
| **[Exported tests](#export-tests)** | Turning a session into a regression test | `browser_export_test` |
---
## MCP server
The server boots in **under 50 ms** — the stdio transport connects before the browser is even launched. Chromium starts lazily on the first `browser_navigate` call, auto-detecting a locally installed Chrome or Edge and falling back to bundled Chromium.
### Setup
Add to your MCP client configuration:
```jsonc
{
"mcpServers": {
"hyper-playwright": {
"command": "npx",
"args": ["-y", "hyper-playwright"]
}
}
}
```
Headed mode with images and fonts enabled:
```jsonc
{
"mcpServers": {
"hyper-playwright": {
"command": "npx",
"args": ["-y", "hyper-playwright", "--headed", "--allow-media"]
}
}
}
```
Attach to a browser you already have open (Chrome → *Inspect* → *remote debugging port*):
```jsonc
{
"mcpServers": {
"hyper-playwright": {
"command": "npx",
"args": ["-y", "hyper-playwright", "--cdp", "9222"]
}
}
}
```
### How it works
Ask your agent to interact with any web page. It sees the page as compact Semantic Markdown instead of a verbose ARIA tree:
```markdown
<untrusted_web_content>
# Aurora Store
**URL:** https://example.com/shop
## Navigation
- [e1] "Home" (link)
- [e2] "Catalog" (link)
## Forms
- [e4] "Email address" (textbox, type=text)
- [e5] "Plan" (combobox)
</untrusted_web_content>
```
It acts on those `[eN]` references with `browser_batch`, fans multi-page work out with `browser_swarm`, and converts the finished session into a runnable test with `browser_export_test` — roughly 70% fewer tokens per turn than a raw ARIA dump.
---
## Tools
Six tools cover the whole workflow:
| Tool | What it does |
|---|---|
| `browser_navigate` | Open a URL, wait for settle, return Semantic Markdown. |
| `browser_batch` | Run several actions in one turn, with a `+ / -` diff. |
| `browser_swarm` | Open several URLs across pooled tabs, one merged report. |
| `browser_snapshot` | Re-distil the page, optionally with a PNG screenshot. |
| `browser_debug` | Read buffered console errors and failed requests. |
| `browser_export_test` | Replay the session as a `@playwright/test` spec. |
### Batch actions
```jsonc
{
"actions": [
{ "action": "fill", "ref": "e4", "value": "agent@example.com" },
{ "action": "check", "ref": "e6" },
{ "action": "select", "ref": "e5", "value": "pro" },
{ "action": "click", "ref": "e7" }
]
}
```
* `fill`, `type`, `check`, `uncheck`, `hover`, `focus` run **in parallel** with `Promise.all`, each with its own cloned ghost cursor.
* Everything else — `click`, `dblclick`, `drag`, `upload`, `select`, `press`, `scroll`, `reload`, `back`, `forward`, `dialogAccept`, `dialogDismiss`, `wait` — runs **sequentially**, since it can navigate or invalidate references.
* `drag` takes a destination ref in `value` (e.g. `"e8"`); `upload` takes file path(s); `reload` / `back` / `forward` / dialog actions take no ref.
* A failed click reports **what is actually in the way** (`⛔ blocked by [e9] "Cookie banner"`), and repeating one action with no DOM change raises a loop warning.
### Multi-tab swarm
```jsonc
{
"tasks": [
{ "url": "https://a.example", "query": "price", "label": "Product A" },
{ "url": "https://b.example", "query": "stock", "label": "Product B" }
],
"isolated": false
}
```
At most 3 tabs globally and 2 per domain, with 80–200 ms jitter against 429s and CAPTCHAs. Set `isolated: true` for authenticated or mutating work — each task then runs in a throwaway context cloned from the current `storageState`.
---
## Export tests
```jsonc
{ "title": "Buy a pair of headphones", "path": "./tests/buy.spec.ts" }
```
Every recorded action becomes a `role` + `name` locator so the spec survives re-renders:
```ts
import { test, expect } from '@playwright/test';
test('Buy a pair of headphones', async ({ page }) => {
await page.goto('https://example.com/shop');
await page.getByRole('textbox', { name: 'Email address' }).fill('agent@example.com');
await page.getByRole('button', { name: 'Add to cart' }).click();
});
```
---
## Install / uninstall
Two scripts, one command each. Both are idempotent and safe to re-run.
**One-click install** — no clone needed, a single command fetches the repo and runs the installer:
```bash
curl -fsSL https://raw.githubusercontent.com/vamsireddy4/hyper-playwright/main/install.sh | bash
# with flags: ... | bash -s -- --headed --allow-media
```
This clones to `~/hyper-playwright` (override with `HP_DEST`) and then runs the same steps as `./install.sh`. Re-running it pulls the latest code and reinstalls.
From a checkout:
```bash
./install.sh # headless (default)
./install.sh --headed # visible browser window
./install.sh --headed --allow-media
```
`install.sh` installs dependencies, builds the CLI, links it onto your `PATH` as `hyper-playwright`, and registers the server with every MCP client it finds — **Claude Code**, **opencode** and **Claude Desktop**.
```bash
./uninstall.sh # removes the binary and every client registration
./uninstall.sh --purge # also deletes ~/.hyper-playwright (cookies + logins)
```
Without `--purge` the persistent browser profile is deliberately **kept**.
---
## CLI flags
| Flag | Default | Purpose |
|---|---|---|
| `--headed` | off | Show the browser window. |
| `--cdp <url\|port>` | – | Attach to a running browser. |
| `--browser <name>` | auto | `chrome`, `msedge` or `chromium`. |
| `--allow-media` | off | Stop blocking images / fonts / media. |
| `--allow-file-urls` | off | Permit `file://` navigation. |
| `--profile <dir>` | `~/.hyper-playwright/profile` | Persistent browser profile. |
| `--max-tabs <n>` | `3` | Concurrent swarm tabs (1–3). |
| `--transport <name>` | stdio | `stdio` or `http`. |
| `--port <n>` | `8787` | HTTP port for `--transport http`. |
All logs go to **stderr**. `stdout` carries JSON-RPC frames only — enforced by a unit test.
### Web apps
```bash
npx hyper-playwright --transport http --port 8787
```
Your app connects to `POST http://127.0.0.1:8787/mcp`. Keep it on `127.0.0.1` unless you have added your own auth/TLS layer.
---
## Security
Page content can try to talk the agent into doing something it should not. Three defences are on by default.
| Defence | Behaviour | Opt-out |
|---|---|---|
| **Injection filtering** | Text matching common injection patterns is dropped from the payload; the count is reported. | — |
| **`file://` blocked** | Navigation is refused unless `--allow-file-urls` is passed. | `--allow-file-urls` |
| **Constrained writes** | `browser_export_test` writes only inside the working directory or a temp directory. | `--allow-write-anywhere` |
Every payload is wrapped in `<untrusted_web_content>` tags so the host can tell page-derived text apart from instructions.
---
## Cross-platform support
| | macOS | Windows | Linux |
|---|---|---|---|
| Headless / headed | ✅ | ✅ | ✅ |
| Auto-detect Chrome / Edge | ✅ | ✅ | ✅ |
| Bundled Chromium fallback | ✅ | ✅ | ✅ |
| `--cdp` attach | ✅ | ✅ | ✅ |
| Sandbox flags | – | – | auto |
Sandbox flags (`--no-sandbox`, `--disable-setuid-sandbox`, `--disable-dev-shm-usage`) apply **only** on Linux. The persistent profile lives at `~/.hyper-playwright/profile`. Process cleanup uses `taskkill /F /T` on Windows and a process-group `SIGKILL` elsewhere.
## Development
```bash
npm install
npm run build # tsup → dist/index.js (single ESM file) + dist/lib.js
npm run typecheck # tsc --noEmit, zero errors
npm test # 22 unit tests (node:test, no extra dependencies)
npm run verify # full end-to-end MCP suite against a local test site
```
`npm run verify` boots the real binary over stdio and exercises the handshake, navigation, batch execution, obstacle diagnostics, overlay handling, swarm execution, isolated contexts, screenshots, debug buffering, test export, media blocking, the security guardrails, and `--cdp` attachment.
## Resources
* [SPEC](SPEC.md) — full project specification
* [Install script](install.sh) / [Uninstall script](uninstall.sh)
* [CI workflow](.github/workflows/ci.yml)
* [npm package](https://www.npmjs.com/package/hyper-playwright)
* [Model Context Protocol](https://modelcontextprotocol.io)
* [Playwright](https://playwright.dev) — the automation library underneath
## License
MIT
TDQS
Scored across 6 tools
Each tool targets a distinct phase of browser automation: navigate (single URL), swarm (multi-URL), batch (actions), snapshot (refresh state), debug (diagnostics), export_test (test generation). The only mild overlap is navigate vs. swarm, but the descriptions clearly separate one-page from many-page use.
All names share the browser_ prefix and snake_case, so the family is obvious. There is a slight mix of noun-style labels (snapshot, batch, swarm) with verb-style ones (navigate, debug), but the pattern stays readable and predictable.
Six tools cover the whole browse-act-inspect-export loop without filler. Each has a clear role, and no operation feels redundant or missing from the set.
Navigation, batched interaction, state refresh, diagnostics, multi-page scraping and test export give near-full lifecycle coverage. Minor gaps exist, such as explicit session/tab cleanup or a standalone screenshot/download control, but snapshot's PNG option and batch actions cover most needs.