agent-browser

Browser automation CLI for AI agents. Fast native Rust CLI.

Installation

Global Installation (recommended)

Installs the native Rust binary:

npm install -g agent-browser
agent-browser install  # Download Chrome from Chrome for Testing (first time only)

Project Installation (local dependency)

For projects that want to pin the version in package.json:

npm install agent-browser
agent-browser install

Then use via package.json scripts or by invoking agent-browser directly.

Homebrew (macOS)

brew install agent-browser
agent-browser install  # Download Chrome from Chrome for Testing (first time only)

Cargo (Rust)

cargo install agent-browser
agent-browser install  # Download Chrome from Chrome for Testing (first time only)

From Source

Requires Node.js 24+, pnpm 11+, and Rust.

git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native   # Requires Rust (https://rustup.rs)
pnpm link --global  # Makes agent-browser available globally
agent-browser install

Linux Dependencies

On Linux, install system dependencies:

agent-browser install --with-deps

This exits nonzero if the package manager cannot install every required browser library.

When run as root, this command calls the detected package manager directly. For non-root users, it uses sudo. If you are not root and sudo is unavailable, it reports that root privileges or sudo are required.

Updating

Upgrade to the latest version:

agent-browser upgrade

Detects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command automatically.

Requirements

• Chrome - Run agent-browser install to download Chrome from Chrome for Testing (Google's official automation channel). Existing Chrome, Brave, Playwright, and Puppeteer installations are detected automatically. No Playwright or Node.js required for the daemon.
• macOS browser installation - On macOS versions below 13, agent-browser install stops before downloading Chrome for Testing and prints instructions to update macOS or install Chrome manually. Use Software Update if your Mac supports macOS 13 or later, or install Chrome manually from Google's Chrome download page. This check applies when you run agent-browser install; the package installation commands above remain unchanged. If sw_vers -productVersion is unavailable, exits with an error, returns no version, or returns a malformed version, agent-browser install reports a detection error and stops before making a network request.
• Node.js 24+ and pnpm 11+ - Only needed when building from source.
• Rust - Only needed when building from source (see From Source above).

Quick Start

agent-browser open example.com
agent-browser snapshot                    # Get accessibility tree with refs
agent-browser click @e2                   # Click by ref from snapshot
agent-browser fill @e3 "test@example.com" # Fill by ref
agent-browser get text @e1                # Get text by ref
agent-browser screenshot page.png
agent-browser close

Clicks fail early when another element covers the target's click point, for example a consent banner or modal. Dismiss or interact with the reported covering element, then take a fresh snapshot before retrying the original ref. Click and dblclick fail, instead of reporting success, when the element is hidden, disabled, or outside the viewport. click --new-tab opens the link's URL directly, so these checks do not apply to it.

Headless Chromium screenshots hide native scrollbars for consistent image output. Pass --hide-scrollbars false when launching to keep native scrollbars visible.

Traditional Selectors (also supported)

agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"
agent-browser find role button click --name "Submit"

Commands

Core Commands

agent-browser open                    # Launch browser (no navigation); stays on about:blank
agent-browser open <url>              # Launch + navigate to URL (aliases: goto, navigate)
agent-browser read [url]              # Fetch agent-readable text, or read rendered active-tab DOM
agent-browser click <sel>             # Click element (--new-tab to open in new tab)
agent-browser dblclick <sel>          # Double-click element
agent-browser focus <sel>             # Focus element
agent-browser type <sel> <text>       # Type into element
agent-browser fill <sel> <text>       # Clear and fill
agent-browser press <key>             # Press key (Enter, Tab, Control+a) (alias: key)
agent-browser keyboard type <text>    # Type with real keystrokes (no selector, current focus)
agent-browser keyboard inserttext <text>  # Insert text without key events (no selector)
agent-browser keydown <key>           # Hold key down
agent-browser keyup <key>             # Release key
agent-browser hover <sel>             # Hover element
agent-browser select <sel> <val>      # Select dropdown by value or visible label
agent-browser check <sel>             # Check checkbox
agent-browser uncheck <sel>           # Uncheck checkbox
agent-browser scroll <dir> [px]       # Scroll (up/down/left/right, --selector <sel>)
agent-browser scrollintoview <sel>    # Scroll element into view (alias: scrollinto)
agent-browser drag <src> <tgt>        # Drag and drop
agent-browser upload <sel> <files>    # Upload files
agent-browser screenshot [path]       # Take screenshot (--full for full page, saves to a temporary directory if no path)
agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
agent-browser screenshot --if-changed # Recommended: skip unchanged images to save tokens
agent-browser screenshot --threshold 0.01 # Ignore changes affecting at most 1% of pixels
agent-browser screenshot --screenshot-dir ./shots    # Save to custom directory
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf <path>              # Save as PDF
agent-browser snapshot                # Accessibility tree with refs (best for AI)
agent-browser eval <js>               # Run JavaScript (-b for base64, --stdin for piped input)
agent-browser connect <port>          # Connect to browser via CDP
agent-browser stream enable [--port <port>]  # Start runtime WebSocket streaming
agent-browser webmcp list                     # List experimental page tools
agent-browser webmcp invoke <tool> --params @input.json
agent-browser stream status           # Show runtime streaming state and bound port
agent-browser stream disable          # Stop runtime WebSocket streaming
agent-browser close                   # Close browser (aliases: quit, exit)
agent-browser close --all             # Close all active sessions
agent-browser chat "<instruction>"    # AI chat: natural language browser control (single-shot)
agent-browser chat                    # AI chat: interactive REPL mode

When the top-level Chrome/CDP eval result is a value JSON cannot represent, plain output prints its exact JavaScript token, including NaN, Infinity, -Infinity, -0, BigInt literals, and undefined. With --json, data.result stays null and sibling data.unserializable contains the token. MCP text prints the token, and structured responses expose it at structuredContent.response.data.unserializable.

WebMCP (experimental)

WebMCP is enabled by default in agent-browser-managed Chrome. Use --no-webmcp to disable the launch features and proactive context.

Browser responses automatically announce WebMCP tools on first discovery and when the catalog changes. Summaries contain only names, brief descriptions, origins, and frame IDs. Choose a relevant tool, then fetch its full schema with agent-browser webmcp list <tool> --frame <frame-id> --json before invoking it. Schemas and annotations are never included proactively. Unchanged catalogs and pages without tools add no context.

JSON exposes updates as data.webmcp; CLI and MCP text use the same summaries. An omitted field means no update. A one-time status: "ready" update with tools: [] clears previously advertised tools; status: "unavailable" invalidates them when observation fails. Every emitted summary replaces earlier availability, including schema-only changes. After conversation compaction or joining an existing browser session, use webmcp list to recover context. Administrative commands and explicit metadata requests do not append duplicate summaries.

Automatic summaries are limited to 16 tools and 4 KiB of JSON, with descriptions shortened to 160 bytes plus a truncation marker. Names and frame identities are never cut into unusable identifiers; oversized records are omitted. truncated: true indicates shortened descriptions or omitted tools. webmcp list --json retrieves the full catalog; webmcp list <tool> --frame <frame-id> --json retrieves only the selected tool. Full-record changes trigger an update even when the brief description stays the same, so refresh previously fetched schemas after a catalog update.

The daemon subscribes to CDP WebMCP events once per page session and reads its event cache after browser actions. There is no per-action discovery polling or registration grace period. Initial subscription is bounded to one second; unsupported sessions are not repeatedly probed. Explicit webmcp list can retry discovery. Asynchronous registrations appear on the next normal browser response after the event arrives. This describes agent-browser's active tab and frames, not a separately opened preview iframe.

```bash agent-browser open https://ex