Control Chrome

Control Chrome

The browser_* tools drive the user's own Chrome (their tabs, cookies, logins and extensions) through the byob extension. Don't substitute curl, Playwright or a fresh browser when the task depends on that session.

Core loop

1. Look: browser_snapshot → an outline of the page where every control has a ref: - button "Save" [ref=e7]. Use interactive:true for a short controls-only view; add diff:true later to see only what changed.
2. Act by ref: browser_click {ref:"e7"}, browser_type {ref:"e3", text:"…"}, browser_select, browser_press_key, browser_hover. Actions auto-wait until the element is visible, enabled and not covered, and report what they caused (→ navigated to …, → opened new tab …, → confirm dialog is open). Add snapshot:true to get the page diff back in the same call.
3. Repeat. Refs stay valid until the page navigates; a stale_ref error means: snapshot again and use the new ref.

Shortcuts:

• browser_find locates by role+name, text, label, placeholder or testId and can act immediately: {role:"button", name:"Sign in", action:"click"}, {label:"Email", action:"fill", value:"a@b.c"}.
• browser_batch runs many steps in one call — fill a whole form and submit: {steps:[{tool:"type",args:{ref:"e3",text:"…"}}, {tool:"click",args:{ref:"e9"}}]}. It stops at the first failure and says which step failed.

Tabs

• Calls without tabId go to the working tab: the tab this session last used or opened; initially the user's active tab.
• browser_navigate {url} opens a new background tab (grouped under "byob") and reuses it afterwards; it never navigates the user's own tab away. newTab:true forces another tab. browser_tabs lists / selects / closes tabs; select switches the working tab.
• When an action reports opened new tab N, pass tabId: N to work there.
• Close tabs you opened for scratch work when done; never close the user's tabs unless asked.

Reading vs. seeing

• Content: browser_read — markdown (main article), text (everything visible), links, tables, html. On long pages use outline:true first, then filter:"<phrase>" or scope with ref/selector.
• Visual layout, charts, canvas, images: browser_screenshot (returned to you as an image; annotate:true labels refs on it). Prefer snapshots for finding controls — they're cheaper and exact.
• Big outputs are cut to a budget and the full text is saved to a file whose path is printed; read that file only if you need the rest.

Waiting

Actions already wait for their target. Use browser_wait only for things that happen later: {text:"Order placed"}, {selector:".results", state:"visible"}, {url:"*/dashboard*"}, {load:"networkidle"}. Avoid fixed ms delays and avoid networkidle on pages with live connections (chat, dashboards).

Debugging pages

browser_console (buffered console + uncaught errors; pass since to get only new entries), browser_network (record → act → stop; or intercept to block/mock/modify), browser_inspect (element box/state/styles, or Web Vitals), browser_storage (cookies, local/sessionStorage), browser_emulate (device, dark mode, geolocation, timezone, offline), browser_evaluate (only when exposed and nothing else works).