| name | agent-browser |
| description | Use this skill for browser automation. |
agent-browser
A CLI tool for browser automation. It maintains a persistent browser session with cookies - login once and stay authenticated across all subsequent navigations.
Before You Start
Use agent-browser only for interaction
For reading or fetching web content, prefer standard web search and
fetch tools. Use agent-browser only when the task requires interaction:
clicking, form submission, or stateful navigation.
Subagent safety gate
If running as a subagent, you MUST load the testing-safety-protocol
skill before using agent-browser. Only proceed if the protocol permits.
If it does not permit, stop and do not use agent-browser.
--headed
- Primary agent (interactive session with user): always
--headed
- Subagent: headless by default; use
--headed only if explicitly instructed
Prerequisites
If agent-browser is not installed, it is a system-level CLI tool. Load the installing-dependencies skill, inform the user what needs to be installed and where it writes, and wait for explicit permission before proceeding.
Session
agent-browser keeps a single browser session. Cookies persist across open calls as long as the session is alive.
agent-browser session --json
agent-browser session list --json
Opening a browser
agent-browser close && agent-browser open https://example.com [--headed]
agent-browser set viewport 1920 1080
agent-browser open https://example.com/dashboard [--headed]
--headed follows the decision in "Before You Start".
Browser settings
agent-browser set viewport 1920 1080
agent-browser set media dark
agent-browser set media light
agent-browser set headers '{"Accept-Language": "en-US"}'
Closing the session
close destroys the session and deletes all cookies. Only use it when you want a completely fresh start or are fully done with the task. After closing, any authenticated site will require re-login.
agent-browser close
Snapshot
Snapshot returns the current page's interactive elements, each assigned a reference handle (@e1, @e2, ...). Always take a fresh snapshot before interacting, and re-snapshot whenever the page content changes (navigation, modal open/close, AJAX update).
agent-browser snapshot -i --json
Interaction
All interaction commands use @ref handles from the most recent snapshot.
agent-browser click @e1
agent-browser fill @e2 "text"
agent-browser type @e2 "text"
agent-browser press Enter
agent-browser select @e3 "option-value"
agent-browser check @e4
agent-browser hover @e5
agent-browser scroll down 500
Cookie banners
After opening any public-facing page, check for a cookie consent banner and dismiss it before proceeding - unless the user explicitly asks to leave it for debugging.
agent-browser snapshot -i --json
agent-browser click @eX
Navigation
agent-browser open https://example.com
agent-browser back
agent-browser forward
agent-browser reload
Waiting
agent-browser wait @e1
agent-browser wait 2000
agent-browser wait --text "Success"
Prefer wait @ref or wait --text over a fixed-time wait - they resolve as soon as the condition is met and fail fast if it never arrives.
Extracting Data
agent-browser get text @e1 --json
agent-browser get value @e2 --json
agent-browser get html @e1 --json
agent-browser get attr data-id @e1 --json
agent-browser get title --json
agent-browser get url --json
agent-browser get box @e1 --json
Reading page text
agent-browser eval "document.body.innerText.split('\n').slice(0, 80).join('\n')"
Screenshots
Always save to /tmp/agent-screenshots/ to avoid polluting the project directory. Replace YYYYMMDD-HHMMSS with the actual timestamp (e.g. 20260220-143000).
mkdir -p /tmp/agent-screenshots
agent-browser screenshot /tmp/agent-screenshots/YYYYMMDD-HHMMSS-description.png
agent-browser screenshot /tmp/agent-screenshots/YYYYMMDD-HHMMSS-description.png --full
DevTools
Console and errors
console captures all log levels (log, warn, error, debug). errors is a subset showing only page errors.
agent-browser console --json
agent-browser console --clear
agent-browser errors --json
Cookies and storage
agent-browser cookies get --json
agent-browser cookies clear
agent-browser storage local --json
agent-browser storage session --json
Network
agent-browser network requests --json
agent-browser network requests --filter "api" --json
agent-browser network requests --clear
agent-browser network route "*/api/*" --abort
agent-browser network route "*/api/*" --body '{"mock":true}'
agent-browser network unroute
JavaScript evaluation
agent-browser eval "window.location.href"
agent-browser eval "localStorage.getItem('token')"
agent-browser eval "document.title"
Authentication
For form-based login:
agent-browser open https://example.com/login [--headed]
agent-browser snapshot -i --json
agent-browser fill @eUsername "user@example.com"
agent-browser fill @ePassword "secret"
agent-browser click @eSubmit
For token-based APIs or localized content, inject headers before navigating:
agent-browser set headers '{"Authorization": "Bearer <token>"}'
agent-browser set headers '{"Accept-Language": "zh-CN"}'
agent-browser open https://example.com/api/resource [--headed]
Debugging
agent-browser highlight @e1
agent-browser trace start
agent-browser trace stop /tmp/trace.zip
Recovery when browser stops responding
pkill loses all cookies. After recovery, re-login to any authenticated sites.
pkill -x agent-browser
sleep 5
agent-browser open https://example.com --headed
agent-browser set viewport 1920 1080