agent-browser

name	agent-browser
description	Use when you need to screenshot or drive a dev server and the shared Chrome is unavailable or contended — e.g. parallel Conductor workspaces: headless per-workspace browser via npx agent-browser.

agent-browser — headless per-workspace browser

Browser automation CLI from Vercel Labs. Native Rust binary driving Chrome/Chromium over CDP — no Playwright, no shared Chrome window. Each --session gets its own browser instance, cookies, and history, so parallel Conductor workspaces never fight over tabs.

Needs node/npx. Run every command through npx agent-browser ... (or agent-browser if installed globally with npm i -g agent-browser). First use on a machine may need npx agent-browser install to download Chrome for Testing; existing Chrome, Brave, Playwright, and Puppeteer installs are detected automatically.

Isolate the workspace first

SESSION="$(npx agent-browser session id --scope worktree --prefix dev-loop)"
# Then pass --session "$SESSION" on every call, or export AGENT_BROWSER_SESSION="$SESSION"

The browser persists via a background daemon, so chaining commands with && is safe.

The ui-iterate loop

Screenshot the affected route at all three widths, then critique the images:

URL="http://localhost:${CONDUCTOR_PORT:-3000}/route-you-changed"

npx agent-browser --session "$SESSION" open "$URL"
npx agent-browser --session "$SESSION" wait --load networkidle

npx agent-browser --session "$SESSION" set viewport 375 812   # phone
npx agent-browser --session "$SESSION" screenshot /tmp/ui-375.png

npx agent-browser --session "$SESSION" set viewport 768 1024  # tablet
npx agent-browser --session "$SESSION" screenshot /tmp/ui-768.png

npx agent-browser --session "$SESSION" set viewport 1440 900  # desktop
npx agent-browser --session "$SESSION" screenshot /tmp/ui-1440.png

Read each PNG with the Read tool and critique it (hierarchy, spacing, states) per the ui-iterate skill. Add --full to screenshot for the full page instead of the viewport.

Interact via accessibility-tree refs

snapshot prints the accessibility tree with stable @eN element refs — more reliable than CSS selectors for driving state (hover, open menus, filled forms) before a shot:

npx agent-browser --session "$SESSION" snapshot -i        # interactive elements only, with refs
npx agent-browser --session "$SESSION" click @e2          # click by ref
npx agent-browser --session "$SESSION" fill @e3 "[e-mail]"  # clear + fill by ref
npx agent-browser --session "$SESSION" snapshot -i        # re-snapshot after the page changes

Refs go stale on navigation or DOM changes — always re-run snapshot before reusing them. If a click fails because another element covers the target (consent banner, modal), dismiss the reported covering element and take a fresh snapshot before retrying.

Done? Close it

npx agent-browser --session "$SESSION" close

More commands (wait --text, hover, press, scroll, diff screenshot, auth/state): npx agent-browser --help, or npx agent-browser skills get core for the full workflow guide served by the installed CLI. skills get dogfood is an adversarial exploratory-QA pass, which complements a design review of a surface you already know about.

Which browser tool, and when

Two browser lanes exist here and they must not fight over the same Chrome.

claude-in-chrome drives your real, logged-in browser. Use it when the session needs your cookies, an authenticated app, or you want to watch what happens.

agent-browser runs its own headless Chrome. Use it whenever the shared browser would be contended or is unavailable: parallel Conductor workspaces, background runs, anything unattended. Always pass --session <workspace> and --pin-tab, which is what keeps two workspaces from adopting each other's tabs.

Requires Node 24 or newer. On an older Node the CLI still runs but npm prints an engine warning; if a command behaves strangely, check the Node version before debugging further.

Accessibility, without hand-rolling it

npx agent-browser --session "$SESSION" a11y --tags wcag2a,wcag2aa

Runs axe-core in-page, offline and CSP-safe, scoped by selector and aware of iframes. Prefer it to writing WCAG checks by hand in a review.