Skip to main content
Glama
README.md
# browser-agent

[![License: MIT](https://img.shields.io/badge/license-MIT-c6532a)](LICENSE)
[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-1b3330)](package.json)
[![Playwright](https://img.shields.io/badge/playwright-chromium-244640)](https://playwright.dev)

A browser the people on your team and the coding agents they use can share. Playwright drives a real Chromium session. The CLI and the MCP server talk to the same long-lived process, and every action comes back with an accessibility snapshot, a ref such as `e3`, and a clear success or failure.

Agents stop guessing CSS. A duplicate name is refused, with the candidate refs listed, before anything is clicked. A JavaScript dialog returns immediately instead of freezing the next tool call.

<p align="center">
  <img src="docs/images/harbor-login.png" alt="Harbor Desk sign-in page opened in Chromium by browser-agent" width="49%">
  <img src="docs/images/cli-snapshot.png" alt="Terminal showing a compact accessibility snapshot with refs e1, e2, and e3" width="49%">
</p>

<p align="center">
  <img src="docs/images/harbor-board.png" alt="Harbor Desk morning board after signing in" width="49%">
  <img src="docs/images/cli-click.png" alt="Terminal showing a successful click on Sign in and the new snapshot" width="49%">
</p>

The pictures are one real session against [`examples/harbor`](examples/harbor/index.html). The snapshot on the right of the first row took 54ms. The click that opened the board took 119ms. Those times are from this run, after the browser was already open. They are not a benchmark.

## What you can do

One session can cover the whole path a person would take through a web app.

- Open a URL, a host (`example.com`, `localhost:3000`), or a local HTML file. Go back, forward, and reload.
- Read the page as an accessibility tree, compact or full, and act on refs.
- Click, double-click, right-click, hover, scroll, and press keys.
- Fill fields. Password values are masked in the output. Type slowly when a page only listens to real keystrokes.
- Choose a select option, and set files on an upload input.
- Wait for text, for text to disappear, for a URL glob, a load state, a CSS selector, an element, or a JavaScript condition.
- Take a viewport screenshot, a full-page screenshot, or a screenshot of one element. MCP returns the PNG to the model.
- Run JavaScript in the page, or against one element.
- Pull visible text, HTML, links, or a form summary.
- Handle `alert`, `confirm`, `prompt`, and `beforeunload` without deadlocking the agent.
- List, open, select, and close tabs. Popups are reported and are not stolen automatically.
- List, set, and clear cookies. Read and write `localStorage` and `sessionStorage`.
- Save downloads and list the files.
- Watch console messages and recent network requests. Abort or fulfill requests that match a URL glob.
- Run headless, or show the window. Use Playwright's Chromium, installed Chrome, or Edge, including beta, dev, and canary channels.
- Reuse a Chrome profile, send traffic through a proxy, set the viewport and user agent, and record a WebM of the session.
- Keep the browser alive between shell commands and between MCP tool calls. Name a session so an agent does not take the browser you are using.
- Print human output, or `--json` for scripts. Talk to the same browser from Cursor, Claude Code, Claude Desktop, or any MCP client.

## Time it gives back

The expensive part of browser work for an agent is not the click. It is the turns spent guessing a selector, clicking the wrong Save, or waiting on an alert that never returns. browser-agent is built so that turn ends on the first correct ref.

These are working-time estimates for a developer who already knows the app. They are not a customer study.

| Job | Without a shared agent browser | With browser-agent |
| --- | --- | --- |
| Confirm sign-in still reaches the next screen | 20–40 minutes the first time you write and maintain a Playwright script, or a manual pass on every change | The Harbor Desk path below: navigate, snapshot, type, click. About a minute, then the same commands after the next edit |
| Let a coding agent see the UI it just changed | Paste screenshots by hand, or watch it retry selectors for several model calls | One MCP server. Each action returns the new snapshot |
| Stop a wrong click on a repeated label | The first match is clicked, then you debug the damage | The action fails, lists every match, and clicks nothing |
| Keep a logged-in browser between commands | Every script launches a fresh browser and logs in again | The daemon stays up. Later actions in the Harbor run were 50–120ms |
| Show a teammate what happened | A separate screen recording, plus a verbal retelling | `--video`, a PNG, the console, and the network log from the same session |
| Point Cursor, Claude Code, and a shell script at one browser | Three tools, three setups, three kinds of flake | One daemon, one session name, one result shape |

For a business, the saving shows up as fewer broken agent loops and less time rebuilding the same smoke check. A team that asks an agent to verify UI several times a day stops paying for the turns that used to be selector retries. The same commands run in a terminal, in CI, and inside the editor.

## Quick start

Node.js 20 or newer.

```bash
npm install
npx playwright install chromium
npm run build
node dist/cli.js doctor
node dist/cli.js navigate https://example.com
node dist/cli.js snapshot --compact
node dist/cli.js close
```

After the package is published:

```bash
npm install -g browser-agent
browser-agent install
browser-agent navigate https://example.com
browser-agent snapshot --compact
browser-agent close
```

`browser-agent install` downloads the Chromium build that matches this Playwright version. A single-file binary is not shipped. The browser is the large part, and it has to match the library.

On a machine where Chromium's sandbox cannot start, the daemon retries once with `--no-sandbox`. Set `BROWSER_AGENT_NO_SANDBOX=1`, or pass `--arg --no-sandbox`, to skip the first attempt.

## Harbor Desk, end to end

The example is a one-file desk for a pier office. Serve it, then drive it.

```bash
python3 -m http.server 4173 --bind 127.0.0.1 --directory examples/harbor
```

```bash
browser-agent navigate http://127.0.0.1:4173/
browser-agent snapshot --compact
browser-agent type "Work email" ada@harbor.example
browser-agent type Password tide-0540
browser-agent click "Sign in"
browser-agent screenshot -o board.png
browser-agent close
```

<p align="center">
  <img src="docs/images/cli-type.png" alt="Typing a password. The observation and the snapshot mask the value." width="78%">
</p>

The password is masked in the observation and in the snapshot. The email stays visible because it is not a password field.

With no command in a terminal, `browser-agent` opens an interactive session:

```text
browser-agent 0.1.0
Type a command, help, or exit.
› navigate http://127.0.0.1:4173/
› click "Sign in"
› exit
```

`help` lists the commands. `exit` leaves the prompt and leaves the browser running until `close`.

## How an agent should work

1. `browser_navigate` to open the page.
2. Read the snapshot. Use a ref such as `e3`.
3. `browser_click`, `browser_type`, or another action with that ref.
4. If the result contains `pendingDialog`, call `browser_dialog` before anything else.
5. `browser_screenshot` when the pixels matter.
6. `browser_close` when the task is done.

Refs last until the next navigation or snapshot. A click, a type, and the other mutations return a fresh compact snapshot, so the next action can use the new refs immediately. An explicit snapshot defaults to the full tree. Pass `mode: "compact"` when you only want controls and headings.

Set `BROWSER_AGENT_SESSION=agent` in the MCP config. The default session name is `default`. Sharing that name means the agent and your terminal are driving one window.

A prompt that produces a reliable run:

> Open http://127.0.0.1:4173/, sign in with the pier office account, and confirm the morning board lists MV Calder. Use browser-agent. Do not guess selectors. If a dialog appears, handle it before the next action. If a name matches more than one element, use the ref from the error.

## When a name is not unique

<p align="center">
  <img src="docs/images/cli-ambiguous.png" alt="browser-agent refusing to click Save because two buttons share that name" width="78%">
</p>

`"Save"` matched two buttons. Nothing was clicked. The hint points at a ref. `click e2` is the next command, after you decide which Save you meant. The same rule applies to typing, hovering, and selecting.

## CLI

Global flags can sit before or after the command.

| Flag | Meaning |
| --- | --- |
| `--json` | Print the structured result. |
| `--session <name>` | Named browser. Default `default`. |
| `--headed` / `--headless` | Show or hide the window. Headless is the default. |
| `--profile <dir>` | Chrome user-data directory. Close Chrome first if it already has that directory open. |
| `--channel <name>` | `chrome`, `msedge`, `chromium`, or a beta, dev, or canary channel. `chromium` uses Playwright's build. |
| `--proxy <url>` | Proxy server, for example `http://127.0.0.1:8080`. |
| `--proxy-user`, `--proxy-pass` | Proxy credentials. The password is part of the session identity. |
| `--viewport <WxH>` | Viewport, for example `1280x720`. Headed mode uses the real window unless this is set. |
| `--user-agent <ua>` | Override the user agent. |
| `--executable-path <file>` | A specific Chromium binary. |
| `--video` | Record a WebM. The path is printed when the session closes. |
| `--timeout <ms>` | Action timeout for this command. Default 15000. |
| `--idle-timeout <sec>` | Quit after inactivity. Default 1800. `0` keeps the browser until `close`. |
| `--strict-https` | Reject invalid TLS certificates. Invalid certificates are accepted by default. |
| `--arg <flag>` | Extra Chromium argument. Repeat it. `--arg --no-sandbox` is valid. |
| `--no-snapshot` | Skip the automatic snapshot. |

Launch flags are part of the session identity. Passing a different `--headed`, profile, proxy, viewport, or video setting against a running session returns `SESSION_CONFIG_MISMATCH` instead of quietly driving the wrong browser. A command that does not pass launch flags attaches to the session that is already running.

### Commands

| Command | What it does |
| --- | --- |
| `launch` | Start the browser and leave it running. |
| `status` | Show the session. |
| `close` | Close the browser. |
| `navigate <url>` | Open a URL. `--wait load`, `domcontentloaded` (default), or `networkidle`. |
| `back`, `forward`, `reload` | History. |
| `snapshot` | Accessibility tree. `--compact`. `--max-lines <n>`. |
| `click <target>` | Click. `--button left\|right\|middle`. `--double`. |
| `type <target> <text>` | Fill a field. `--submit` presses Enter. `--slowly` sends keystrokes. `--no-clear` appends when typing slowly. |
| `press <key>` | `Enter`, `Tab`, `Control+A`. `--target` focuses first. |
| `hover <target>` | Hover. |
| `select <target> <value>` | Choose an option by label or value. |
| `upload <target> <files...>` | Set files on an input. The files must exist on the machine running the browser. |
| `scroll [direction]` | `up`, `down`, `left`, `right`, `top`, `bottom`. `--amount <px>`. `--target` scrolls that element into view. |
| `screenshot` | PNG. `--full`. `-o, --output <file>`. `--target` captures one element. |
| `eval <expression>` | JavaScript in the page. `--target` exposes the element as `el`. |
| `extract [type]` | `text` (default), `html`, `links`, or `forms`. `--max <chars>`. |
| `wait` | See the flags below. |
| `tabs [action] [value]` | `list`, `new <url>`, `select <index>`, `close <index>`. |
| `dialog <accept\|dismiss>` | Close the open dialog. `--prompt <text>` answers a prompt. |
| `cookies [list\|set\|clear]` | `--name`, `--value`, `--url`. |
| `storage [get\|set\|clear] [key] [value]` | `localStorage`. `--session-storage` uses `sessionStorage`. |
| `downloads` | List files saved this session. |
| `network [list\|clear\|route\|unroute] [pattern]` | `route` aborts by default. `--fulfill`, `--status`, `--body`, `--content-type`. |
| `console [list\|clear]` | `--level all\|error\|warning\|info`. |
| `mcp` | MCP server on stdio. |
| `init [cursor\|claude-desktop\|claude-code]` | Print an MCP config. |
| `install` | Download Playwright's Chromium. |
| `doctor` | Check Node, Playwright, and Chromium. |
| `repl` | Interactive mode. This is also the default in a terminal. |

`wait` flags: `--text`, `--text-gone`, `--url <glob>`, `--load <state>`, `--selector <css>`, `--target`, `--state visible\|hidden\|attached\|detached`, `--fn <expression>`, `--time <ms>` (at most 10000). Prefer text, URL, or a load state over a fixed sleep.

`networkidle` is available and is a poor default. Pages with analytics or long-polling often never go idle. `domcontentloaded` is the default for navigation.

## Targets

| Form | Example | When to use it |
| --- | --- | --- |
| Snapshot ref | `e12` or `@e12` | Default. Valid for the current snapshot. |
| Accessible name | `"Assign to pier"` | When that name is unique. |
| Role phrase | `"Sign in button"` or `button "Sign in"` | Role plus name. |
| Label | `label=Work email` | A labeled control. |
| Placeholder | `placeholder=Search` | Placeholder text. |
| Role query | `role=button[name="Sign in"]` | When the name alone is shared. |
| Text | `text=Morning board` | Visible text. |
| Test id | `testid=submit` | `data-testid`. |
| CSS | `css=#submit` | Last resort. |
| XPath | `xpath=//button[@name='save']` | Last resort. |

A phrase like `"Login button"` is a button named Login. `"Work email"` matches a textbox, searchbox, or combobox with that name. Matching is exact, then case-insensitive, then a substring when the query is at least 3 characters. Interactive controls and headings are preferred.

Refs remember the role, the accessible name, which occurrence it was, and the Chrome accessibility node. A click resolves that node and then performs a real Playwright click. If the node is gone, the role and name are tried. If several elements still match, the action is `AMBIGUOUS_TARGET`.

## MCP

The server speaks stdio and starts the same daemon the CLI uses.

```bash
browser-agent init cursor
browser-agent init claude-desktop
browser-agent init claude-code
```

Cursor (`.cursor/mcp.json` or `~/.cursor/mcp.json`), Claude Desktop (`claude_desktop_config.json`), and Claude Code (`.mcp.json`):

```json
{
  "mcpServers": {
    "browser-agent": {
      "command": "npx",
      "args": ["-y", "browser-agent", "mcp"],
      "env": { "BROWSER_AGENT_SESSION": "agent" }
    }
  }
}
```

Claude Code can also add it with `claude mcp add browser-agent -- npx -y browser-agent mcp`. From a checkout, point `command` at `node` and `args` at `dist/cli.js` plus `mcp`.

The server registers a `browser-task` prompt that describes the ref loop for the model.

### Tools

Every tool returns text plus structured content. A failure sets the MCP error flag. `browser_screenshot` also returns the PNG.

| Tool | Parameters |
| --- | --- |
| `browser_navigate` | `url`, `command` (`goto`, `back`, `forward`, `reload`), `waitUntil` (`load`, `domcontentloaded`, `networkidle`), `timeout`, `snapshot` |
| `browser_snapshot` | `mode` (`compact` or `full`), `maxLines` |
| `browser_click` | `target`, `button`, `double`, `timeout`, `snapshot` |
| `browser_type` | `target`, `text`, `submit`, `slowly`, `clear`, `delay`, `timeout`, `snapshot` |
| `browser_press` | `key`, `target`, `timeout`, `snapshot` |
| `browser_hover` | `target`, `timeout`, `snapshot` |
| `browser_select` | `target`, `value`, `timeout`, `snapshot` |
| `browser_upload` | `target`, `files`, `timeout`, `snapshot` |
| `browser_scroll` | `direction`, `amount`, `target`, `timeout`, `snapshot` |
| `browser_screenshot` | `target`, `fullPage`, `path`, `timeout`. The server attaches the image itself. |
| `browser_evaluate` | `expression`, `target`, `timeout`. With `target`, the expression receives `el`. |
| `browser_extract` | `type` (`text`, `html`, `links`, `forms`), `maxChars`, `target` |
| `browser_wait` | `text`, `textGone`, `selector`, `target`, `url`, `loadState`, `state`, `fn`, `time`, `timeout`, `snapshot` |
| `browser_tabs` | `action` (`list`, `new`, `close`, `select`), `index`, `url`, `snapshot`, `timeout` |
| `browser_dialog` | `action` (`accept` or `dismiss`), `promptText`, `snapshot` |
| `browser_cookies` | `action` (`list`, `set`, `clear`), `name`, `value`, `url` |
| `browser_storage` | `action` (`get`, `set`, `clear`), `type` (`local` or `session`), `key`, `value` |
| `browser_downloads` | `limit` |
| `browser_network` | `action` (`list`, `clear`, `route`, `unroute`), `pattern`, `routeAction` (`abort`, `continue`, `fulfill`), `resourceTypes`, `status`, `body`, `contentType`, `limit` |
| `browser_console` | `action` (`list` or `clear`), `level`, `limit` |
| `browser_status` | Session state. |
| `browser_close` | Close the browser. |

`snapshot` on an action is `true`, `"compact"`, `"full"`, or `false`. `timeout` is milliseconds, at most 180000.

A successful result:

```json
{
  "ok": true,
  "action": "click",
  "url": "http://127.0.0.1:4173/",
  "title": "Harbor Desk",
  "observation": "Clicked button \"Sign in\" [ref=e3].",
  "snapshot": "- button \"New berth\" [ref=e1]\n- heading \"MV Calder\" [ref=e2] [level=2]"
}
```

### Dialogs

An `alert` or `confirm` opened by a click does not block the tool. The response is `ok: true` with `pendingDialog`. The next action returns `DIALOG_OPEN` until `browser_dialog` accepts or dismisses it. A serial agent can handle the dialog instead of retrying a click that is already waiting.

```bash
browser-agent dialog accept
browser-agent dialog dismiss
browser-agent dialog accept --prompt "yes"
```

### Two workflows

Shell, for a smoke check you can put in CI:

```bash
browser-agent --session ci navigate "$BASE_URL/login"
browser-agent --session ci type "Work email" "$EMAIL"
browser-agent --session ci type Password "$PASSWORD"
browser-agent --session ci click "Sign in"
browser-agent --session ci wait --text "MV Calder"
browser-agent --session ci screenshot --full -o board.png
browser-agent --session ci close
```

MCP, for an agent editing the app:

```text
browser_navigate  { "url": "http://127.0.0.1:4173/" }
browser_type      { "target": "Work email", "text": "ada@harbor.example" }
browser_type      { "target": "Password", "text": "tide-0540" }
browser_click     { "target": "e3" }
browser_wait      { "text": "MV Calder" }
browser_screenshot { "fullPage": false }
```

Other useful sessions:

```bash
browser-agent --headed navigate http://localhost:3000
browser-agent --session qa --profile ~/.config/google-chrome --channel chrome navigate https://mail.example
browser-agent --proxy http://127.0.0.1:8080 navigate https://example.com
browser-agent network route "**/analytics/**"
browser-agent network route "**/api/user" --fulfill --status 200 --body '{"name":"Ada"}' --content-type application/json
browser-agent cookies set --name session --value abc
browser-agent storage set theme dark
browser-agent tabs new https://example.com/docs
browser-agent tabs select 0
browser-agent eval "document.title"
browser-agent extract forms
browser-agent --video navigate https://example.com
browser-agent close
```

`--profile` uses a real browser profile, including its cookies. Prefer a dedicated profile for agents.

## Architecture

```text
CLI  ──┐
       ├── HTTP 127.0.0.1 ── daemon ── Playwright ── Chromium
MCP  ──┘         bearer token
```

Each session lives in `~/.browser-agent/sessions/<name>/`. `BROWSER_AGENT_DATA_DIR` overrides the root.

| File | Role |
| --- | --- |
| `session.json` | Port, token, pid, and the public launch config. Mode `0600`. |
| `launch.json` | Launch config, written for the new process and deleted after it is read. |
| `daemon.log` | Daemon stderr. |
| `screenshots/` | PNGs, unless you pass a path. |
| `downloads/` | Files saved from the page. |

The daemon binds `127.0.0.1` on a random port. Clients send `Authorization: Bearer …` and `POST /action`. Actions run one at a time, so two overlapping clicks cannot race. Playwright is imported only when a browser starts, so `browser-agent --help` stays cheap.

Snapshots come from Chrome's accessibility tree. Hidden subtrees are skipped. Password-like values are masked. Compact mode lists controls and headings. Full mode adds structure and static text that is not already the parent's name.

## Configuration

| Variable | Default | Meaning |
| --- | --- | --- |
| `BROWSER_AGENT_SESSION` | `default` | Session name. |
| `BROWSER_AGENT_DATA_DIR` | `~/.browser-agent` | Session root. |
| `BROWSER_AGENT_HEADED` | off | Show the window. |
| `BROWSER_AGENT_CHANNEL` | Playwright Chromium | `chrome`, `msedge`, `chromium`, or a beta, dev, or canary channel. |
| `BROWSER_AGENT_PROFILE` | ephemeral profile | User-data directory. |
| `BROWSER_AGENT_PROXY` | | Proxy URL. |
| `BROWSER_AGENT_PROXY_USERNAME` | | Proxy user. |
| `BROWSER_AGENT_PROXY_PASSWORD` | | Proxy password. Included in the session identity. |
| `BROWSER_AGENT_VIEWPORT` | `1280x720` headless | `WxH`. Headed mode uses the window unless this is set. |
| `BROWSER_AGENT_USER_AGENT` | browser default | User agent. |
| `BROWSER_AGENT_EXECUTABLE_PATH` | | Chromium binary. |
| `BROWSER_AGENT_ARGS` | | Extra Chromium arguments, comma-separated. |
| `BROWSER_AGENT_NO_SANDBOX` | off | Add `--no-sandbox` and `--disable-dev-shm-usage` before the first launch. |
| `BROWSER_AGENT_VIDEO` | off | Record WebM. |
| `BROWSER_AGENT_TIMEOUT` | `15000` | Action timeout, milliseconds. |
| `BROWSER_AGENT_NAV_TIMEOUT` | `30000` | Navigation timeout, milliseconds. |
| `BROWSER_AGENT_IDLE_TIMEOUT` | `1800` | Inactivity limit, seconds. `0` disables it. A non-zero value is at least 5 seconds. |
| `BROWSER_AGENT_IGNORE_HTTPS_ERRORS` | `true` | Accept invalid TLS. `--strict-https` turns this off. |
| `BROWSER_AGENT_DEBUG` | off | Client debug logs on stderr. MCP stdout stays JSON-RPC. |

## Errors

Failures carry `code`, `message`, and usually `hint`.

| Code | Meaning |
| --- | --- |
| `AMBIGUOUS_TARGET` | More than one element matched. Nothing was activated. |
| `ELEMENT_NOT_FOUND` | No element matched. |
| `REF_NOT_FOUND` | That ref is not in the latest snapshot. |
| `STALE_REF` | The ref's node is gone. Take a new snapshot. |
| `INVALID_TARGET` | The target string could not be parsed. |
| `DIALOG_OPEN` | Accept or dismiss the dialog before the next action. |
| `TIMEOUT` | The action or wait exceeded its limit. |
| `NAVIGATION_FAILED` | DNS, connection, or proxy failure. |
| `INVALID_URL` | The URL scheme is not `http`, `https`, or `file`. |
| `NO_PAGE` | The browser has no page. Retry, and the session relaunches. |
| `BROWSER_NOT_INSTALLED` | Run `browser-agent install`. |
| `BROWSER_LAUNCH_FAILED` | The daemon did not become ready. See `daemon.log`. |
| `BROWSER_CLOSED` | The browser exited during the action. |
| `PROFILE_IN_USE` | Another process has that user-data directory. |
| `SESSION_CONFIG_MISMATCH` | This command asked for different launch options than the running session. |
| `DAEMON_UNREACHABLE` | The process is alive and not answering. Close the session and retry. |
| `FILE_NOT_FOUND` | An upload path is missing. |
| `EVAL_ERROR` | The page rejected the expression. |
| `ROUTE_NOT_FOUND` | `unroute` had no matching pattern. |
| `INVALID_INPUT` | A flag or parameter was missing or out of range. |

## Comparison

| | browser-agent | Playwright MCP | agent-browser | chrome-devtools-mcp |
| --- | --- | --- | --- | --- |
| Built for | A shell and a coding agent on one browser | MCP clients | Agent CLIs | DevTools-level control |
| Interface | CLI and MCP | MCP | CLI daemon | MCP |
| Engine | Playwright | Playwright | Chromium automation | Chrome DevTools |
| Targeting | Accessibility refs. Shared names fail closed. | Accessibility refs | Snapshot refs | Snapshot uids |
| Session | Stays up between shell commands and tool calls | The MCP server's lifetime | CLI daemon | A connected Chrome |
| Dialogs | The action returns with `pendingDialog` | Depends on the tool | Depends on the tool | DevTools protocol |
| Also included | Cookies, storage, downloads, route abort and fulfill, video, profiles, proxy | Browser tools | Agent CLI | Network and debugging |

Playwright MCP is the right choice when you want Microsoft's MCP server and nothing else. agent-browser is a strong CLI. chrome-devtools-mcp is the right choice when you want the DevTools protocol itself. browser-agent is the one process a human shell and an MCP client both drive, with results a serial agent can recover from.

## Security

The daemon listens on loopback only. `session.json` holds the bearer token and is mode `0600`.

`browser_evaluate` runs in the page, not in the daemon. It can read that page's DOM, cookies, and storage. Treat page content as untrusted, and do not evaluate instructions that came from the page.

`--profile` uses a real browser profile. That includes logged-in sessions. Prefer a dedicated profile for agents.

There is no stealth or evasion mode. The browser is a normal Playwright Chromium for local development, QA, and agent verification.

## Troubleshooting

`browser-agent doctor` checks Node, Playwright, and the Chromium binary.

| Symptom | What to do |
| --- | --- |
| `BROWSER_NOT_INSTALLED` | `browser-agent install` |
| Sandbox error on launch | `--arg --no-sandbox` or `BROWSER_AGENT_NO_SANDBOX=1` |
| `PROFILE_IN_USE` | Close the other Chrome using that directory, or omit `--profile` |
| `SESSION_CONFIG_MISMATCH` | `browser-agent --session <name> close`, then retry with the options you want |
| `DAEMON_UNREACHABLE` | Close that session and retry. The log is `daemon.log` inside the session directory |
| `DIALOG_OPEN` | `browser-agent dialog accept` or `dialog dismiss` |
| `AMBIGUOUS_TARGET` | Click the ref from the hint |
| `REF_NOT_FOUND` or `STALE_REF` | `snapshot`, then use a ref from that output |
| The page never finishes | Stay on `domcontentloaded`. Use `networkidle` only when you know the page goes quiet |
| MCP and the terminal fight over one window | Give the MCP config `BROWSER_AGENT_SESSION=agent` |

Debug logging for the client is `BROWSER_AGENT_DEBUG=1`. It writes to stderr so an MCP session does not corrupt stdout.

## Development

```bash
npm install
npx playwright install chromium
npm test
npm run typecheck
npm run dev -- navigate https://example.com
```

Tests use Vitest. They cover the snapshot formatter, target parsing, CLI help, an in-process browser session, the session daemon, and an MCP `browser_navigate` call. CI installs Chromium and runs typecheck, tests, and `node dist/cli.js --help`.

The library entry is `browser-agent` (`dist/index.js`). It exports the controller, `runAction`, snapshot helpers, and config helpers. The MCP server stays out of that entry so a library import does not load the stdio server.

## License

MIT. See [LICENSE](LICENSE).

## Let's connect and collaborate

I am open to Senior Remote Full-Stack Roles, AI Platform Architecture Contracts, and Enterprise Technical Advisory.

Timezone: UTC+6 (Dhaka / Rangpur, Bangladesh). Flexible overlap with US, UK, and European business hours.

Delivery mode: async-ready, Slack, Discord, Jira, GitHub, and production-first accountability.

| Channel | Address | Action |
| --- | --- | --- |
| Primary portfolio | [imrandev.bd](https://imrandev.bd) | [Visit site](https://imrandev.bd) |
| Packagist packages | [packagist.org/packages/imrandevbd](https://packagist.org/packages/imrandevbd/) | [View packages](https://packagist.org/packages/imrandevbd/) |
| LinkedIn | [linkedin.com/in/imranbru99](https://linkedin.com/in/imranbru99) | [Connect](https://linkedin.com/in/imranbru99) |
| GitHub | [github.com/imranbru99](https://github.com/imranbru99) | [Follow](https://github.com/imranbru99) |
| WhatsApp | [+880 1576-918420](https://wa.me/8801576918420) | [Chat now](https://wa.me/8801576918420) |
| Email | [me@imrandev.bd](mailto:me@imrandev.bd) | [Send email](mailto:me@imrandev.bd) |
| X | [@imrandev_bd](https://x.com/imrandev_bd) | [Follow](https://x.com/imrandev_bd) |
| YouTube | [@ImranDevBD](https://www.youtube.com/@ImranDevBD) | [Subscribe](https://www.youtube.com/@ImranDevBD) |