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

agent-browser is a free, open-source browser automation CLI from Vercel Labs for AI agents that need to inspect, click, type, and verify real web pages.

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.

Traditional browser automation workflows often push large HTML payloads into the model context. That costs tokens, slows iteration, and makes element selection harder for agents.

agent-browser uses a snapshot-based workflow built around refs such as @e1 and @e2. It’s a great way to cut context usage while keeping browser actions deterministic enough for agentic coding workflows.

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.
Rust Performance: The underlying Rust CLI delivers faster startup times, lower resource consumption, and more stable execution compared to pure JavaScript implementations.
Command Set: Covers navigation, element interaction, form filling, screenshot capture, tab management, cookie handling, network interception, clipboard access, visual diffs, streaming, and more.
Session Isolation: Multiple browser instances run independently through named sessions. Each session maintains separate cookies, storage, navigation history, and authentication state.
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.
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.
Sandbox Helpers: Use @agent-browser/sandbox helpers for hosted environments such as Vercel Sandbox and Eve.

Use Cases

AI Agent Testing: Deploy autonomous testing agents that navigate your application, fill forms, click buttons, and verify UI behavior. The snapshot mechanism lets agents understand page structure and locate elements without fragile selectors.
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 Generation: Generate end-to-end test scripts automatically by showing the AI a workflow once. The agent observes element references, records interactions, and produces reproducible test code.
Documentation Creation: Capture screenshots and workflow descriptions automatically while navigating your application. The AI generates user guides, release notes, and onboarding materials based on 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.

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

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 without 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.
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. The snapshot command is the most critical feature for AI. You can filter the output to save tokens.

-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. Use these commands to read data or verify UI states.

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. Modern web pages are dynamic. Use wait to prevent errors.

wait <selector>: Wait for an element to appear.
wait <ms>: Pause for X 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. You can spoof the browser environment to test different conditions.

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 network traffic as a HAR file.

11. Handle complex multi-context workflows.

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.
window new: Open a new window.
frame <sel>: Switch context to an iframe.
frame main: Return to the main page.

12. Dialogs & Debugging.

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.

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. You can run multiple isolated browser instances simultaneously. Each session has its own cookies, storage, and history.

agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

14. Custom Browser Executable. For serverless environments such as AWS Lambda or Vercel Sandbox, you can use a custom Chromium build or the sandbox helper package.

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

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

15. React apps and performance checks have dedicated commands.

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

16. You can integrate this CLI into AI workflows in four ways:

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: The snapshot -i and snapshot -c options keep browser context smaller by sending only the parts an agent needs for the next action.
Granular Control: You can control mouse movement, keyboard input, cookies, storage, network routing, HAR capture, screenshots, PDFs, and JavaScript evaluation from one CLI.
Robust Locators: The combination of Snapshot Refs (@e1) and Semantic Locators (find role) covers almost every selection scenario.
Performance: The native Rust CLI and daemon architecture keep repeated browser commands fast after the first launch.
Session Management: Isolated sessions let you run multiple agents, such as separate buyer and seller flows, with separate cookies and storage.
Agent Integrations: The MCP server, skills path, plugin system, and sandbox helpers make the CLI easier to wire into modern AI coding workflows.

Cons

Setup Still Matters: Browser automation depends on Chrome, system libraries, permissions, and network access. Run agent-browser doctor when a local or CI environment behaves differently than expected.
Chrome-Centered Default: The standard path uses Chrome from Chrome for Testing or another Chromium-compatible browser. iOS Safari control is available through the iOS provider, but it requires macOS, Xcode, Appium, and simulator or device setup.
AI Chat Requires a Key: The chat command needs an AI Gateway API key, so the no-key experience applies to browser automation commands, not to the built-in chat agent.

Alternatives & Related Resources

Page Agent: Add An AI Agent to Your Web Page with One Script Tag.
Playwright Documentation: The underlying browser automation library that powers agent-browser. Learn advanced techniques for handling frames, dialogs, and complex interactions.
Chrome DevTools Protocol: The CDP specification behind agent-browser connections to external browser instances.
Agent Browser Docs: Read the agent-browser documentation, command reference, configuration details, and integration notes.
Automate Anything: 10 Best & Open-source AI Agents.

FAQs

Q: Can I use my own Chrome browser instead of the downloaded one?
A: Yes. You can specify a custom path using the --executable-path flag or the AGENT_BROWSER_EXECUTABLE_PATH environment variable.

Q: How do I handle multi-step authentication?
A: You can use agent-browser state save auth.json after logging in manually or via script. For subsequent runs, use agent-browser state load auth.json to restore your cookies and local storage.

Q: Does it support JavaScript execution?
A: Yes. You can use agent-browser eval "console.log('hello')" to run arbitrary JavaScript on the page.

Q: Can I run this in a Docker container?
A: Absolutely. You will need to install the necessary system dependencies (using agent-browser install --with-deps or manually installing Playwright deps). You should also run with the --headless flag (default) to avoid display errors.

Q: How do I install agent-browser for an AI coding assistant?
A: Install the CLI with npm install -g agent-browser, then run agent-browser install. For assistants that support skills, run npx skills add vercel-labs/agent-browser and use agent-browser skills get core when the agent needs the current workflow instructions.

Q: Does agent-browser include an MCP server?
A: Yes. Run agent-browser mcp to start the stdio MCP server. The default core profile keeps the exposed tool surface smaller, and additional tool profiles are available when you need broader CLI coverage.

Q: Can agent-browser inspect React apps?
A: Yes. Launch the page with agent-browser open --enable react-devtools <url>, then use commands such as react tree, react inspect, react renders, react suspense, and vitals.

Q: Is agent-browser free and open source?
A: Yes. The CLI is open source under the Apache-2.0 license. Some optional integrations, remote browser providers, or AI chat usage may require separate accounts, API keys, or paid infrastructure.

Last Updated: June 24, 2026