`bash
agent-browser tab # List tabs
agent-browser tab new [url] # New tab (optionally with URL)
agent-browser tab # Switch to tab n
agent-browser tab close [n] # Close tab
agent-browser window new # New window
`

$3

`bash
agent-browser frame # Switch to iframe
agent-browser frame main # Back to main frame
`

$3

`bash
agent-browser dialog accept [text] # Accept (with optional prompt text)
agent-browser dialog dismiss # Dismiss
`

$3

`bash
agent-browser trace start [path] # Start recording trace
agent-browser trace stop [path] # Stop and save trace
agent-browser console # View console messages
agent-browser console --clear # Clear console
agent-browser errors # View page errors
agent-browser errors --clear # Clear errors
agent-browser highlight # Highlight element
agent-browser state save # Save auth state
agent-browser state load # Load auth state
`

$3

`bash
agent-browser back # Go back
agent-browser forward # Go forward
agent-browser reload # Reload page
`

$3

`bash
agent-browser install # Download Chromium browser
agent-browser install --with-deps # Also install system deps (Linux)
`

Sessions

Run multiple isolated browser instances:

`bash


Different sessions

The snapshot command supports filtering to reduce output size:

`bash
agent-browser snapshot # Full accessibility tree
agent-browser snapshot -i # Interactive elements only (buttons, inputs, links)
agent-browser snapshot -c # Compact (remove empty structural elements)
agent-browser snapshot -d 3 # Limit depth to 3 levels
agent-browser snapshot -s "#main" # Scope to CSS selector
agent-browser snapshot -i -c -d 5 # Combine options
`

| Option | Description |
|--------|-------------|
| -i, --interactive | Only show interactive elements (buttons, links, inputs) |
| -c, --compact | Remove empty structural elements |
| -d, --depth | Limit tree depth |
| -s, --selector | Scope to CSS selector |

Options

| Option | Description |
|--------|-------------|
| --session | Use isolated session (or AGENT_BROWSER_SESSION env) |
| --headers | Set HTTP headers scoped to the URL's origin |
| --executable-path | Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH env) |
| --json | JSON output (for agents) |
| --full, -f | Full page screenshot / full untruncated network data |
| --truncatejsonvalues | Truncate JSON string values to n chars (default: 500) |
| --name, -n | Locator name filter |
| --exact | Exact text match |
| --headed | Show browser window (not headless) |
| --cdp | Connect via Chrome DevTools Protocol |
| --debug | Debug output |

Selectors

$3

Refs provide deterministic element selection from snapshots:

`bash


1. Get snapshot with refs

`bash
agent-browser click "#id"
agent-browser click ".class"
agent-browser click "div > button"
`

$3

`bash
agent-browser click "text=Submit"
agent-browser click "xpath=//button"
`

$3

`bash
agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"
`

Agent Mode

Use --json for machine-readable output:

`bash
agent-browser snapshot --json


Returns: {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}

agent-browser get text @e1 --json
agent-browser is visible @e2 --json
`

$3

`bash


1. Navigate and get snapshot

`bash
agent-browser open example.com --headed
`

This opens a visible browser window instead of running headless.

Authenticated Sessions

Use --headers to set HTTP headers for a specific origin, enabling authentication without login flows:

`bash


Headers are scoped to api.example.com only

To set headers for multiple origins, use --headers with each open command:

`bash
agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'
`

For global headers (all domains), use set headers:

`bash
agent-browser set headers '{"X-Custom-Header": "value"}'
`

Custom Browser Executable

Use a custom browser executable instead of the bundled Chromium. This is useful for:
- Serverless deployment: Use lightweight Chromium builds like @sparticuz/chromium (~50MB vs ~684MB)
- System browsers: Use an existing Chrome/Chromium installation
- Custom builds: Use modified browser builds

$3

`bash


Via flag

`typescript
import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser';

export async function handler() {
const browser = new BrowserManager();
await browser.launch({
executablePath: await chromium.executablePath(),
headless: true,
});
// ... use browser
}
`

CDP Mode

Connect to an existing browser via Chrome DevTools Protocol:

`bash


Connect to Electron app

Set the AGENT_BROWSER_STREAM_PORT environment variable:

`bash
AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com
`

This starts a WebSocket server on the specified port that streams the browser viewport and accepts input events.

$3

Connect to ws://localhost:9223 to receive frames and send input:

Receive frames:
`json
{
"type": "frame",
"data": "",
"metadata": {
"deviceWidth": 1280,
"deviceHeight": 720,
"pageScaleFactor": 1,
"offsetTop": 0,
"scrollOffsetX": 0,
"scrollOffsetY": 0
}
}
`

Send mouse events:
`json
{
"type": "input_mouse",
"eventType": "mousePressed",
"x": 100,
"y": 200,
"button": "left",
"clickCount": 1
}
`

Send keyboard events:
`json
{
"type": "input_keyboard",
"eventType": "keyDown",
"key": "Enter",
"code": "Enter"
}
`

Send touch events:
`json
{
"type": "input_touch",
"eventType": "touchStart",
"touchPoints": [{ "x": 100, "y": 200 }]
}
`

$3

For advanced use, control streaming directly via the protocol:

`typescript
import { BrowserManager } from 'agent-browser';

const browser = new BrowserManager();
await browser.launch({ headless: true });
await browser.navigate('https://example.com');

// Start screencast
await browser.startScreencast((frame) => {
// frame.data is base64-encoded image
// frame.metadata contains viewport info
console.log('Frame received:', frame.metadata.deviceWidth, 'x', frame.metadata.deviceHeight);
}, {
format: 'jpeg',
quality: 80,
maxWidth: 1280,
maxHeight: 720,
});

// Inject mouse events
await browser.injectMouseEvent({
type: 'mousePressed',
x: 100,
y: 200,
button: 'left',
});

// Inject keyboard events
await browser.injectKeyboardEvent({
type: 'keyDown',
key: 'Enter',
code: 'Enter',
});

// Stop when done
await browser.stopScreencast();
`

Architecture

agent-browser uses a client-daemon architecture:

1. Rust CLI (fast native binary) - Parses commands, communicates with daemon
2. Node.js Daemon - Manages Playwright browser instance
3. Fallback - If native binary unavailable, uses Node.js directly

The daemon starts automatically on first command and persists between commands for fast subsequent operations.

Browser Engine: Uses Chromium by default. The daemon also supports Firefox and WebKit via the Playwright protocol.

Platforms

| Platform | Binary | Fallback |
|----------|--------|----------|
| macOS ARM64 | Native Rust | Node.js |
| macOS x64 | Native Rust | Node.js |
| Linux ARM64 | Native Rust | Node.js |
| Linux x64 | Native Rust | Node.js |
| Windows x64 | Native Rust | Node.js |

Usage with AI Agents

$3

The simplest approach - just tell your agent to use it:

`
Use agent-browser to test the login flow. Run agent-browser --help to see available commands.
`

The --help output is comprehensive and most agents can figure it out from there.

$3

For more consistent results, add to your project or global instructions file:

`markdown


Browser Automation

Use agent-browser for web automation. Run agent-browser --help for all commands.

Core workflow:
1. agent-browser open - Navigate to page
2. agent-browser snapshot -i - Get interactive elements with refs (@e1, @e2)
3. agent-browser click @e1 / fill @e2 "text" - Interact using refs
4. Re-snapshot after page changes
`

$3

For Claude Code, a skill provides richer context:

`bash
cp -r node_modules/agent-browser/skills/agent-browser .claude/skills/
`

Or download:

`bash
mkdir -p .claude/skills/agent-browser
curl -o .claude/skills/agent-browser/SKILL.md \
https://raw.githubusercontent.com/vercel-labs/agent-browser/main/skills/agent-browser/SKILL.md
``

License

Apache-2.0