The snapshot command supports filtering to reduce output size:

`bash
z-agent-browser snapshot # Full accessibility tree
z-agent-browser snapshot -i # Interactive elements only (buttons, inputs, links)
z-agent-browser snapshot -c # Compact (remove empty structural elements)
z-agent-browser snapshot -d 3 # Limit depth to 3 levels
z-agent-browser snapshot -s "#main" # Scope to CSS selector
z-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 |

Token Efficiency: eval vs snapshot

For AI agents, token efficiency is critical. Use the right tool for the job:

$3

| Task | Best Tool | Token Cost |
|------|-----------|------------|
| Find button to click | snapshot -i | ~200-500 |
| Count items on page | eval | ~10 |
| Extract all links | eval | ~50-200 |
| Fill a form | snapshot -i + refs | ~200-500 |
| Check if logged in | eval | ~10 |
| Get table data | eval | ~100-500 |
| Navigate complex UI | snapshot -i | ~200-500 |

$3

Bad (snapshot approach - ~5000 tokens):
`bash
z-agent-browser snapshot # Returns full page, AI parses it
`

Good (eval approach - ~100 tokens):
`bash
z-agent-browser eval "
const rows = [...document.querySelectorAll('tr')];
rows.slice(1, 11).map(r => ({
title: r.cells[0]?.textContent?.trim(),
link: r.querySelector('a')?.href
}));
"


Returns: [{title: "...", link: "..."}, ...]

Rule of thumb:
- Need to CLICK/FILL something? → snapshot -i + refs
- Need to READ/COUNT/EXTRACT data? → eval

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 |
| --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
z-agent-browser click "#id"
z-agent-browser click ".class"
z-agent-browser click "div > button"
`

$3

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

$3

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

Agent Mode

Use --json for machine-readable output:

`bash
z-agent-browser snapshot --json


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

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

$3

`bash


1. Navigate and get snapshot

`bash
z-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
z-agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
z-agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'
`

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

`bash
z-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


Start Chrome with remote debugging

Important: In CDP mode, headless/headed is determined by how Chrome was launched, not by z-agent-browser. The --headed flag has no effect when connecting via CDP.

`bash


Headed CDP (visible browser)

1. Install the Chrome extension
- Install "Playwright MCP Bridge" from the Chrome Web Store
- Or load unpacked from the playwright-mcp repo's extension/ directory

2. Set your extension token and run
`bash
# Set the token from the Chrome extension
export PLAYWRIGHT_MCP_EXTENSION_TOKEN=your-token-here
export AGENT_BROWSER_BACKEND=playwright-mcp

# Commands work the same as native mode
z-agent-browser open "https://example.com"
z-agent-browser snapshot -i
z-agent-browser click @e1
z-agent-browser back
z-agent-browser close
`

The daemon spawns npx @playwright/mcp@latest --extension as a subprocess and communicates via stdio. No separate server needed.

$3

| Variable | Description |
|----------|-------------|
| AGENT_BROWSER_BACKEND | Set to playwright-mcp to use MCP mode (default: native) |
| PLAYWRIGHT_MCP_EXTENSION_TOKEN | Token from the Chrome extension (required for extension mode) |
| PLAYWRIGHT_MCP_COMMAND | Custom command to spawn MCP server (default: npx) |
| PLAYWRIGHT_MCP_ARGS | Space-separated args (default: @playwright/mcp@latest --extension) |

$3

- Feature parity: Not all commands are supported. Streaming, profile mode, and stealth mode are not available in MCP mode.
- Extension required: The Chrome extension must be installed and connected for the MCP server to control your browser.

$3

- AI-assisted browsing: Let AI agents help you navigate complex web apps in your actual browser
- Testing with extensions: Test sites that require specific browser extensions
- Debugging: Watch AI actions in real-time in your browser

Streaming (Browser Preview)

Stream the browser viewport via WebSocket for live preview or "pair browsing" where a human can watch and interact alongside an AI agent.

$3

Set the AGENT_BROWSER_STREAM_PORT environment variable:

`bash
AGENT_BROWSER_STREAM_PORT=9223 z-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

z-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 z-agent-browser to test the login flow. Run z-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 z-agent-browser for web automation. Run z-agent-browser --help for all commands.

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

$3

For Claude Code, install the browser-skill:

`
/plugin marketplace add zm2231/browser-skill
/plugin install browser-skill@browser-skill-marketplace
`

Or manually:

`bash
mkdir -p ~/.claude/skills/browser-automation
curl -o ~/.claude/skills/browser-automation/skill.md \
https://raw.githubusercontent.com/zm2231/browser-skill/main/skills/browser-automation/skill.md
`

Enhanced Fork Features

This fork (zm2231/agent-browser) adds features for bot detection bypass, persistent auth, custom profiles, and more.

$3

`bash
git clone https://github.com/zm2231/agent-browser.git
cd agent-browser
pnpm install
pnpm build
pnpm build:native # requires Rust: https://rustup.rs
npm link
z-agent-browser install
`

$3

Bypass bot detection using playwright-extra with stealth plugin:

`bash
z-agent-browser --stealth open https://bot.sannysoft.com
z-agent-browser snapshot -i


Most bot detection tests pass

Via environment variable

`bash


First session: log in with --persist

Use explicit state file:
`bash
z-agent-browser --state ~/github-auth.json open "https://github.com"
`

$3

Use a persistent Chrome profile directory to run headless with all your existing logins, extensions, and passwords:

`bash


1. Copy your Chrome profile (one-time setup)

Key points:
- Headless by default - no --headed flag needed for background automation
- Uses a COPY of your profile - your real Chrome data is safe
- Keeps extensions, bookmarks, passwords, cookies, localStorage
- Profile location: ~/.z-agent-browser/chrome-profile (recommended)
- Cannot combine with CDP mode

Headless Limitation: Google, Gmail, and other strict sites detect headless Chromium and invalidate sessions. For these sites, use --headed or CDP Mode with real Chrome.app.

Profile Mode vs CDP Mode:

| Feature | Profile Mode | CDP Mode |
|---------|--------------|----------|
| Command | --profile | --cdp or connect |
| Headless support | Yes (default) | Depends on how Chrome was launched |
| Profile data | Uses COPY (safe) | Uses running Chrome's profile |
| Browser process | Playwright launches Chromium | Connects to existing Chrome |
| Best for | Background automation with logins | Interactive debugging, user's actual browser |

$3

`bash
z-agent-browser --user-agent "MyBot/1.0 (compatible)" open https://httpbin.org/user-agent
`

$3

Pass custom Chromium flags:

`bash
z-agent-browser --args "--disable-gpu,--no-sandbox" open https://example.com
`

Common args:
- --disable-gpu: disable GPU acceleration
- --no-sandbox: required in some Docker containers
- --disable-dev-shm-usage: overcome limited /dev/shm in Docker
- --window-size=1920,1080: set initial window size

$3

Skip SSL validation for local dev servers with self-signed certs:

`bash
z-agent-browser --ignore-https-errors open "https://localhost:8443"
`

Note: When changing launch options (like --ignore-https-errors), kill any existing daemon first:
`bash
pkill -f "node.*daemon"; sleep 1
z-agent-browser --ignore-https-errors open "https://localhost:8443"
`

$3

Record browser sessions to WebM:

`bash
z-agent-browser open "https://example.com" --headed
z-agent-browser record start ./demo.webm
z-agent-browser fill @e1 "demo input"
z-agent-browser click @e2
z-agent-browser record stop


Video saved to ./demo.webm

Restart recording with new file

`bash
z-agent-browser tab new https://example.com
`

$3

Omit path to get base64-encoded PNG:

`bash
z-agent-browser screenshot --json


Returns: {"success":true,"data":{"base64":"iVBORw0KGgo..."}}

`bash
z-agent-browser open "https://github.com"
z-agent-browser state load ~/.browser/github-auth.json # Loads into current session
`

$3

Establish persistent CDP connection; subsequent commands omit --cdp:

`bash


Start Chrome with remote debugging

`bash
z-agent-browser open "about:blank"
z-agent-browser open "data:text/html,

Hello

| Variable | Description |
|----------|-------------|
| AGENT_BROWSER_SESSION | Session name for isolation |
| AGENT_BROWSER_HEADED | Set to "1" for visible browser |
| AGENT_BROWSER_STEALTH | Set to "1" for stealth mode |
| AGENT_BROWSER_PERSIST | Set to "1" for auto-persistence |
| AGENT_BROWSER_STATE | Path to state file |
| AGENT_BROWSER_PROFILE | Path to Chrome profile directory |
| AGENT_BROWSER_USER_AGENT | Custom User-Agent string |
| AGENT_BROWSER_ARGS | Comma-separated browser launch args |
| AGENT_BROWSER_IGNORE_HTTPS_ERRORS | Set to "1" to skip SSL validation |
| AGENT_BROWSER_EXECUTABLE_PATH | Custom browser binary path |
| AGENT_BROWSER_EXTENSIONS | Path to browser extensions |
| AGENT_BROWSER_STREAM_PORT | WebSocket port for streaming |
| AGENT_BROWSER_BACKEND | Backend type: native (default) or playwright-mcp |
| PLAYWRIGHT_MCP_COMMAND | Command to spawn MCP server (default: npx) |
| PLAYWRIGHT_MCP_ARGS | Space-separated args for MCP server (default: @playwright/mcp@latest) |
| NO_COLOR | Disable colored output |

$3

--ignore-https-errors with existing daemon: If daemon already has a browser context, new launch options may not apply. Kill daemon before changing options:
`bash
pkill -f "node.*daemon"
``

Acknowledgments

- Playwright MCP by Microsoft - Powers the experimental MCP backend mode
- Playwright by Microsoft - Core browser automation engine
- vercel-labs/agent-browser - Original project this fork is based on

License

Apache-2.0