/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.

After the first look, ask for **only what changed**:

agentglass-browser observe --delta            # {delta:true, added, removed, changed, same, console, network}
agentglass-browser click e12 --observe        # `after` is a delta too

`added` are whole nodes, `removed` are ids gone from the page, `unlisted` are ids still there but past the tree's cap, `changed` is `{e, field: new value}` (null = the field went away), `same` is how many did not move. New console and network rows only. `form`, `storage` and `viewport` appear only when they changed — **absent means unchanged**. Positions (`at`) are not diffed. After a navigation, with no earlier look, or after a look you only saw part of (`--max-tokens`, `--summary`), you get the full answer with `delta:false` and a `reason`. Plain `observe` is always the full page.

A page that is mostly below the fold or a menu you already know the id of does not need the whole tree:

agentglass-browser observe --viewport         # only what is on screen; `outOfView` counts the rest
agentglass-browser observe --root e12         # only the subtree of e12 (refused if e12 is gone)

Both are looks at a part: they are not a baseline, so they neither replace nor break the one `--delta` is measured against, and they cannot be combined with it. Unnamed layout wrappers (`role` presentation/none/generic with no name, id or test id) are left out of every tree, counted in `wrappers`, and an empty `name` is not written.

The baseline (and `checkup`'s "since your last checkup") is kept per `--as` name; callers without one share a single baseline, so pass `--as` to get your own.

`click` and `press` wait for what they caused (the navigation, or a quiet page with no request in flight, capped at 1 s) and answer with an `effect`: `navigated`, `newDocument`, `newErrors`, `failedRequests`, `dialog`, `settledBy`. Often that is all you need to know — no look at all.

Did it break? One call

The edit → reload → "is it broken?" loop is one verb:

agentglass-browser checkup http://localhost:5173/   # load it, wait for quiet, report
agentglass-browser checkup --reload                 # after your edit
agentglass-browser checkup                          # no navigation: since your last checkup

The first field is the verdict, `ok` or `N problems`. Problems are uncaught exceptions and console errors — **including the ones thrown while the page loaded**, which `console` and `observe` cannot see — failed requests (4xx/5xx, CORS, blocked) and visible error text (`role=alert`, so an alert toast counts). Chromium's `issues`, `perf` (LCP, CLS) and `a11y` (unlabelled controls, with ids) come along as advice and do not count. A screenshot path only when something failed (`--no-shot` to skip; `shot: "unavailable: …"` when there is no frame to take).

Then the whole interaction in ONE call

agentglass-browser do "click #save" "wait #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.

Every round you spend re-reads everything above it, so the count of calls is the cost. Three rules:

1. **Act, wait for the end state and look, in ONE call.** A form is one `fill --field e3=... --field e4=... --submit --observe`; a click that should lead somewhere is `do "click e9" "wait #done" --observe`. Do not split an action from the look that checks it. 2. **Trust the receipt.** `click` and `press` already say whether the page navigated, errored, opened a dialog or opened a tab (`effect.popups`: `[{page, url}]`, so the next call is `--page <page>`), and `--observe` already shows the page after. `fill` names any field the page changed from what you typed (`changedByPage`); no entry means every value took. Do not observe again to confirm what the answer just told you; look again only when it says something you did not expect. An act waits up to 3 s for its selector to appear and for a passing overlay to clear, so do not `wait` before a click on something that is about to render. An id the page re-rendered is refused with the id that replaced it (`... is now e43`): repeat the call with that one. 3. **Stop when the result is on the page.** The task is done the moment the page shows it (a confirmation, the new URL, the sa