Agent Browser

agent-browser — AI Browser Automation CLI

Rust-native CLI by Vercel Labs. Persistent daemon per session, CDP-based, deterministic ref selectors (@e1, @e2), JSON output. Built for AI agents.

Repo: github.com/vercel-labs/agent-browser | License: Apache 2.0

Install

# npm (recommended)
npm install -g agent-browser
agent-browser install   # downloads Chrome for Testing

# homebrew
brew install agent-browser && agent-browser install

# cargo
cargo install agent-browser && agent-browser install

# Linux — also install system deps
agent-browser install --with-deps

Upgrade: agent-browser upgrade

Core Concept: Refs

Every snapshot assigns deterministic refs (@e1, @e2, ...) to DOM elements. Use refs instead of CSS selectors — they're stable within a snapshot, semantic, and LLM-friendly.

agent-browser open https://example.com
agent-browser snapshot -i          # interactive elements only
# Output:
#   - heading "Example" [ref=e1]
#   - link "More info" [ref=e2]
#   - button "Submit" [ref=e3]

agent-browser click @e3            # click Submit

After any DOM change (navigation, AJAX, form submit) — re-snapshot to get fresh refs.

Essential Commands

Navigation

agent-browser open 
agent-browser back | forward | reload

Snapshot (primary way to "see" the page)

agent-browser snapshot              # full accessibility tree
agent-browser snapshot -i           # interactive elements only (buttons, inputs, links)
agent-browser snapshot -c           # compact (remove empty nodes)
agent-browser snapshot -d 3         # limit depth
agent-browser snapshot -s "#main"   # scope to selector
agent-browser snapshot --json       # machine-readable

Interaction

agent-browser click 
agent-browser fill  "text"         # clear + type (for inputs)
agent-browser type  "text"         # type without clearing
agent-browser select  "option"     # dropdown
agent-browser check|uncheck        # checkbox
agent-browser hover 
agent-browser press Enter|Tab|Escape    # keyboard
agent-browser press Control+a           # key combo
agent-browser scroll down 500           # scroll page
agent-browser upload  file.pdf     # file upload

Data Extraction

agent-browser get text         # element text
agent-browser get html         # innerHTML
agent-browser get value        # input value
agent-browser get attr  href   # attribute
agent-browser get title             # page title
agent-browser get url               # current URL

Screenshot & PDF

agent-browser screenshot [path]         # to file or temp
agent-browser screenshot --full         # full page scroll capture
agent-browser screenshot --annotate     # numbered labels matching refs
agent-browser pdf output.pdf

Wait

agent-browser wait                     # wait for element visible
agent-browser wait 2000                     # wait ms
agent-browser wait --load networkidle       # wait for network idle
agent-browser wait --url "**/dashboard"     # wait for URL pattern
agent-browser wait --text "Success"         # wait for text
agent-browser wait  --state hidden     # wait for element to disappear

Semantic Locators (alternative to refs)

agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "test@test.com"
agent-browser find placeholder "Search" fill "query"
agent-browser find testid "login-btn" click

Session Management

agent-browser session list              # active sessions
agent-browser --session myapp      # named session
agent-browser close                     # close current
agent-browser close --all               # close all

Tabs

agent-browser tab                   # list tabs
agent-browser tab new [url]         # new tab
agent-browser tab 2                 # switch to tab 2
agent-browser tab close

AI Agent Workflow Pattern

Standard loop for any AI agent:

# 1. Navigate
agent-browser open https://target.com

# 2. Observe (snapshot → LLM reads → decides action)
agent-browser snapshot -i --json

# 3. Act (LLM picks ref from snapshot)
agent-browser fill @e2 "search query"
agent-browser click @e3

# 4. Wait for result
agent-browser wait --load networkidle

# 5. Re-observe (new snapshot after DOM changed)
agent-browser snapshot -i --json

# 6. Extract or continue
agent-browser get text @e5

Repeat 2-5 until task complete. Always close when done.

Batch Execution

When exact sequence is known upfront:

cat  env vars > `./agent-browser.json` > `~/.agent-browser/config.json`

Key env vars:
```bash
AGENT_BROWSER_SESSION=myapp           # default session
AGENT_BROWSER_HEADED=1                # show browser window
AGENT_BROWSER_EXECUTABLE_PATH=/path   # custom Chrome
AGENT_BROWSER_PROXY=http://host:port  # proxy
AGENT_BROWSER_DEFAULT_TIMEOUT=25000   # operation timeout (max 30000)
AGENT_BROWSER_IDLE_TIMEOUT_MS=60000   # daemon auto-shutdown
AGENT_BROWSER_ENCRYPTION_KEY=  # encrypt state files
AGENT_BROWSER_ALLOWED_DOMAINS=a.com,b.com  # restrict navigation
AGENT_BROWSER_MAX_OUTPUT=50000        # truncate output (prevent context flooding)

Config file (agent-browser.json):

{
  "headed": false,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data",
  "userAgent": "my-agent/1.0",
  "screenshotDir": "./shots",
  "colorScheme": "dark"
}

Key CLI flags: --json, --session , --profile , --headed, --proxy , --ignore-https-errors, --annotate, --engine lightpanda, --provider , --content-boundaries, --no-auto-dialog, --debug

Safety Features for AI

--content-boundaries          # wrap untrusted page content in markers
--max-output 50000            # prevent context window flooding
--allowed-domains a.com,b.com # restrict navigation to trusted domains
--action-policy policy.json   # gate destructive actions
--confirm-actions eval,download  # require approval for sensitive ops

Cloud Providers

For scalable/CI deployments: --provider

Supported: AgentCore, Browserbase, Browserless, BrowserUse, Kernel

Gotchas

1. Refs invalidate on DOM change — always re-snapshot after navigation/AJAX/form submit
2. Daemon persists — run agent-browser close explicitly to avoid orphaned processes
3. networkidle unreliable on SPAs — prefer wait --text "X" or wait --url "pattern"
4. Timeout max 30s — keep DEFAULT_TIMEOUT under 30000ms
5. State files contain tokens — use ENCRYPTION_KEY or add to .gitignore
6. Shadow DOM not in snapshots — only light DOM visible
7. Large pages — use snapshot -i -c -d 3 to limit output size
8. Chrome profile lock — close Chrome before using --profile with same profile

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nobrainer-tech
• Source: nobrainer-tech/nobrainer-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.