agent-browser CLI Reference

When to use this skill

Prefer programmatic tools first (CLIs, APIs, MCP servers). Use agent-browser when the task needs a visual browser (OAuth login, dashboards, visual verification), no CLI/API alternative exists, or the user explicitly asks to "open"/"browse"/"check the site"/"take a screenshot".

Do NOT use Playwright MCP tools. Always use the agent-browser CLI instead.

The one rule: every session is named and closed

agent-browser runs a persistent per-session daemon that owns a real "Chrome for Testing" browser. That daemon outlives the CLI — the browser keeps running (and, on an auto-refreshing page, keeps pegging a CPU core) until something closes it. On shared fleet/worker hosts a leaked browser starves the box (CTL-1500). So:

Every command carries --headed --session <name> — a short, task-specific name (e.g. ctl-1500-verify, gh-review). Never the implicit default session: it collides across concurrent workers and is the hardest leak to attribute.
Close in the same turn you finish: agent-browser --session <name> close. If you took a wrong turn, close before starting over — never leave a session open "in case".
Never write an open-loop without a guaranteed close (e.g. until agent-browser --session s open <url>; do sleep …; done) — each failed open can spawn/adopt a browser and a loop that exits without closing strands them. If you must poll, open once, then wait/reload, and close in a trap/finally.
On a worker/CI host, close immediately — the host reaper (orphan-sweep vector 5) is a backstop, not a substitute.