@browser tool drives a real local Chrome/Chromium browser so the agent can see and interact with web pages the way a person would: open a URL, read the rendered page as text, click and type into elements, run JavaScript, capture screenshots, and inspect the page’s console and network activity.
It is the verification loop for web work — the agent builds or changes a frontend, then actually looks at it and debugs it from what the page logged and requested, instead of guessing from source.
@browser speaks the Chrome DevTools Protocol (CDP) directly over the websocket client ChatCLI already ships — zero new dependency, no driver, no downloaded runtime, no API key. It only needs a locally installed Chromium-family browser (Google Chrome, Chromium, Brave or Edge).How it works
- Lazy launch — the first
openstarts one browser; every later command reuses that single stateful session. - CDP over websocket — navigation, DOM reads, screenshots and event capture all flow over the DevTools websocket. No Selenium/Playwright, no external binary.
- Snapshot as text — the page is rendered to model-friendly text with every interactive element stamped and numbered so the agent can address them precisely.
- Continuous capture — console messages (errors included) and network responses are captured into bounded rings, so you can ask “what did the page log?” after the fact.
- Dies with the session — a headless browser never outlives ChatCLI; it is closed on CLI shutdown (or explicitly with
close).
Subcommands
Invoke with a JSON envelope{cmd, args} or the flat argv form. The model calls @browser automatically in /agent and /coder when it needs to look at a page.
Refs vs. CSS selectors
Everysnapshot stamps each interactive element with a data-chatcli-ref attribute and returns a numbered listing. click and type accept either that [n] ref number or a raw CSS selector:
Refs are stable until the next navigation. After you
open a new URL or a click triggers navigation, take a fresh snapshot before addressing elements by [n] again.A worked example
Build a page in/coder, then verify it end to end:
Environment variables
Security
Observation commands are read-only and skip the confirmation prompt — the agent can look freely:open, snapshot, screenshot, console, network, scroll, back, status, close.
Commands that act on a page — click, type and eval — can trigger real actions on remote sites, so they go through the standard security gate like any other mutating tool. See Coder Mode Security.
Notes
- One session per process, launched lazily on the first
openand reused across every call. - Console and network are captured continuously into bounded rings —
console/networkread the recent history, they don’t need to be “armed” first. screenshotwrites a PNG (default under the temp dir, or--file path). Pair it with@viewso the model can look at the screenshot it just took.- The browser is always closed on ChatCLI shutdown; a stray headless Chrome never survives the session.
Next steps
Image Input (@view)
Attach a screenshot
@browser captured so the model can see it with its own eyes.Plugin @coder
Read, write, patch and run — pair it with
@browser to build then verify.Agentic Plugins
The full builtin tool catalog and how the agent uses them.
Web Tools
@webfetch, @websearch and the shared hardened HTTP client.