/browser-use

name: browser-use
description: Drive agentglass's built-in browser — the one already signed in to the sites this project uses. Use when a task needs a page behind a login (a dashboard, a ticket, a staging app), when a URL fetched with curl comes back signed out or JavaScript-rendered, or when the user asks you to look at, click through, or screenshot something in a browser. It is a full browser for agents: DevTools, fake network responses, isolated profiles, a virtual clock.

Using the built-in browser

`curl` gets you the signed-out version of everything that matters, because the session lives in a browser. agentglass has one, already signed in to whatever the person using it is signed in to. `agentglass-browser` drives it, and it is built for you rather than lent to you: the whole DevTools protocol is here, so is running JavaScript, so is faking a broken API.

Start here, in this order

agentglass-browser health                     # is anything listening; always answers
agentglass-browser open https://example.com/app
agentglass-browser observe --shot             # EVERYTHING at once

`observe` is the verb to reach for first. One answer with the url and title, whether the view is **visible and focused**, the console and the network since last time, a tree of the interactive page addressed by role and accessible name, the current value of every input, and optionally the picture. Polling six verbs in turn is where the time goes.

Then the whole interaction in ONE call

agentglass-browser do "click #save" "waitfor #done" --observe

Starting this process costs ~69 ms before it says a word, so six separate verbs spend most of a second on startup alone. `do` spends it once. Measured: **618 ms → 94 ms** for six verbs. Steps stop at the first failure, which comes back with its own console errors and failed requests.

Wait for something instead of polling for it

agentglass-browser events --wait 30           # answers the MOMENT something happens

The cost of polling is not the clock, it is the twenty answers sitting in your context for the rest of the session. `events` waits on the server and answers once. "Nothing happened in thirty seconds" is an answer, not a failure.

The verbs, by what you reach for them for

look        observe · read · text · html · region · shot · frames · console · network
page        resize · zoom (the one Ctrl+/Ctrl- move) · emulate · throttle
act         click · type · select · check · fill · hover · dblclick · rightclick
            focus · blur · press · scroll · drag · upload
wait        wait · waitfor (--until network-idle | no-timers) · events
navigate    open · back · forward · reload
tabs        tabs · tab · newtab · closetab · profiles
containers  whoami · profiles (--make/--drop) · newtab --profile · lanes
identity    cookies · storage · permission · permissions · clipboard
run code    eval · eval --file · addInitScript · expose · exposed
inspect     cdp · debug · listeners · coverage · trace
devtools    inspect open|close · inspect panel <id> · inspect zoom <n> · inspect shot
network     fake · intercept · throttle · headers · har
pretend     emulate · resize · clock · settings
evidence    shot · shot --with-inspector · record · pdf · save · download · audit --script
batch       do (and `lanes` for several pages at once)

The things worth knowing before you start

**Stable ids beat invented selectors.** Every node in an `observe` comes with an id like `e17`, stamped on the element so it survives a re-render. Every verb that takes a selector takes one of those instead. Do not go inventing CSS.

**A failure explains itself.** It comes back with the console errors and failed requests from just before it, and a screenshot. `selector matched 3 elements` names them with position and text. You do not need a second call to find out what went wrong.

**JavaScript is yours.** `eval` reads the app's own runtime — a store, a component's state, `document.visibilityState`. `eval --file` for anything a shell would mangle. `addInitScript` runs BEFORE the page's own scripts, on every navigation, which is the one thing `eval` cannot do.

**DevTools, whole.** `cdp <Domain.method>` relays the entire protocol — breakpoints, heap snapshots, the accessibility tree. On top of it: `debug` (a DOM breakpoint answers "who deleted this row", and `debug where` gives you the stack AND the locals in one call), `listeners`, `coverage` ("is my change even being loaded").

**Break the network on purpose.** `fake` forces a 404, a 500 or a hang on a URL pattern; `intercept` pauses a request at the network level, which catches what the page did not ask for through fetch; `throttle` makes the machine slow, and offline is a *different* failure from slow. That is how you reproduce "the board freezes when the API is down" against the real app instead of in a unit test.

You already have an identity — you do not have to remember to ask

Several agents drive this browser at once, so every one of them works in a container of its own: its own cookies, its own storage, its own tabs. The CLI derives a name from your session, mints the container on first use, and sends every later verb to the tab it opened for you.

agentglass-browser open https://example.com/app    # your own container, your own tab
agentglass-browser read                            # goes to the tab that open made

**Open a tab before you act.** Isolation is the tab your identity is holding, so a verb from an identity that has none has nowhere of its own to go. It is refused, by name, rather than sent to whichever tab is in front — that fall-back is how an agent that had declared its identity on every single call still drove another agent's page seven times, with `ok: true` each time and no signal on either side. Your identity loses its tab when the tab is closed, when an `open` failed, and when the app restarts, so the refusal is a thing you will meet