@drakulavich/bowser Cli

GitHub Actions

A Bun-native, drop-in command-compatible alternative to Microsoft playwright-cli for AI agents.

Devops Browser Automation Developer Tools

Add to Cursor Add to VS Code Run on PlugMCP

1{2  "mcpServers": {3    "drakulavich-bowser-cli": {4      "command": "npx",5      "args": [6        "-y",7        "@drakulavich/[email protected]"8      ]9    }10  }11}

.cursor/mcp.jsonMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @drakulavich/[email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add drakulavich-bowser-cli -- npx -y @drakulavich/bowser-cli@0.12.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "drakulavich-bowser-cli": {4      "command": "npx",5      "args": [6        "-y",7        "@drakulavich/[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.12.0
Last checked: 2026-10-28

Stars: —
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install @drakulavich/bowser Cli?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does @drakulavich/bowser Cli need an API key?

No required environment variable is listed on this record.

What transport does @drakulavich/bowser Cli use?

@drakulavich/bowser Cli runs locally over stdio.

When was @drakulavich/bowser Cli last checked?

Last checked 2026-10-28. A Bun-native, drop-in command-compatible alternative to Microsoft playwright-cli for AI agents.

From the publisher

Documentation

Bowser

A Bun-native, drop-in command-compatible alternative to Microsoft playwright-cli for AI agents. Same commands, same flag syntax, same snapshot YAML — replace playwright with bowser and existing playwright-cli skills work unchanged.

Built on Bun.WebView (new in Bun 1.3.12), it drives the native WebKit engine on macOS, so there is no browser to download: nothing to install beyond Bun itself. bowser runs on macOS only. If you need Chromium, or Linux or Windows, use playwright-cli.

Why

What sets it apart from playwright-cli:

Bun-native. Runs on Bun, no Node or Playwright install.
Fewer tokens than playwright-cli. In the agent benchmark (10 browser tasks, 3 runs each, Claude Sonnet 5.5, 2026-10-21), an agent used 413k tokens and $0.41 with bowser against 445k and $0.51 with playwright-cli, summed over the per-task medians. Both passed all 30 runs.
Persistent sessions. Each named session keeps a long-lived browser process so multi-step flows survive between commands.

Install

bowser runs on macOS only (it needs WebKit, which Bun.WebView provides only there).

# From npm
npm install -g @drakulavich/bowser-cli

# ...or directly from source
git clone https://github.com/drakulavich/bowser.git
cd bowser
bun install
bun link                     # exposes `bowser` on $PATH

Bun ≥ 1.4.4 must be on your PATH: the npm package runs src/cli.ts with the bun it finds there. npm does not enforce that, so on an older Bun a command that would start a session fails with the error "bowser requires Bun >=1.4.4 (found )" (exit 1).

bowser is distributed only through npm and from source; releases no longer attach binaries. If you used a release binary, run bowser close --all with it, delete it, then npm i -g @drakulavich/bowser-cli.

On another platform, any command that would start a session fails with the error "bowser requires macOS (WebKit)" (exit 1).

Upgrading

Open sessions survive an upgrade. The first command after it finds the daemon the old bowser started, stops it, and opens the session again with its profile and its page. It then runs as asked, and prints one line on stderr first: "bowser: session '' restarted for bowser (was ): page reloaded at ; refs cleared, run 'bowser snapshot'". A session opened without --persistent or --profile adds "cookies and storage were lost (no --persistent)": those lived only in the old daemon. A ref from before the upgrade fails with "is from a page that is no longer loaded", so take a new snapshot. The page is the one the old daemon showed, and the session keeps the BOWSER_OP_TIMEOUT_MS it was opened with. A session started by bowser 0.12 or older gets the default 30 s instead, whatever the first command after the upgrade sets. The restart has its own budget, so that first command can take up to twice the budget, plus a few seconds to stop the old daemon.

From 0.12.0 on, a running bowser mcp server hands its calls over to the installed version on the first tool call after the upgrade, and the restart line comes first in that call's text. Its tool list stays the one the client got when it connected, so a new command shows up once the client restarts the server. A server started by 0.11 or older can't hand over: restart it once after the upgrade.

A daemon newer than the bowser you run (after a downgrade) is still refused: "session '' is running bowser (this is ); run 'bowser close -s ', then open it again" (exit 1).

Screenshots

Screenshots are written as PNG files. bowser screenshot --filename out.png writes to out.png (relative paths resolve against your current directory); without --filename it writes screenshot-<session>.png, auto-incrementing (-1, -2, …) if that file already exists. The reply names the absolute path written and the PNG's size in pixels (wrote /…/out.png (1600×1200), {"ok":true,"filename":"/…/out.png","width":1600,"height":1200}); snapshot --filename names the path too. The size follows the display's pixel ratio: an 800×600 viewport is 1600×1200 on a Retina display and 800×600 on one at ratio 1. --scale=N fixes it at innerWidth·N × innerHeight·N by scaling the capture down, or fails with exit code 1 when N is above the display's ratio, since bowser cannot render more pixels than the display has. A capture is the viewport, as in playwright-cli without --full-page: bowser has no full-page or element-bounded screenshots (Bun.WebView captures only the viewport). Use resize to capture more. WebKit cannot capture a viewport whose pixels fill 4 GiB. On a Retina display (pixel ratio 2) that is reached only near resize's maximum: resize 16384 16384 cannot be captured, resize 16384 16383 can. screenshot then fails with exit code 1 and names the size to resize to. Before it captures, screenshot waits up to 5 s for the web fonts the page itself has asked for (not those of its iframes), such as a font first used by text a script added after the page loaded. If they are still loading after 5 s it captures anyway and adds ; fonts still loading to the reply ("fontsLoading":true under --json): the image may show text in a fallback font or none at all, so retry, or check that the font URL answers.

Quickstart

bowser open https://example.com          # navigate, save state
bowser snapshot                          # the page's aria tree, with [ref=eN]
bowser click e3                          # click a ref
bowser fill e5 "[email protected]"        # fill a form field
bowser press Enter                       # submit
bowser screenshot --filename=shot.png    # capture
bowser close                             # end session

Each session runs one persistent browser process (spawned lazily on first command, addressed over a Unix socket). Commands attach, run, and detach — so typed text, modals, dynamic DOM, cookies, and auth all survive across invocations. Session state lives under ~/.bowser/sessions/<name>/. Several commands started at once on a new session still share one browser.

If the page's web process crashes, WebKit relaunches it and reloads the page once. That reload looks like the page reloading itself, so bowser does not report it: page state is gone, and old refs fail with not found in the current page snapshot. If the process dies again, WebKit does not reload the page, and every page command fails with the page crashed (its web process exited); run 'bowser reload' or 'bowser goto <url>' (exit 2). bowser does not reload it for you; reload, goto or open <url> recover it.

If a session's browser exits (it crashed, or was killed), every command but open and close fails with session '<name>' is not open (its browser exited); run 'bowser open' (exit 1), or gives the recorded bowser open --persistent / bowser open --profile=<dir> command when session state records a profile; paths are quoted when needed. State from an older bowser has no profile record, so bowser falls back to checking the default profile directory. This avoids quietly starting an empty browser. bowser open (with the same profile option again, when one was recorded) starts it anew; bowser close clears it. A session that never ran a browser still starts one on its first command.

Multiple sessions

bowser -s=login open https://app.example.com/login
bowser -s=login fill  e1 "[email protected]"
op read op://vault/app/password | bowser -s=login fill e2 --stdin
bowser -s=login click e3

Commands on one session run one at a time: when several clients (parallel shell calls, two MCP servers) send commands to the same session, each waits its turn and runs whole.

Persistent profiles

A session's browser store is in memory by default: close (or a crash) loses its logins. A persistent profile is the way to keep cookies, and so logins, between sessions: bowser has no cookie commands, and state-save/state-load carry only localStorage. Open the session with --persistent to keep cookies, localStorage and IndexedDB on disk, like playwright-cli open --persistent:

bowser -s=app open https://app.example.com/login --persistent   # profile in ~/.bowser/profiles/app/
bowser -s=app close                                              # the profile stays
bowser -s=app open https://app.example.com --persistent         # still logged in
bowser -s=work open https://app.example.com --profile=./profiles/work   # a directory of your choice

The profile lives outside ~/.bowser/sessions/<name>/, so close leaves it alone. Delete it with rm -rf ~/.bowser/profiles/<name> (or your --profile directory).
The store is chosen when the session's browser starts. open --persistent on a session that is already running with another store fails with exit 1; run bowser close first. open without the flag reuses a running persistent session.
One profile directory serves one running session at a time; sharing it between two is unsupported.
A persistent store needs macOS 15.2 or later.

Dialogs

bowser answers every alert, confirm and prompt the moment it opens, so no command ever waits on a dialog. Without an answer set, the dialog is dismissed: confirm returns false and prompt returns null. To accept one, set the answer before the action that opens it:

bowser dialog-accept            # the next dialog is accepted (confirm → true)
bowser click e7                 # the click that opens it
bowser dialog-accept "Ann"      # a prompt gets "Ann"; with no text, its own default value
bowser click e8

### Modal state
- ["prompt" dialog with message "Your name?"]: accepted

The command that caused the dialog reports it under ### Modal state. With --json it reports it as "dialogs": [...]. If the command fails, the report follows its error on stderr and the exit code is unchanged. dismissed (run dialog-accept before the action to accept it) means no answer was set. An answer covers one dialog and is dropped when the page navigates.

Differences from playwright-cli:

In playwright-cli, the dialog stays open and dialog-accept answers it after the action. In bowser, dialog-accept after the action prepares the next dialog. It does not answer the one already reported.
WebKit has no dialog events, so bowser replaces window.alert/confirm/prompt in the page, and in every same-origin iframe it can reach, before it acts there. A dialog in such an iframe is reported like the page's own and takes the prepared answer. A dialog that fires between commands (a timer) is reported by the next command that prints dialogs, even when that command leaves the page (reload, goto, open, go-back, press Enter on a form).
A function the page defined itself (window.confirm = m => …) is left alone and runs, as in playwright-cli; its calls are not dialogs and are not reported.
A page function made with .bind() from the browser's own (window.confirm = confirm.bind(window)) looks native to bowser: the shim replaces it, and the dialog is reported.
Not reported, and dismissed by WebKit:
- a dialog the page opens while loading, before bowser's first command on that document;
- a dialog in a cross-origin iframe, or in an iframe that loaded after bowser's last command;
- a dialog opened through a reference the page saved at load time (const c = window.confirm), including a page wrapper around it (window.confirm = m => c(m)).
In each of these cases a prepared answer stays set until the next dialog bowser sees or a navigation.
A dialog whose handler then navigates the page (if (confirm('Leave?')) location = …) is answered but not reported, because the report leaves with the old page.
beforeunload is not handled.

Snapshot output

snapshot prints the page's full accessibility tree in playwright-cli's format: headings, text, state such as [checked] or [active], /url and /placeholder props, and an eN ref on every visible element, not only the interactive ones. This is the todo fixture in tests/fixtures/:

### Page
- Page URL: http://localhost:52047/todo-app.html
- Page Title: Bowser Todo
### Snapshot
```yaml
- generic [active] [ref=e1]:
  - heading "Todos" [level=1] [ref=e2]
  - generic [ref=e3]:
    - textbox "New todo" [ref=e4]:
      - /placeholder: What needs doing?
    - button "Add" [ref=e5] [cursor=pointer]
  - list "Todo list" [ref=e6]:
    - listitem [ref=e7]: No todos yet
  - generic [ref=e8]:
    - generic [ref=e9]: 0 items left
    - button "Clear completed" [ref=e10] [cursor=pointer]
```

A ref stays the same across snapshots of one document while the element's role and name do not change; new elements get the next free number, so gaps are normal. After fill e4 "buy milk" and click e5, the list above becomes listitem [ref=e11] holding checkbox "Toggle buy milk" [ref=e12], and e5, e10 still name the same buttons. A navigation or reload starts again at e1.

Password field values are never shown: a filled <input type="password"> prints as textbox "Password" [ref=e3] with no value, state.json does not store it, and it adds nothing to another element's name. This is a deliberate difference from playwright-cli, which prints the value.

An action on a ref whose element a re-render removed fails at once with ref 'eN' not found in the current page snapshot. Try capturing new snapshot. and exit code 1, as in playwright-cli. A ref from another page (from before a navigation or reload, or from the page you left before go-back) fails the same way with ref 'eN' is from a page that is no longer loaded; take a new snapshot. Run snapshot again and use the new refs. A pushState or #hash change keeps the page, and its refs keep working.

An action on a ref whose element changed its role or name since the snapshot (a Buy A button that relabelled itself) also fails, exit code 1, before it touches the page: ref 'e2' now points to button "Delete account", not button "Buy A"; take a new snapshot. click and fill on a ref whose centre another element covers (a backdrop, or a + button the page put where Add was) fail the same way and name what covers it: ref 'e2' (button "Add to cart") is covered by generic <div> at its click point; take a new snapshot or close what covers it. A playwright-cli frame ref such as f1e3 fails with 'f1e3' is a playwright-cli frame ref; bowser does not snapshot iframe contents.

--depth=N prints N levels below the first line: a node at the limit drops its children but keeps its inline text value and its prop lines (/url, /placeholder). --depth=0 or no flag prints the whole tree. Iframe contents and shadow DOM are not walked: an iframe prints as a leaf with a ref.

JSON output for agent pipelines

--json snapshot prints {"snapshot": "<tree>"}: the tree text alone, without the ### Page wrapper. snapshot --filename=f writes the ### Page text to f, with or without --json, and answers wrote /…/f ({"ok":true,"filename":"/…/f"} under --json, with "dialogs" when a dialog was answered).

bowser --json snapshot | jq -r .snapshot | grep 'button'

Command reference

Command	Description
`open [url] [--persistent] [--profile=dir]`	Start session; navigate if URL given. `--persistent` keeps cookies, `localStorage` and IndexedDB in `~/.bowser/profiles/<session>/` across `close` and restarts; `--profile=dir` keeps them in `dir` instead (implies `--persistent`). See Persistent profiles.
`goto <url>`	Navigate within current session. For `open` and `goto` alike, a URL without a scheme gets one, as in `playwright-cli`: `http://` for `localhost`, `127.0.0.1` and `[::1]` (`localhost:3000/x` → `http://localhost:3000/x`), `https://` for any other host (`example.com` → `https://example.com`). A URL with a scheme (`http:`, `file:`, `about:`, `data:`, …) is used as typed. Unlike `playwright-cli`, `127.0.0.1` gets `http://`, not `https://`.
`snapshot [--filename=f] [--depth=N]`	Full aria tree in `playwright-cli`'s format, with `eN` refs; `--depth=N` limits the levels printed (`0` or unset is unlimited)
`markdown [ref] [--filename=f]`	The page as Markdown, for reading. When the page offers its own Markdown (a claude.ai artifact's source, or `<link rel="alternate" type="text/markdown">`), that text; otherwise `<main>` (or the body without one) converted: headings, paragraphs, lists, tables, links, code, emphasis, image `alt`, with hidden content and form controls left out. With a ref, only that element is converted, without scrolling the page. `--json` gives `{"markdown":"…","source":"page"
`click <ref>`	Click an element. A disabled element (the snapshot's `[disabled]`: a disabled control or `<fieldset>`, or `aria-disabled="true"` on it or an ancestor) fails at once with `ref 'eN' is disabled`, exit 1, and is not clicked; `playwright-cli` waits out its timeout
`fill <ref> <text>` / `fill <ref> --stdin`	Focus, clear, type. `--stdin` reads the text from piped input and drops one trailing newline, so a secret never appears in the process arguments: `op read op://vault/site/password \| bowser fill e4 --stdin`. The text is never echoed, with or without `--stdin`: `filled e4 (textbox "Password")`, and `--json` answers `{"ok":true,"ref":"e4","element":{"role":"textbox","name":"Password"}}`. `--stdin` is not offered over MCP. A disabled (a disabled `<fieldset>` included) or `readonly` field fails with `ref 'eN' is not an editable element (disabled)` or `(readonly)`, exit 1, value untouched; `playwright-cli` waits out its timeout. A `date`, `time`, `datetime-local`, `month`, `week` or `color` input gets the value set directly, as `playwright-cli` does (`fill e9 2024-01-02`); one it does not keep fails with `ref 'eN' did not accept the value for input[type=<type>]`. On `type=number`, text that is not a number fails with `ref 'eN' needs a number (input[type=number])`. Both exit 1 and leave the value as it was; no error repeats the text.
`type <text>`	Type into focused element. The text is never echoed: it prints `typed N characters` (`typed 1 character` for one), counting code points, and `--json` answers `{"ok":true,"length":N}`. For `fill` and `type` alike, a browser error that quotes the text is replaced by `<command>: the browser's error message was withheld because it contained the entered text`; a dialog message the page shows is page content and is printed as is
`press <key>`	Press a keyboard key, or a combination as in `playwright-cli`: `Shift+Tab`, `Meta+a`, `Shift+Meta+ArrowRight`. Modifiers are `Shift`, `Control`, `Alt`, `Meta` and `ControlOrMeta` (which is `Meta`: bowser runs on macOS). `Tab` moves focus to the next field, as the browser's own Tab does, and types nothing; `Shift+Tab` moves it back. The key is one character or `Enter`, `Tab`, `Space`, `Backspace`, `Delete`, `Escape`, `ArrowLeft`, `ArrowRight`, `ArrowUp`, `ArrowDown`, `Home`, `End`, `PageUp`, `PageDown`. Known differences from `playwright-cli`: WebKit through `Bun.WebView` cannot press `F1`–`F12`, a modifier alone (`Shift`) or a key code (`KeyA`, `NumpadEnter`), so these fail with `usage:` (exit 1); `Meta+c`, `Meta+x` and `Meta+v` reach the page as keydowns but do not copy, cut or paste. Keys follow macOS: `Control+a` moves to the start of the line, `Meta+a` selects all, `Meta+z` undoes
`hover <ref>`	Hover an element
`select <ref> <value>`	Choose a `<select>` option: the first, in document order, whose value or label is `<value>` (`select e3 Red` picks `<option value="r">Red</option>`). With no such option it fails at once with `ref 'eN' has no option "<value>"` (exit 1) and the select keeps its value; `playwright-cli` waits out its timeout
`check <ref>` / `uncheck <ref>`	Check or uncheck a checkbox or radio button. A disabled one fails like `click`. `uncheck` on a checked radio fails with `ref 'eN' is a radio button; select another option in its group to uncheck it`, exit 1; on an unchecked one it succeeds and does nothing. An `aria-checked="mixed"` checkbox is unchecked for `check` (one click, as in `playwright-cli`) and checked for `uncheck`, which clicks it until it reads `false` (`playwright-cli` leaves it mixed)
`dialog-accept [text]` / `dialog-dismiss`	Set the answer for the next `alert`/`confirm`/`prompt` (a prompt gets `text`, default its own value). Run it before the action; without one a dialog is dismissed. The action reports each dialog under `### Modal state`.
`screenshot [--filename=f] [--scale=N]`	Screenshot of the viewport (PNG); no full-page capture. Waits up to 5 s for the page's own web fonts (not its iframes'); `; fonts still loading` when they did not arrive
`resize <width> <height>`	Set the viewport size in pixels, each side 1 to 16384 (`Bun.WebView`'s limit)
`go-back` / `go-forward` / `reload`	Navigation
`wait-for --url <part>` / `wait-for --text <text>`	Wait until the page URL (`location.href`) or its visible text (`document.body.innerText`) contains the value: a client-side route change or text that arrives after a `click` has answered. Prints the URL and saves it to the session. Bounded by the command's budget; when it runs out it fails with `wait-for: no URL containing '<part>' after <ms>ms; the page is at <url>` (exit 2). One of the two flags, not empty. `playwright-cli` has no such command; Playwright MCP's `browser_wait_for` is the closest.
`list`	List sessions whose daemon answers. A session whose daemon is gone is not listed.
`close [name]`	End a session and remove its directory (defaults to `--session`; positional name overrides). Fails if the browser process cannot be confirmed stopped, including a daemon from bowser 0.5 or older that does not answer: it wrote no pidfile, so `close` exits 2 and keeps the session until you end the process yourself (the error says how). A name with no session answers `session '<name>' is not open` (exit 0), as `playwright-cli` does, so a typo in `-s` does not look like a close.
`close --all`	Close every open session; a directory a refused start left behind is removed but not listed. If one cannot be closed, it still tries the rest, then fails (exit 2) naming each such session with its reason and listing the ones it closed
`localstorage-list`	List all `localStorage` entries (`key=value` per line, or JSON with `--json`)
`localstorage-get <key>`	Read a `localStorage` value
`localstorage-set <key> <value>`	Write a `localStorage` entry
`localstorage-delete <key>`	Remove a `localStorage` entry
`localstorage-clear`	Clear all `localStorage` entries
`sessionstorage-list`	List all `sessionStorage` entries (`key=value` per line, or JSON with `--json`)
`sessionstorage-get <key>`	Read a `sessionStorage` value
`sessionstorage-set <key> <value>`	Write a `sessionStorage` entry
`sessionstorage-delete <key>`	Remove a `sessionStorage` entry
`sessionstorage-clear`	Clear all `sessionStorage` entries
`eval <expression>`	Evaluate a JS expression in the current page; prints the result
`run-code <code>`	Run JavaScript in the current page and print the result. One expression is evaluated as one (`run-code "(() => { return 5 })()"` prints `5`); any other code is the body of an async function, so use `return` for the result, and `await` works (`run-code "await new Promise(r => setTimeout(r, 100)); return document.title"`). Unlike `playwright-cli`'s `run-code`, which calls a function with a Playwright `page` in Node, it runs in the page: a result that is a function, such as `async page => …`, fails with `run-code runs JavaScript in the page and has no Playwright 'page'; write statements and use return` (exit 1)
`state-save <file>`	Save the current origin's localStorage to a Playwright-compatible `storageState` JSON file. Its `cookies` array is always empty: bowser has no cookie access (use `open --persistent` to keep logins). A page with no origin (`about:blank`) saves no origins.
`state-load <file>`	Restore localStorage from a `storageState` file. It restores origins matching the current page and reports the others skipped. Cookies in the file are skipped, with one line on stderr. A missing, invalid or wrongly shaped file (`storageState.origins: expected array, got object`) restores nothing and exits 1.
`mcp`	Run a Model Context Protocol stdio server exposing every command above as an MCP tool.

With --json, and so over MCP, click, fill, hover, select, check and uncheck name the element the ref pointed to, with the role and name its snapshot gave: click e724 answers {"ok":true,"ref":"e724","element":{"role":"button","name":"Add to cart"},"url":"…"}.

Global flags: -s=<name> / --session=<name>, --json, -h/--help, --version (prints the version and runs nothing). A session name uses letters, digits, ., _ and -, and does not start with . or -. It is at most 255 characters, or fewer under a very long HOME: <HOME>/.bowser/sessions/<name>/pid.<pid>.tmp must fit Bun's 1016-character path limit. A longer name is a usage error that gives the limit.

bowser <command> --help (or -h anywhere before --) prints that command's usage, arguments and flags and runs nothing; bowser mcp --help does not start the server. After --, --help is text like any other argument.

A command given more arguments than it takes fails before it runs, with usage: too many arguments for '<cmd>': expected <n>, received <m> and exit code 1. Quote an argument that has spaces: bowser eval "1 + 1", bowser fill e4 "hello world". Words after -- count too, so fill e1 -- a b is too many. bowser mcp with any extra word fails the same way and does not start the server.

A command given fewer arguments than it requires fails the same way, with its usage line: bowser select e3 fails with usage: bowser select <ref> <value> and exit code 1. An empty argument is a value, as in playwright-cli: bowser select e3 "" selects the option whose value is empty, and bowser localstorage-set k "" stores an empty string.

MCP bridge

bowser mcp runs a Model Context Protocol server over stdio, exposing every browser command as an MCP tool — so MCP clients (Claude Desktop, etc.) can drive the browser without shelling out. Each tool maps 1:1 to a CLI command and takes an optional session argument; outputs are the same JSON as --json mode.

Arguments are checked against the tool's input schema. A wrong type (session: 42, an object where a string belongs, persistent: "false") or a key the tool does not have is refused with an isError result starting usage:, and nothing runs. Where the schema says string, a finite number is also taken (resize {width: 800, height: 600}), and null is the same as leaving the argument out.

{
  "mcpServers": {
    "bowser": { "command": "bowser", "args": ["mcp"] }
  }
}

Notes:

The server is a thin client of the same per-session daemons the CLI uses; the first tool call on a fresh session spawns one.
Relative file paths (screenshot, snapshot filename, state-save, state-load) resolve against the server's working directory. If the client starts it from / or another directory it cannot write, the server uses <os.tmpdir()>/bowser-mcp instead ($TMPDIR/bowser-mcp). Replies name the absolute path written. An absolute path is used as given.
The protocol is hand-rolled (newline-delimited JSON-RPC) with zero runtime dependencies. It speaks MCP 2025-11-25, 2025-06-18 and 2024-11-05: initialize answers with the client's version when it is one of these, and with 2025-11-25 otherwise. The stateless 2026-07-28 revision is not implemented; its server/discover probe gets -32601 Method not found, on which a client falls back to initialize.
initialize, ping, tools/list and notifications are answered at once, even while tool calls run.
A JSON-RPC batch (an array) or a line that is not a JSON object gets one -32600 Invalid Request error with id: null; nothing in a batch runs. MCP 2025-06-18 has no batching.
A request without a string method gets -32600 Invalid Request with its id, and a tools/call of a tool the server does not have gets -32602 Unknown tool. A response from the client (a message with result or error) gets no answer.
Tool calls for different sessions run concurrently; calls for the same session run one at a time, in the order they arrived. Responses may therefore arrive out of order (JSON-RPC matches them by id).
The server exits when stdin closes and every running call has answered. A client that stops reading stdout is gone: the server exits 0 at its next response, and calls still queued never run. A browser operation already running finishes in its daemon.
notifications/cancelled drops the call: one still queued behind its session never runs, and a running one finishes but its result is discarded. Either way no response is sent for it, per the MCP spec. A browser operation that has already started is not undone — a cancelled click may still have clicked, and the session's next call waits for it to finish.

How it works

bowser open spawns a per-session daemon holding a Bun.WebView, navigates, and saves {url, title} to ~/.bowser/sessions/<name>/state.json.
bowser snapshot runs a snapshot script in the page that walks the DOM into an aria tree (roles, names, text, refs) and keeps a reference to each ref's element in the page; src/snapshot.ts renders that tree as YAML. Refs are persisted with the CSS path each element had (#id when safe, otherwise an nth-of-type chain), e.g. e3 → html > body > button:nth-of-type(2).
bowser click e3 resolves the ref from state, then in the page: the snapshot script kept a reference to each ref's element, so the command checks that element is still in the document and computes its CSS path afresh (a stale ref fails here, before anything is clicked). It then dispatches the click via the daemon, using Bun.WebView's built-in actionability auto-wait — no polling, no hard-coded timeouts.

bowser's scripts run in the page's own JavaScript world, and WebKit returns their results through the page's JSON.stringify. bowser sets aside the builtin patches that legacy libraries such as Prototype.js install, and it refuses a page that replaced JSON.stringify. It does not defend against a page written to deceive automation: such a page can forge any check made from inside it.

Environment variables

Variable Effect

BOWSER_OP_TIMEOUT_MS Per-command timeout in milliseconds (default 30000; 0 disables). It covers the whole command: each step of a command gets the time the command has left, and time spent queued behind another command counts, so a wedged browser makes a command exit with a timeout error instead of blocking forever. The daemon reads it once, when the session starts, and a value set on a later command applies to that command only when it is smaller. To raise it, close the session and open it again with the new value. An upgrade restart keeps it (see "Upgrading"). A timeout names the command and, when it differs, the step that overran: 'fill' timed out after 3000ms (in its 'click' step) (exit 2). When the time runs out after an action was sent, the timeout says the action may have reached the page: 'click' timed out after 3000ms; the click may have been delivered, check the page before retrying. Once the action has returned it says the click was delivered, and waiting for the page it opened when the action started a navigation that has not loaded yet. Retrying without checking may act twice. If a timed-out command is still running 2 s later (or after the budget, if shorter), the daemon reloads the page once to free the browser (in a session that has not loaded a page yet, where a reload does nothing, it leaves the blank page instead). A command whose client goes away (killed, or its terminal closed) gets 5 s more to finish once its connection closes (or what is left of its budget, if less), and is then ended the same way, with or without a budget. If the command outlives that reload, every other command fails at once with session is stuck: '<cmd>' is still running after a reload; run 'bowser close' (exit 2) until it ends; close always works. A command sent during the 2 s and the reload waits for them, so the first such failure can take up to 12 s after the timeout (up to 22 s in a session that has not loaded a page yet, where leaving the blank page can take two 10 s tries). An action such as click or fill on a page still loading a navigation that an earlier command started waits for it, and fails with page is still loading <url>; retry later, or run 'bowser close' (exit 2) if the time runs out first. If the daemon itself stops answering mid-command (frozen or swapped out), the command gives up 2 s after its budget with daemon for session '<s>' did not answer; run 'bowser close -s <s>' to stop it (exit 2), and bowser close -s <s> ends it.

BOWSER_DAEMON_DEBUG 1 writes the output of a session daemon that this command starts to ~/.bowser/sessions/<session>/daemon.log, for debugging a daemon that fails to start. close deletes it with the session directory.

Variable	Effect
`BOWSER_OP_TIMEOUT_MS`	Per-command timeout in milliseconds (default `30000`; `0` disables). It covers the whole command: each step of a command gets the time the command has left, and time spent queued behind another command counts, so a wedged browser makes a command exit with a timeout error instead of blocking forever. The daemon reads it once, when the session starts, and a value set on a later command applies to that command only when it is smaller. To raise it, `close` the session and `open` it again with the new value. An upgrade restart keeps it (see "Upgrading"). A timeout names the command and, when it differs, the step that overran: `'fill' timed out after 3000ms (in its 'click' step)` (exit 2). When the time runs out after an action was sent, the timeout says the action may have reached the page: `'click' timed out after 3000ms; the click may have been delivered, check the page before retrying`. Once the action has returned it says `the click was delivered`, and `waiting for the page it opened` when the action started a navigation that has not loaded yet. Retrying without checking may act twice. If a timed-out command is still running 2 s later (or after the budget, if shorter), the daemon reloads the page once to free the browser (in a session that has not loaded a page yet, where a reload does nothing, it leaves the blank page instead). A command whose client goes away (killed, or its terminal closed) gets 5 s more to finish once its connection closes (or what is left of its budget, if less), and is then ended the same way, with or without a budget. If the command outlives that reload, every other command fails at once with `session is stuck: '<cmd>' is still running after a reload; run 'bowser close'` (exit 2) until it ends; `close` always works. A command sent during the 2 s and the reload waits for them, so the first such failure can take up to 12 s after the timeout (up to 22 s in a session that has not loaded a page yet, where leaving the blank page can take two 10 s tries). An action such as `click` or `fill` on a page still loading a navigation that an earlier command started waits for it, and fails with `page is still loading <url>; retry later, or run 'bowser close'` (exit 2) if the time runs out first. If the daemon itself stops answering mid-command (frozen or swapped out), the command gives up 2 s after its budget with `daemon for session '<s>' did not answer; run 'bowser close -s <s>' to stop it` (exit 2), and `bowser close -s <s>` ends it.
`BOWSER_DAEMON_DEBUG`	`1` writes the output of a session daemon that this command starts to `~/.bowser/sessions/<session>/daemon.log`, for debugging a daemon that fails to start. `close` deletes it with the session directory.

Tests

bun run check                                  # typecheck, lint, then unit tests
bun run typecheck                              # tsc
bun run lint                                   # Biome (import cycles, layer rules) and Knip (unused files, exports)
bun test                                       # unit + command tests with a fake daemon
BOWSER_E2E=1 bun test                          # + end-to-end on WebKit
BOWSER_E2E=1 BOWSER_E2E_NET=1 bun test         # + live-internet e2e (GitHub search)

End-to-end examples included:

tests/e2e.test.ts — open/snapshot/click on a data: URL (no network)
tests/e2e-todo.test.ts — a local todo app served by Bun.serve: add three todos, toggle one, clear completed. Proves the daemon keeps state across commands.
tests/e2e-webkit.test.ts — every command driven on WebKit, with page state read back via eval after each one.
tests/e2e-compat.test.ts — diffs bowser against playwright-cli on the todo flow, asserting bowser's refs are a subset of playwright-cli's tree; skips without playwright-cli's WebKit installed.
tests/e2e-search.test.ts — live web: search GitHub for OpenClaw, find the repo link, type into the search box and press Enter.

Roadmap

Migrating from 0.1.0

The 0.2.0 release is a clean break: snap → snapshot, @e3 → e3, --session → -s=, session list → list. See CHANGELOG.md for the full migration table.

License

MIT

@drakulavich/bowser Cli

GitHub Actions

A Bun-native, drop-in command-compatible alternative to Microsoft playwright-cli for AI agents.

Devops Browser Automation Developer Tools

Add to Cursor Add to VS Code Run on PlugMCP

GitHub npm Website

Add to Cursor Add to VS Code Run on PlugMCP

1{2  "mcpServers": {3    "drakulavich-bowser-cli": {4      "command": "npx",5      "args": [6        "-y",7        "@drakulavich/[email protected]"8      ]9    }10  }11}

.cursor/mcp.jsonMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @drakulavich/[email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add drakulavich-bowser-cli -- npx -y @drakulavich/bowser-cli@0.12.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "drakulavich-bowser-cli": {4      "command": "npx",5      "args": [6        "-y",7        "@drakulavich/[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.12.0
Last checked: 2026-10-28

Stars: —
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install @drakulavich/bowser Cli?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does @drakulavich/bowser Cli need an API key?

No required environment variable is listed on this record.

What transport does @drakulavich/bowser Cli use?

@drakulavich/bowser Cli runs locally over stdio.

When was @drakulavich/bowser Cli last checked?

Last checked 2026-10-28. A Bun-native, drop-in command-compatible alternative to Microsoft playwright-cli for AI agents.

From the publisher

Documentation

Bowser

Why

What sets it apart from playwright-cli:

Bun-native. Runs on Bun, no Node or Playwright install.
Fewer tokens than playwright-cli. In the agent benchmark (10 browser tasks, 3 runs each, Claude Sonnet 5.5, 2026-10-21), an agent used 413k tokens and $0.41 with bowser against 445k and $0.51 with playwright-cli, summed over the per-task medians. Both passed all 30 runs.
Persistent sessions. Each named session keeps a long-lived browser process so multi-step flows survive between commands.

Install

bowser runs on macOS only (it needs WebKit, which Bun.WebView provides only there).

# From npm
npm install -g @drakulavich/bowser-cli

# ...or directly from source
git clone https://github.com/drakulavich/bowser.git
cd bowser
bun install
bun link                     # exposes `bowser` on $PATH

On another platform, any command that would start a session fails with the error "bowser requires macOS (WebKit)" (exit 1).

Upgrading

A daemon newer than the bowser you run (after a downgrade) is still refused: "session '' is running bowser (this is ); run 'bowser close -s ', then open it again" (exit 1).

Screenshots

Quickstart

bowser open https://example.com          # navigate, save state
bowser snapshot                          # the page's aria tree, with [ref=eN]
bowser click e3                          # click a ref
bowser fill e5 "[email protected]"        # fill a form field
bowser press Enter                       # submit
bowser screenshot --filename=shot.png    # capture
bowser close                             # end session

Multiple sessions

bowser -s=login open https://app.example.com/login
bowser -s=login fill  e1 "[email protected]"
op read op://vault/app/password | bowser -s=login fill e2 --stdin
bowser -s=login click e3

Commands on one session run one at a time: when several clients (parallel shell calls, two MCP servers) send commands to the same session, each waits its turn and runs whole.

Persistent profiles

bowser -s=app open https://app.example.com/login --persistent   # profile in ~/.bowser/profiles/app/
bowser -s=app close                                              # the profile stays
bowser -s=app open https://app.example.com --persistent         # still logged in
bowser -s=work open https://app.example.com --profile=./profiles/work   # a directory of your choice

The profile lives outside ~/.bowser/sessions/<name>/, so close leaves it alone. Delete it with rm -rf ~/.bowser/profiles/<name> (or your --profile directory).
The store is chosen when the session's browser starts. open --persistent on a session that is already running with another store fails with exit 1; run bowser close first. open without the flag reuses a running persistent session.
One profile directory serves one running session at a time; sharing it between two is unsupported.
A persistent store needs macOS 15.2 or later.

Dialogs

bowser dialog-accept            # the next dialog is accepted (confirm → true)
bowser click e7                 # the click that opens it
bowser dialog-accept "Ann"      # a prompt gets "Ann"; with no text, its own default value
bowser click e8

### Modal state
- ["prompt" dialog with message "Your name?"]: accepted

Differences from playwright-cli:

In playwright-cli, the dialog stays open and dialog-accept answers it after the action. In bowser, dialog-accept after the action prepares the next dialog. It does not answer the one already reported.
WebKit has no dialog events, so bowser replaces window.alert/confirm/prompt in the page, and in every same-origin iframe it can reach, before it acts there. A dialog in such an iframe is reported like the page's own and takes the prepared answer. A dialog that fires between commands (a timer) is reported by the next command that prints dialogs, even when that command leaves the page (reload, goto, open, go-back, press Enter on a form).
A function the page defined itself (window.confirm = m => …) is left alone and runs, as in playwright-cli; its calls are not dialogs and are not reported.
A page function made with .bind() from the browser's own (window.confirm = confirm.bind(window)) looks native to bowser: the shim replaces it, and the dialog is reported.
Not reported, and dismissed by WebKit:
- a dialog the page opens while loading, before bowser's first command on that document;
- a dialog in a cross-origin iframe, or in an iframe that loaded after bowser's last command;
- a dialog opened through a reference the page saved at load time (const c = window.confirm), including a page wrapper around it (window.confirm = m => c(m)).
In each of these cases a prepared answer stays set until the next dialog bowser sees or a navigation.
A dialog whose handler then navigates the page (if (confirm('Leave?')) location = …) is answered but not reported, because the report leaves with the old page.
beforeunload is not handled.

Snapshot output

### Page
- Page URL: http://localhost:52047/todo-app.html
- Page Title: Bowser Todo
### Snapshot
```yaml
- generic [active] [ref=e1]:
  - heading "Todos" [level=1] [ref=e2]
  - generic [ref=e3]:
    - textbox "New todo" [ref=e4]:
      - /placeholder: What needs doing?
    - button "Add" [ref=e5] [cursor=pointer]
  - list "Todo list" [ref=e6]:
    - listitem [ref=e7]: No todos yet
  - generic [ref=e8]:
    - generic [ref=e9]: 0 items left
    - button "Clear completed" [ref=e10] [cursor=pointer]
```

JSON output for agent pipelines

bowser --json snapshot | jq -r .snapshot | grep 'button'

Command reference

Command	Description
`open [url] [--persistent] [--profile=dir]`	Start session; navigate if URL given. `--persistent` keeps cookies, `localStorage` and IndexedDB in `~/.bowser/profiles/<session>/` across `close` and restarts; `--profile=dir` keeps them in `dir` instead (implies `--persistent`). See Persistent profiles.
`goto <url>`	Navigate within current session. For `open` and `goto` alike, a URL without a scheme gets one, as in `playwright-cli`: `http://` for `localhost`, `127.0.0.1` and `[::1]` (`localhost:3000/x` → `http://localhost:3000/x`), `https://` for any other host (`example.com` → `https://example.com`). A URL with a scheme (`http:`, `file:`, `about:`, `data:`, …) is used as typed. Unlike `playwright-cli`, `127.0.0.1` gets `http://`, not `https://`.
`snapshot [--filename=f] [--depth=N]`	Full aria tree in `playwright-cli`'s format, with `eN` refs; `--depth=N` limits the levels printed (`0` or unset is unlimited)
`markdown [ref] [--filename=f]`	The page as Markdown, for reading. When the page offers its own Markdown (a claude.ai artifact's source, or `<link rel="alternate" type="text/markdown">`), that text; otherwise `<main>` (or the body without one) converted: headings, paragraphs, lists, tables, links, code, emphasis, image `alt`, with hidden content and form controls left out. With a ref, only that element is converted, without scrolling the page. `--json` gives `{"markdown":"…","source":"page"
`click <ref>`	Click an element. A disabled element (the snapshot's `[disabled]`: a disabled control or `<fieldset>`, or `aria-disabled="true"` on it or an ancestor) fails at once with `ref 'eN' is disabled`, exit 1, and is not clicked; `playwright-cli` waits out its timeout
`fill <ref> <text>` / `fill <ref> --stdin`	Focus, clear, type. `--stdin` reads the text from piped input and drops one trailing newline, so a secret never appears in the process arguments: `op read op://vault/site/password \| bowser fill e4 --stdin`. The text is never echoed, with or without `--stdin`: `filled e4 (textbox "Password")`, and `--json` answers `{"ok":true,"ref":"e4","element":{"role":"textbox","name":"Password"}}`. `--stdin` is not offered over MCP. A disabled (a disabled `<fieldset>` included) or `readonly` field fails with `ref 'eN' is not an editable element (disabled)` or `(readonly)`, exit 1, value untouched; `playwright-cli` waits out its timeout. A `date`, `time`, `datetime-local`, `month`, `week` or `color` input gets the value set directly, as `playwright-cli` does (`fill e9 2024-01-02`); one it does not keep fails with `ref 'eN' did not accept the value for input[type=<type>]`. On `type=number`, text that is not a number fails with `ref 'eN' needs a number (input[type=number])`. Both exit 1 and leave the value as it was; no error repeats the text.
`type <text>`	Type into focused element. The text is never echoed: it prints `typed N characters` (`typed 1 character` for one), counting code points, and `--json` answers `{"ok":true,"length":N}`. For `fill` and `type` alike, a browser error that quotes the text is replaced by `<command>: the browser's error message was withheld because it contained the entered text`; a dialog message the page shows is page content and is printed as is
`press <key>`	Press a keyboard key, or a combination as in `playwright-cli`: `Shift+Tab`, `Meta+a`, `Shift+Meta+ArrowRight`. Modifiers are `Shift`, `Control`, `Alt`, `Meta` and `ControlOrMeta` (which is `Meta`: bowser runs on macOS). `Tab` moves focus to the next field, as the browser's own Tab does, and types nothing; `Shift+Tab` moves it back. The key is one character or `Enter`, `Tab`, `Space`, `Backspace`, `Delete`, `Escape`, `ArrowLeft`, `ArrowRight`, `ArrowUp`, `ArrowDown`, `Home`, `End`, `PageUp`, `PageDown`. Known differences from `playwright-cli`: WebKit through `Bun.WebView` cannot press `F1`–`F12`, a modifier alone (`Shift`) or a key code (`KeyA`, `NumpadEnter`), so these fail with `usage:` (exit 1); `Meta+c`, `Meta+x` and `Meta+v` reach the page as keydowns but do not copy, cut or paste. Keys follow macOS: `Control+a` moves to the start of the line, `Meta+a` selects all, `Meta+z` undoes
`hover <ref>`	Hover an element
`select <ref> <value>`	Choose a `<select>` option: the first, in document order, whose value or label is `<value>` (`select e3 Red` picks `<option value="r">Red</option>`). With no such option it fails at once with `ref 'eN' has no option "<value>"` (exit 1) and the select keeps its value; `playwright-cli` waits out its timeout
`check <ref>` / `uncheck <ref>`	Check or uncheck a checkbox or radio button. A disabled one fails like `click`. `uncheck` on a checked radio fails with `ref 'eN' is a radio button; select another option in its group to uncheck it`, exit 1; on an unchecked one it succeeds and does nothing. An `aria-checked="mixed"` checkbox is unchecked for `check` (one click, as in `playwright-cli`) and checked for `uncheck`, which clicks it until it reads `false` (`playwright-cli` leaves it mixed)
`dialog-accept [text]` / `dialog-dismiss`	Set the answer for the next `alert`/`confirm`/`prompt` (a prompt gets `text`, default its own value). Run it before the action; without one a dialog is dismissed. The action reports each dialog under `### Modal state`.
`screenshot [--filename=f] [--scale=N]`	Screenshot of the viewport (PNG); no full-page capture. Waits up to 5 s for the page's own web fonts (not its iframes'); `; fonts still loading` when they did not arrive
`resize <width> <height>`	Set the viewport size in pixels, each side 1 to 16384 (`Bun.WebView`'s limit)
`go-back` / `go-forward` / `reload`	Navigation
`wait-for --url <part>` / `wait-for --text <text>`	Wait until the page URL (`location.href`) or its visible text (`document.body.innerText`) contains the value: a client-side route change or text that arrives after a `click` has answered. Prints the URL and saves it to the session. Bounded by the command's budget; when it runs out it fails with `wait-for: no URL containing '<part>' after <ms>ms; the page is at <url>` (exit 2). One of the two flags, not empty. `playwright-cli` has no such command; Playwright MCP's `browser_wait_for` is the closest.
`list`	List sessions whose daemon answers. A session whose daemon is gone is not listed.
`close [name]`	End a session and remove its directory (defaults to `--session`; positional name overrides). Fails if the browser process cannot be confirmed stopped, including a daemon from bowser 0.5 or older that does not answer: it wrote no pidfile, so `close` exits 2 and keeps the session until you end the process yourself (the error says how). A name with no session answers `session '<name>' is not open` (exit 0), as `playwright-cli` does, so a typo in `-s` does not look like a close.
`close --all`	Close every open session; a directory a refused start left behind is removed but not listed. If one cannot be closed, it still tries the rest, then fails (exit 2) naming each such session with its reason and listing the ones it closed
`localstorage-list`	List all `localStorage` entries (`key=value` per line, or JSON with `--json`)
`localstorage-get <key>`	Read a `localStorage` value
`localstorage-set <key> <value>`	Write a `localStorage` entry
`localstorage-delete <key>`	Remove a `localStorage` entry
`localstorage-clear`	Clear all `localStorage` entries
`sessionstorage-list`	List all `sessionStorage` entries (`key=value` per line, or JSON with `--json`)
`sessionstorage-get <key>`	Read a `sessionStorage` value
`sessionstorage-set <key> <value>`	Write a `sessionStorage` entry
`sessionstorage-delete <key>`	Remove a `sessionStorage` entry
`sessionstorage-clear`	Clear all `sessionStorage` entries
`eval <expression>`	Evaluate a JS expression in the current page; prints the result
`run-code <code>`	Run JavaScript in the current page and print the result. One expression is evaluated as one (`run-code "(() => { return 5 })()"` prints `5`); any other code is the body of an async function, so use `return` for the result, and `await` works (`run-code "await new Promise(r => setTimeout(r, 100)); return document.title"`). Unlike `playwright-cli`'s `run-code`, which calls a function with a Playwright `page` in Node, it runs in the page: a result that is a function, such as `async page => …`, fails with `run-code runs JavaScript in the page and has no Playwright 'page'; write statements and use return` (exit 1)
`state-save <file>`	Save the current origin's localStorage to a Playwright-compatible `storageState` JSON file. Its `cookies` array is always empty: bowser has no cookie access (use `open --persistent` to keep logins). A page with no origin (`about:blank`) saves no origins.
`state-load <file>`	Restore localStorage from a `storageState` file. It restores origins matching the current page and reports the others skipped. Cookies in the file are skipped, with one line on stderr. A missing, invalid or wrongly shaped file (`storageState.origins: expected array, got object`) restores nothing and exits 1.
`mcp`	Run a Model Context Protocol stdio server exposing every command above as an MCP tool.

MCP bridge

{
  "mcpServers": {
    "bowser": { "command": "bowser", "args": ["mcp"] }
  }
}

Notes:

The server is a thin client of the same per-session daemons the CLI uses; the first tool call on a fresh session spawns one.
Relative file paths (screenshot, snapshot filename, state-save, state-load) resolve against the server's working directory. If the client starts it from / or another directory it cannot write, the server uses <os.tmpdir()>/bowser-mcp instead ($TMPDIR/bowser-mcp). Replies name the absolute path written. An absolute path is used as given.
The protocol is hand-rolled (newline-delimited JSON-RPC) with zero runtime dependencies. It speaks MCP 2025-11-25, 2025-06-18 and 2024-11-05: initialize answers with the client's version when it is one of these, and with 2025-11-25 otherwise. The stateless 2026-07-28 revision is not implemented; its server/discover probe gets -32601 Method not found, on which a client falls back to initialize.
initialize, ping, tools/list and notifications are answered at once, even while tool calls run.
A JSON-RPC batch (an array) or a line that is not a JSON object gets one -32600 Invalid Request error with id: null; nothing in a batch runs. MCP 2025-06-18 has no batching.
A request without a string method gets -32600 Invalid Request with its id, and a tools/call of a tool the server does not have gets -32602 Unknown tool. A response from the client (a message with result or error) gets no answer.
Tool calls for different sessions run concurrently; calls for the same session run one at a time, in the order they arrived. Responses may therefore arrive out of order (JSON-RPC matches them by id).
The server exits when stdin closes and every running call has answered. A client that stops reading stdout is gone: the server exits 0 at its next response, and calls still queued never run. A browser operation already running finishes in its daemon.
notifications/cancelled drops the call: one still queued behind its session never runs, and a running one finishes but its result is discarded. Either way no response is sent for it, per the MCP spec. A browser operation that has already started is not undone — a cancelled click may still have clicked, and the session's next call waits for it to finish.

How it works

bowser open spawns a per-session daemon holding a Bun.WebView, navigates, and saves {url, title} to ~/.bowser/sessions/<name>/state.json.
bowser snapshot runs a snapshot script in the page that walks the DOM into an aria tree (roles, names, text, refs) and keeps a reference to each ref's element in the page; src/snapshot.ts renders that tree as YAML. Refs are persisted with the CSS path each element had (#id when safe, otherwise an nth-of-type chain), e.g. e3 → html > body > button:nth-of-type(2).
bowser click e3 resolves the ref from state, then in the page: the snapshot script kept a reference to each ref's element, so the command checks that element is still in the document and computes its CSS path afresh (a stale ref fails here, before anything is clicked). It then dispatches the click via the daemon, using Bun.WebView's built-in actionability auto-wait — no polling, no hard-coded timeouts.

Environment variables

Variable Effect

Variable	Effect
`BOWSER_OP_TIMEOUT_MS`	Per-command timeout in milliseconds (default `30000`; `0` disables). It covers the whole command: each step of a command gets the time the command has left, and time spent queued behind another command counts, so a wedged browser makes a command exit with a timeout error instead of blocking forever. The daemon reads it once, when the session starts, and a value set on a later command applies to that command only when it is smaller. To raise it, `close` the session and `open` it again with the new value. An upgrade restart keeps it (see "Upgrading"). A timeout names the command and, when it differs, the step that overran: `'fill' timed out after 3000ms (in its 'click' step)` (exit 2). When the time runs out after an action was sent, the timeout says the action may have reached the page: `'click' timed out after 3000ms; the click may have been delivered, check the page before retrying`. Once the action has returned it says `the click was delivered`, and `waiting for the page it opened` when the action started a navigation that has not loaded yet. Retrying without checking may act twice. If a timed-out command is still running 2 s later (or after the budget, if shorter), the daemon reloads the page once to free the browser (in a session that has not loaded a page yet, where a reload does nothing, it leaves the blank page instead). A command whose client goes away (killed, or its terminal closed) gets 5 s more to finish once its connection closes (or what is left of its budget, if less), and is then ended the same way, with or without a budget. If the command outlives that reload, every other command fails at once with `session is stuck: '<cmd>' is still running after a reload; run 'bowser close'` (exit 2) until it ends; `close` always works. A command sent during the 2 s and the reload waits for them, so the first such failure can take up to 12 s after the timeout (up to 22 s in a session that has not loaded a page yet, where leaving the blank page can take two 10 s tries). An action such as `click` or `fill` on a page still loading a navigation that an earlier command started waits for it, and fails with `page is still loading <url>; retry later, or run 'bowser close'` (exit 2) if the time runs out first. If the daemon itself stops answering mid-command (frozen or swapped out), the command gives up 2 s after its budget with `daemon for session '<s>' did not answer; run 'bowser close -s <s>' to stop it` (exit 2), and `bowser close -s <s>` ends it.
`BOWSER_DAEMON_DEBUG`	`1` writes the output of a session daemon that this command starts to `~/.bowser/sessions/<session>/daemon.log`, for debugging a daemon that fails to start. `close` deletes it with the session directory.

Tests

bun run check                                  # typecheck, lint, then unit tests
bun run typecheck                              # tsc
bun run lint                                   # Biome (import cycles, layer rules) and Knip (unused files, exports)
bun test                                       # unit + command tests with a fake daemon
BOWSER_E2E=1 bun test                          # + end-to-end on WebKit
BOWSER_E2E=1 BOWSER_E2E_NET=1 bun test         # + live-internet e2e (GitHub search)

End-to-end examples included:

tests/e2e.test.ts — open/snapshot/click on a data: URL (no network)
tests/e2e-todo.test.ts — a local todo app served by Bun.serve: add three todos, toggle one, clear completed. Proves the daemon keeps state across commands.
tests/e2e-webkit.test.ts — every command driven on WebKit, with page state read back via eval after each one.
tests/e2e-compat.test.ts — diffs bowser against playwright-cli on the todo flow, asserting bowser's refs are a subset of playwright-cli's tree; skips without playwright-cli's WebKit installed.
tests/e2e-search.test.ts — live web: search GitHub for OpenClaw, find the repo link, type into the search box and press Enter.

Roadmap

Migrating from 0.1.0

The 0.2.0 release is a clean break: snap → snapshot, @e3 → e3, --session → -s=, session list → list. See CHANGELOG.md for the full migration table.

License

MIT