| 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)"
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
npx agent-browser --session "$SESSION" screenshot /tmp/ui-375.png
npx agent-browser --session "$SESSION" set viewport 768 1024
npx agent-browser --session "$SESSION" screenshot /tmp/ui-768.png
npx agent-browser --session "$SESSION" set viewport 1440 900
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
npx agent-browser --session "$SESSION" click @e2
npx agent-browser --session "$SESSION" fill @e3 "test@example.com"
npx agent-browser --session "$SESSION" snapshot -i
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.
