agent-browser

Automates real browser interactions: navigating websites, clicking buttons, filling forms, taking screenshots, extracting data, and testing web apps. Activate whenever the user asks to open a URL, che

SKILL.md

GitHub

Browser Automation with agent-browser

How it works

agent-browser controls a headless Chromium instance. The core loop is:

  1. Open a page.
  2. Snapshot the accessibility tree to discover interactive elements. Each element gets a short ref like @e1.
  3. Act on elements using their refs.
  4. Re-snapshot after any action that changes the DOM (navigation, form submit, tab switch, dynamic content load).

Refs are ephemeral — they become stale after DOM changes. Always re-snapshot before acting on a changed page.

agent-browser open https://example.com
agent-browser snapshot -i          # interactive elements only
agent-browser fill @e2 "hello"
agent-browser click @e3
agent-browser snapshot -i          # re-snapshot after click

Choosing locators: refs vs semantic find

Use refs (@e1) by default — they are fast, unambiguous, and come directly from snapshot -i. Use semantic find when:

  • You know the label/text but have not taken a snapshot yet.
  • You need to target an element by role, label, or visible text across page changes without re-snapshotting.
  • You are writing a reusable automation sequence where refs would be fragile.
# Ref-based (preferred in interactive sessions)
agent-browser click @e3

# Semantic (useful for scripted flows)
agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "user@test.com"
agent-browser find first ".item" click
agent-browser find nth 2 "a" text

Common workflows

Fill and submit a form

agent-browser open https://example.com/form
agent-browser snapshot -i
# Read the output: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]

agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i   # verify the result page

Log in once, reuse the session

# Initial login
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "username"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

# Later — skip login
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

Record a polished demo video

Explore the page first (so you know which refs to use), then start recording for a clean take. Recording creates a fresh context but preserves cookies and storage from your session.

# Rehearse
agent-browser open https://app.example.com
agent-browser snapshot -i

# Record
agent-browser record start ./demo.webm      # captures from current page
agent-browser click @e1
agent-browser fill @e2 "demo input"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser record stop                    # saves video

agent-browser record restart ./take2.webm    # stop current + start fresh

Extract data from a page

agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e4              # single element text
agent-browser get attr @e5 href         # link target
agent-browser get html @e6              # raw innerHTML
agent-browser get count ".product-card" # how many items matched
agent-browser eval "JSON.stringify([...document.querySelectorAll('.price')].map(e => e.textContent))"

Take a screenshot or PDF

agent-browser screenshot              # to stdout (inline in conversation)
agent-browser screenshot page.png     # save to file
agent-browser screenshot --full       # full-page capture
agent-browser pdf output.pdf          # export as PDF

When to re-snapshot

Re-snapshot (agent-browser snapshot -i) whenever:

  • You clicked a link or submitted a form (page navigation).
  • A button triggered dynamic content (modal, accordion, tab switch).
  • You scrolled and expect lazy-loaded elements.
  • An action returned an error about a stale ref.

You do not need to re-snapshot after fill, type, hover, focus, or reading data with get — these do not change the element tree.


Error recovery

Symptom Likely cause Fix
"ref @eN not found" Stale refs after DOM change Re-snapshot, use new refs
Click does nothing Element obscured or not yet visible scrollintoview @eN then click, or wait @eN first
Page blank after open SPA still loading wait --load networkidle or wait --text "expected"
Cannot find element Element inside iframe frame "#iframe-id" then snapshot
Dialog blocking interaction Unhandled alert/confirm dialog accept or dialog dismiss
Need to debug visually Headless mode hides UI open <url> --headed to watch live

Command reference

Navigation

agent-browser open <url>              # navigate (add --headed to see the browser)
agent-browser back                    # history back
agent-browser forward                 # history forward
agent-browser reload                  # reload page
agent-browser close                   # close browser

Snapshot

agent-browser snapshot                # full accessibility tree
agent-browser snapshot -i             # interactive elements only (recommended)
agent-browser snapshot -c             # compact output
agent-browser snapshot -d 3           # limit tree depth
agent-browser snapshot -s "#main"     # scope to CSS selector

Interactions

agent-browser click @e1               # click
agent-browser dblclick @e1            # double-click
agent-browser fill @e2 "text"         # clear field then type
agent-browser type @e2 "text"         # type without clearing
agent-browser press Enter             # press key
agent-browser press Control+a         # key combo
agent-browser keydown Shift           # hold key
agent-browser keyup Shift             # release key
agent-browser hover @e1               # hover
agent-browser focus @e1               # focus element
agent-browser check @e1               # check checkbox
agent-browser uncheck @e1             # uncheck checkbox
agent-browser select @e1 "value"      # select dropdown option
agent-browser scroll down 500         # scroll page
agent-browser scrollintoview @e1      # scroll element into view
agent-browser drag @e1 @e2            # drag and drop
agent-browser upload @e1 file.pdf     # upload file

Read data

agent-browser get text @e1            # element text
agent-browser get html @e1            # innerHTML
agent-browser get value @e1           # input value
agent-browser get attr @e1 href       # attribute value
agent-browser get title               # page title
agent-browser get url                 # current URL
agent-browser get count ".item"       # count matching elements
agent-browser get box @e1             # bounding box

Check state

agent-browser is visible @e1          # visibility check
agent-browser is enabled @e1          # enabled check
agent-browser is checked @e1          # checked state

Wait

agent-browser wait @e1                # wait for element to appear
agent-browser wait 2000               # wait milliseconds
agent-browser wait --text "Success"   # wait for text on page
agent-browser wait --url "**/dash"    # wait for URL pattern
agent-browser wait --load networkidle # wait for network idle
agent-browser wait --fn "window.ready" # wait for JS condition

Mouse (low-level)

agent-browser mouse move 100 200     # move cursor
agent-browser mouse down left        # press button
agent-browser mouse up left          # release button
agent-browser mouse wheel 100        # scroll wheel

Browser settings

agent-browser set viewport 1920 1080     # viewport size
agent-browser set device "iPhone 14"     # device emulation
agent-browser set geo 37.77 -122.42      # geolocation
agent-browser set offline on             # offline mode
agent-browser set headers '{"X-Key":"v"}'# extra HTTP headers
agent-browser set credentials user pass  # HTTP basic auth
agent-browser set media dark             # color scheme

Cookies and storage

agent-browser cookies                    # list cookies
agent-browser cookies set name value     # set cookie
agent-browser cookies clear              # clear cookies
agent-browser storage local              # list localStorage
agent-browser storage local key          # get key
agent-browser storage local set k v      # set key
agent-browser storage local clear        # clear all

Network interception

agent-browser network route <url>              # intercept requests
agent-browser network route <url> --abort      # block requests
agent-browser network route <url> --body '{}'  # mock response
agent-browser network unroute [url]            # remove route
agent-browser network requests                 # list tracked requests
agent-browser network requests --filter api    # filter by pattern

Tabs, frames, dialogs

agent-browser tab                    # list tabs
agent-browser tab new [url]          # open new tab
agent-browser tab 2                  # switch to tab
agent-browser tab close              # close tab
agent-browser window new             # new window
agent-browser frame "#iframe"        # switch to iframe
agent-browser frame main             # back to main frame
agent-browser dialog accept [text]   # accept alert/confirm/prompt
agent-browser dialog dismiss         # dismiss dialog

JavaScript

agent-browser eval "document.title"  # run arbitrary JS

Debugging

agent-browser open <url> --headed    # show visible browser window
agent-browser console                # view console messages
agent-browser console --clear        # clear console log
agent-browser errors                 # view page errors
agent-browser errors --clear         # clear error log
agent-browser highlight @e1          # visually highlight element
agent-browser trace start            # start trace recording
agent-browser trace stop trace.zip   # stop and save trace
agent-browser --cdp 9222 snapshot    # connect via CDP

Sessions (parallel browsers)

agent-browser --session test1 open site-a.com
agent-browser --session test2 open site-b.com
agent-browser session list

JSON output

Add --json to any command for machine-readable output:

agent-browser snapshot -i --json
agent-browser get text @e1 --json