agent-browser（Agent 浏览器自动化）

Agent Browser

Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallback.

Works with: Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Google Gemini, opencode.

Quick Navigation

When to Use

• Automating browser tasks in AI agent workflows
• Web scraping with AI-friendly output
• Testing web applications with LLM agents
• Managing multiple browser sessions with isolated auth

Core Concepts

Refs (Element References)

The snapshot command returns an accessibility tree where each element has a unique ref like @e1, @e2:

• Deterministic - ref points to exact element from snapshot
• Fast - no DOM re-query needed
• AI-friendly - LLMs can reliably parse and use refs

Architecture

Client-daemon architecture:

1. Rust CLI - parses commands, communicates with daemon
2. Daemon - runs the browser automation engine:

- Default: Node.js daemon (Playwright) - Native (v0.16.0+): native Rust daemon (direct Chrome DevTools Protocol), enabled via --native, AGENT_BROWSER_NATIVE=1, or "native": true - Lightpanda (v0.17.0+): Lightpanda engine, selected via --engine lightpanda or AGENT_BROWSER_ENGINE=lightpanda (implies native mode)

Daemon starts automatically and persists between commands. Startup errors are surfaced directly (v0.17.0+).

v0.8.6 improves daemon reliability by cleaning stale socket/PID files and retrying transient connection errors.

Quick Example

# Navigate and get snapshot
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 input by ref
agent-browser get text @e1                # Get text by ref
agent-browser screenshot page.png         # Save screenshot
agent-browser close

AI Workflow Pattern

Optimal workflow for AI agents:

# 1. Navigate and get snapshot
agent-browser open example.com
agent-browser snapshot -i --json   # AI parses tree and refs

# 2. AI identifies target refs from snapshot

# 3. Execute actions using refs
agent-browser click @e2
agent-browser fill @e3 "input text"

# 4. Get new snapshot if page changed
agent-browser snapshot -i --json

Headed Mode (Debugging)

agent-browser open example.com --headed

Local File Access (v0.9.1)

agent-browser open file:///path/to/doc.pdf --allow-file-access

Cursor-Aware Snapshots (v0.9.1)

agent-browser snapshot -C
agent-browser snapshot --cursor

Session Persistence (v0.10.0)

Automatically save and restore cookies/localStorage across restarts with a named session:

agent-browser --session-name myapp open myapp.com
agent-browser --session-name myapp open myapp.com

State management commands:

agent-browser state list
agent-browser state show myapp
agent-browser state rename myapp myapp-prod
agent-browser state clear myapp-prod
agent-browser state cleanup

Release Updates (v0.12.0–v0.14.0)

• Added keyboard commands for raw keyboard input at the currently focused element (no selector needed).
• Added persistent color scheme selection via --color-scheme and AGENT_BROWSER_COLOR_SCHEME.
• Improved IPC reliability (EAGAIN/backpressure-aware writes) and lowered default Playwright timeout to 25s (configurable via AGENT_BROWSER_DEFAULT_TIMEOUT).
• Improved CDP reconnection and fixed state load when no browser is running.
• Reduced --annotate warning noise when the flag isn’t explicitly passed.

New Tab Clicks (v0.10.0)

agent-browser click @e12 --new-tab

Mobile Safari (iOS)

agent-browser -p ios device list
agent-browser -p ios open https://example.com --device "iPhone 15"
agent-browser tap 200 400
agent-browser swipe 200 600 200 200 500

JSON Output

Use --json for machine-readable output:

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

Critical Prohibitions

• Do not use CSS/XPath selectors when refs are available (use @e1, @e2, etc.)
• Do not forget to close sessions when done
• Do not assume element positions without taking a fresh snapshot
• Do not use old refs after page navigation or content changes (re-snapshot)

Common Commands

# Navigation
agent-browser open <url>
agent-browser back / forward / reload
agent-browser close

# Interaction
agent-browser click <sel>
agent-browser click <sel> --new-tab
agent-browser fill <sel> <text>
agent-browser press <key>
agent-browser hover <sel>
agent-browser select <sel> <val>
agent-browser download <sel> <path>  # v0.7+

# Info
agent-browser get text <sel>
agent-browser get url
agent-browser get title
agent-browser is visible <sel>

# Snapshots & Screenshots
agent-browser snapshot -i --json
agent-browser screenshot [path]

Links

• Documentation
• Changelog
• GitHub
• npm