Skip to main content
Glama

browser-agent

License: MIT Node.js >= 20 Playwright

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.

The pictures are one real session against examples/harbor. 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.

Related MCP server: Playwright MCP

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.

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:

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.

python3 -m http.server 4173 --bind 127.0.0.1 --directory examples/harbor
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

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:

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

"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.

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):

{
  "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:

{
  "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.

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:

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:

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:

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

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

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.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables browser automation and web interaction through structured accessibility snapshots using Playwright. Supports clicking, typing, navigation, form filling, and other web actions without requiring screenshots or vision models.
      10,908,336 npm
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides browser automation capabilities using Playwright, allowing LLMs to interact with web pages through structured accessibility snapshots without needing screenshots or vision models.
      2
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to control a real Chromium browser through Playwright, allowing them to navigate pages, click elements, fill forms, extract text or HTML, and capture screenshots in a persistent session.
      6
      ISC