agent-browser: Free Open-Source Browser Automation CLI for AI Agents

agent-browser is a free, open-source browser automation CLI from Vercel Labs. Your AI agents can use it to inspect, click, type, read, and verify real web pages from the terminal.

With agent-browser, AI coding agents such as Claude Code, Codex, Gemini CLI, OpenCode, Cursor, GitHub Copilot, Goose, and Windsurf can control a browser through stable element refs and avoid dumping thousands of lines of raw HTML into the model context.

When an agent needs the page structure, snapshot returns an accessibility tree with compact element refs. When it needs the page content, read fetches agent-readable text or extracts readable text from the rendered active tab.

A typical loop is open, snapshot, act on a ref such as @e2, and take another snapshot after the page changes. Named sessions, stable tab IDs, optional strict tab pinning, and machine-readable JSON help an agent keep that loop attached to the correct browser state during longer tasks.

Visit agent-browser

Features

Snapshot-Based Context Reduction: Returns an accessibility-tree snapshot with stable refs so agents can act on @e1, @e2, and similar handles while keeping full page HTML out of the prompt.
Flexible Installation: Install the native CLI with npm, Homebrew, or Cargo. A local project dependency is also available when you want to pin the version in package.json.
Dual Browser Modes: The headless mode runs silently in the background for batch operations and production workflows. The headed mode displays a visible browser window for real-time debugging and observing AI behavior.
Native Rust CLI: The CLI communicates with a native daemon that keeps Chrome and session state available across separate commands.
Command Set: Covers navigation, element interaction, form filling, screenshot capture, tab management, cookie handling, network interception, clipboard access, visual diffs, streaming, and more.
Session and Tab Isolation: Named sessions maintain separate cookies, storage, navigation history, and authentication state. Shared CDP sessions can bind to a specific target across commands and daemon restarts, while --pin-tab prevents a closed tab from silently switching the session to another tab.
Semantic Locators: Find elements by ARIA role, text content, label, placeholder, alt text, or test ID.
Smart Snapshot Filtering: Reduce snapshot output size through interactive-only mode, compact mode, depth limiting, or CSS selector scoping.
Agent-Readable Page Text: Use read [url] to prefer Markdown, inspect nearby llms.txt resources, filter sections, print an outline, or read the rendered DOM from the active authenticated tab.
Authentication Headers: Set HTTP headers scoped to specific origins for authenticated browser sessions.
Custom Browser Support: Use lightweight Chromium builds for serverless deployment or connect to existing browser installations.
MCP Server: Run agent-browser mcp to expose browser automation through a stdio Model Context Protocol server with tool profiles.
Plugin System: Add and run out-of-process plugins through the agent-browser plugin command family.
React and Web Vitals Commands: Inspect React component trees, track render activity, classify Suspense boundaries, and collect Core Web Vitals from the CLI.
Accessibility Audits: Run embedded axe-core audits with a11y, filter by WCAG tags, scope checks to a selector, and receive text or structured JSON results across supported frame trees.
WebGPU Testing: Launch Chromium with a WebGPU preset, use hardware backends on macOS and Windows, or use software Vulkan on Linux for browser and CI checks.
Deployment Safeguards: Restrict domains, mark untrusted page content, limit output, require confirmation for sensitive actions, and apply policy gates to plugins and browser commands.
Sandbox and eve Integration: Use @agent-browser/sandbox helpers in Vercel Sandbox, or mount @agent-browser/eve to give an eve agent namespaced browser commands inside its sandbox.

Use Cases

AI Agent Testing: Deploy autonomous testing agents that navigate your application, fill forms, click buttons, and verify UI behavior. Snapshot refs give agents exact element handles that stay tied to the captured page structure.
Web Scraping for AI: Extract data from websites that require JavaScript execution or complex interactions. The agent captures screenshots, fills search forms, navigates pagination, and retrieves rendered content.
E2E Test Workflows: Let a coding agent navigate the application, inspect stable refs, run the required interactions, and translate the successful command sequence into a reproducible test.
Documentation Creation: Capture screenshots and workflow descriptions automatically while navigating your application. The AI can draft documentation and onboarding material from actual interface interactions.
Authenticated Workflow Automation: Skip repetitive login flows during development by using header-based authentication. The agent accesses protected endpoints directly with authorization tokens scoped to specific domains.
Accessibility Regression Checks: Audit a current page or URL with embedded axe-core rules, narrow the run to selected WCAG tags, and consume structured violations in an automated quality check.
API Discovery from Browser Traffic: Capture request and response data in HAR files, include text or binary response bodies when needed, and use the derive-client skill to build a reusable client from recorded traffic.

How to Use It

1. Install the agent-browser CLI.

NPM (Recommended)

npm install -g agent-browser
agent-browser install  # Download Chrome from Chrome for Testing

Project Installation

npm install agent-browser
agent-browser install

Homebrew (macOS)

brew install agent-browser
agent-browser install

Cargo (Rust)

cargo install agent-browser
agent-browser install

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
pnpm link --global
agent-browser install

Linux Dependencies

agent-browser install --with-deps
# Or manually: npx playwright install-deps chromium

Upgrade and Diagnose

agent-browser upgrade
agent-browser doctor
agent-browser doctor --fix

2. The basic command loop to verify your setup.

agent-browser open example.com
agent-browser snapshot                    # Returns accessibility tree with refs
agent-browser click @e2                   # Click element using ref from snapshot
agent-browser fill @e3 "[email protected]" # Fill input field
agent-browser get text @e1                # Read text
agent-browser screenshot page.png
agent-browser close

3. These are your primary tools for navigation and interaction.

open: Launch a browser on about:blank.
open <url>: Navigate to a URL (aliases: goto, navigate).
click <sel>: Click an element.
dblclick <sel>: Double-click an element.
focus <sel>: Bring an element into focus.
type <sel> <text>: Type text into an element.
fill <sel> <text>: Clear an input and fill it.
press <key>: Press a specific key (e.g., Enter, Tab, Control+a).
keyboard type <text>: Type with real keystrokes into the focused element.
keyboard inserttext <text>: Insert text directly and skip key events.
keydown/keyup <key>: Hold or release a key.
hover <sel>: Hover the mouse over an element.
select <sel> <val>: Choose an option in a dropdown.
check/uncheck <sel>: Toggle checkboxes.
scroll <dir> [px]: Scroll up, down, left, or right.
scrollintoview <sel>: Scroll until an element is visible.
drag <src> <tgt>: Drag one element to another.
upload <sel> <files>: Upload files to a file input.
screenshot [path]: Save a screenshot (use --full for the whole page).
screenshot --annotate: Save a screenshot with numbered element labels.
pdf <path>: Save the page as a PDF.
eval <js>: Execute custom JavaScript on the page.
read [url]: Fetch agent-readable text from a URL or read the rendered DOM of the active tab. Options include --outline, --filter, --llms index, --llms full, --require-md, and --json.
a11y [url]: Run an embedded axe-core accessibility audit, with optional WCAG tag and selector filters.
chat "instruction": Ask the built-in AI chat command to control the browser from natural language. It requires an AI Gateway API key.
mcp: Start the stdio MCP server for clients that can call Model Context Protocol tools.

4. Use snapshot to give an agent a compact map of the current page. Filter the map when the full accessibility tree contains more detail than the next action needs.

-i, --interactive: Show only interactive elements (buttons, inputs, links).
-c, --compact: Remove empty structural elements.
-d, --depth <n>: Limit the tree depth.
-s, --selector <sel>: Scope the snapshot to a specific CSS selector.
--json: Output raw JSON for machine parsing.

Example Workflow:

agent-browser snapshot -i -c  # Get a compact, interactive-only tree

5. You can select elements in three ways.

Refs (Recommended): Use @e1, @e2 from the snapshot. This is deterministic and fast.

CSS/XPath: Use standard selectors like #submit or xpath=//button.

Semantic Locators: Find elements by their human-readable attributes.

find role <role> <action>: e.g., find role button click --name "Submit"
find text <text> <action>: e.g., find text "Sign In" click
find label <label> <action>: e.g., find label "Email" fill "[email protected]"
find placeholder <ph> <action>: Find by input placeholder.
find alt/title/testid: Find by alt text, title attribute, or data-testid.
find first/last/nth: Select specific matches (e.g., find nth 2 "a" text).

6. Read page content, inspect individual values, or verify UI states.

Read a Page:

agent-browser read https://example.com/article
agent-browser read https://docs.example.com --outline
agent-browser read https://docs.example.com --llms index --filter auth
agent-browser read  # Read the rendered active tab

Get Info:

get text <sel>: Read text content.
get html <sel>: Get inner HTML.
get value <sel>: Get input value.
get attr <sel> <attr>: Get an attribute (like href).
get title / get url: Get page metadata.
get count <sel>: Count matching elements.
get box <sel>: Get bounding box coordinates.

Check State:

is visible <sel>
is enabled <sel>
is checked <sel>

7. Wait for a selector, text, URL, load state, or JavaScript condition before the next action depends on it.

wait <selector>: Wait for an element to appear.
wait <ms>: Pause for a fixed number of milliseconds.
wait --text "Welcome": Wait for text to appear.
wait --url "**/dash": Wait for the URL to match a pattern.
wait --load networkidle: Wait until network traffic stops.
wait --fn "window.ready === true": Wait for a JS condition.

8. Emulate the browser conditions required by the test.

set viewport <w> <h>: Change window size.
set device <name>: Emulate a device (e.g., “iPhone 14”).
set geo <lat> <lng>: Set geolocation coordinates.
set offline [on|off]: Toggle offline mode.
set headers <json>: Add global HTTP headers.
set credentials <u> <p>: Set HTTP Basic Auth.
set media [dark|light]: Emulate color schemes.

9. Manage session data to handle logins and preferences.

Cookies: cookies (list), cookies set <name> <val>, cookies clear.

Storage: storage local (list), storage local set <k> <v>, storage local clear. (Same for session storage).

Authenticated Sessions: Use headers to bypass login UIs.

agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

10. Intercept and manipulate network traffic.

network route <url>: Intercept requests.
network route <url> --abort: Block requests (e.g., ads).
network route <url> --body <json>: Mock API responses.
network route '*' --abort --resource-type script: Block a specific CDP resource type.
network requests: View tracked requests (use --filter to narrow down).
network har start / network har stop [output.har]: Record browser traffic as a HAR file. Text response bodies are embedded by default; use --content all for binary bodies or --content none for metadata only.

Live Preview: Every session starts a WebSocket stream server on an operating-system-assigned port. Check it with stream status. Set AGENT_BROWSER_STREAM_QUALITY, AGENT_BROWSER_STREAM_MAX_WIDTH, and AGENT_BROWSER_STREAM_MAX_HEIGHT before launch when a remote viewer needs smaller frames. WebSocket clients can also request a frame-rate cap or acknowledgment-based pacing.

11. Keep tabs, windows, and frames attached to explicit handles.

tab: List tabs with stable IDs such as t1, t2, and optional labels.
tab new [url]: Open a new tab.
tab new --label docs [url]: Open a labeled tab.
tab <tN|label>: Switch to a stable tab ID or label.
tab close [tN|label]: Close the current tab, a tab ID, or a labeled tab.
tab <targetId>: Switch with a CDP target ID that persists across daemon restarts.
window new: Open a new window.
frame <sel>: Switch context to an iframe.
frame main: Return to the main page.

12. Handle dialogs and inspect failures.

Dialogs: dialog accept [text] (handle alerts/prompts) or dialog dismiss.

Debug:

trace start/stop [path]: Record execution traces.
console: View browser console logs.
errors: View page errors.
highlight <sel>: Visually highlight an element.
state save/load <path>: Save or load full authentication state (cookies/storage) to a file.
doctor: Diagnose Chrome, daemon state, config files, security, providers, network reachability, and headless launch behavior.
a11y [url]: Run accessibility checks in the current CDP page or navigate to a URL first. Safari and iOS WebDriver sessions do not support this command.

Headed Mode: Run with --headed to see the browser window.

CDP Mode: Connect to an existing browser (Chrome/Electron) via the Chrome DevTools Protocol using --cdp <port>.

Auto-Connect: Use --auto-connect or AGENT_BROWSER_AUTO_CONNECT=1 to discover a running Chrome instance with remote debugging enabled.

13. Run isolated sessions or bind several agents to separate tabs in one shared Chrome instance.

agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com
# Reuse saved cookies and localStorage under a stable session key
agent-browser --session agent1 --restore open site-a.com
# Keep two shared-CDP sessions attached to their own tabs
agent-browser --session agent1 --cdp 9222 --pin-tab open site-a.com
agent-browser --session agent2 --cdp 9222 --pin-tab open site-b.com

Restore sessions save state periodically and when the browser closes. The default one-hour idle timeout closes inactive headless sessions. Set AGENT_BROWSER_IDLE_TIMEOUT_MS=0 to disable that cleanup. State files contain session tokens. Keep them out of version control or set AGENT_BROWSER_ENCRYPTION_KEY to encrypt saved state.

14. Use a custom Chromium executable or the sandbox helper package in environments such as AWS Lambda and Vercel Sandbox.

agent-browser --executable-path /path/to/chromium open example.com

npm install @agent-browser/sandbox @vercel/sandbox

15. Inspect React apps, collect Web Vitals, and audit accessibility.

agent-browser open --enable react-devtools https://example.com
agent-browser react tree
agent-browser react inspect <fiberId>
agent-browser react renders start
agent-browser react renders stop
agent-browser react suspense
agent-browser vitals https://example.com
agent-browser a11y https://example.com --tags wcag2a,wcag2aa

16. Test WebGPU pages with the launch preset, then verify the rendering path.

agent-browser --webgpu open https://example.com
agent-browser screenshot webgpu-page.png
agent-browser doctor --webgpu

WebGPU screenshots work headlessly on macOS. Windows requires headed mode in a logged-in desktop session, while Linux requires headed mode with Xvfb for captured WebGPU canvas output. Linux also needs a Vulkan loader and Mesa Vulkan drivers for the default software backend.

17. Add deployment controls when an AI agent will browse untrusted pages or perform sensitive actions.

agent-browser --allowed-domains "example.com,*.example.com" open example.com
agent-browser --content-boundaries --max-output 50000 snapshot
agent-browser --confirm-actions eval,download open example.com

The domain allowlist also blocks disallowed subresources, WebSocket connections, beacons, and WebRTC bypasses in supported Chromium sessions. It requires a fresh controllable browser context and rejects launch paths where equivalent containment cannot be installed before page scripts run.

18. Integrate the CLI into AI workflows through prompts, project instructions, skills, or MCP.

Direct Prompting: Tell the agent, “Use agent-browser to test the login flow.”

System Instructions: Add a section to your AGENTS.md, CLAUDE.md, or system prompt explaining the “Open -> Snapshot -> Click @ref” workflow.

Skills: Use the skills installer path for coding assistants that understand agent skills.

npx skills add vercel-labs/agent-browser
agent-browser skills get core

MCP Server: Start the stdio MCP server when your agent environment can call Model Context Protocol tools.

agent-browser mcp

Pros

Context Savings: snapshot -i and snapshot -c return only the page details needed for the next action.
Broad Inspection: Inspect text, accessibility, React, Web Vitals, networks, HAR bodies, screenshots, and PDFs.
Stable Handles: Snapshot refs, tab IDs, CDP targets, and tab pinning identify the intended browser object.
Performance: The native Rust CLI and daemon architecture keep repeated browser commands fast after the first launch.
Session Recovery: Restore sessions save cookies and localStorage periodically; an encryption key protects saved state at rest.
Agent Integrations: Call agent-browser through project instructions, skills, MCP, or capability-scoped plugins.

Cons

Environment Dependencies: Chrome, system libraries, permissions, and network access are required.
Chrome-Centered Default: Standard automation uses Chrome or Chromium. iOS Safari requires macOS, Xcode, Appium, and device setup.
AI Chat Key: Built-in chat requires an AI Gateway API key.
Sensitive State: Plain state files contain cookies and session tokens.

Alternatives and Related Resources

FAQs

Q: What should I do when a ref click is blocked by an overlay?
A: The error identifies the element covering the click point, such as a consent banner or modal. Interact with that element first, then take a fresh snapshot before retrying the original action.

Q: Do element refs survive navigation or major page updates?
A: Treat refs as handles for the snapshot that produced them. Take a new snapshot after navigation or a significant DOM change, then use the new refs for the next action.

Q: Can accessibility audits run offline or under a strict Content Security Policy?
A: Yes. The axe-core engine is embedded in the binary and does not rely on a page-provided window.axe. The audit requires a CDP browser and is unavailable in Safari and iOS WebDriver sessions.

Q: Is a Chrome remote-debugging port safe to leave open?
A: Any local process can connect to the port and control the browser. Use it only on a trusted machine, close the attached Chrome instance when the task ends, and protect any state file created from that session.

Q: Does the live stream deliver every captured frame?
A: The stream keeps the newest frame when a client falls behind. Use acknowledgment pacing when a viewer should receive only one frame at a time. The separate record command captures through CDP and does not depend on stream frame delivery.

Last Updated: Sep 08, 2026