# browser-link MCP server

> Connects AI agents to specific Chrome tabs to enable debugging, UI interaction, and automated testing within a developer workflow.

- Repository: https://github.com/jobshimo/browser-link
- Page: https://hostedmcp.org/servers/jobshimo/browser-link
- Transport: stdio
- Stars: 1
- License: MIT

## Install

### Claude Code

```sh
claude mcp add browser-link -- npx -y @jobshimo/browser-link
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "browser-link": {
      "command": "npx",
      "args": [
        "-y",
        "@jobshimo/browser-link"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "browser-link": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@jobshimo/browser-link"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"browser-link","type":"stdio","command":"npx","args":["-y","@jobshimo/browser-link"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "browser-link": {
      "command": "npx",
      "args": [
        "-y",
        "@jobshimo/browser-link"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add browser-link -- npx -y @jobshimo/browser-link
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.browser-link]
command = "npx"
args = ["-y", "@jobshimo/browser-link"]
```

### Gemini CLI

```sh
gemini mcp add -s user browser-link npx -- -y @jobshimo/browser-link
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "browser-link": {
      "command": "npx",
      "args": [
        "-y",
        "@jobshimo/browser-link"
      ]
    }
  }
}
```

## Tools (40)

- `browser.list_tabs`: List Chrome tabs currently reachable by browser-link. A tab is normally connected only after the user clicks Connect in the extension popup. Each entry includes tab_id, url, title, claimed_by (null when free, or { agent_id, pid, binary, label?, claimed_at, last_activity_at } when another agent owns it), claimed_by_me (true when YOU hold the claim), an optional map field ({ app_key, entries, flows }) present ONLY when the persistent UI map already has data for that tab's origin, and — only when the user has enabled AND granted cdp-direct mode (off by default, see the cdp-direct docs) — additional tab_id values starting with cdp: carrying transport: 'cdp', reached without the extension. The first content block is always the bare JSON array ([] when empty). When NO tab is reachable a SECOND text block starting with hint: follows it; the hint says whether nothing was ever connected to this bridge, tabs were connected and dropped (how many, which ids/origins, how long ago), the bridge restarted recently, or browser.reset wiped it — and whether to wait for the extension's auto-reconnect or ask the user to press Connect. Also, per tab and only when known (never on a cdp: tab): `build` and `view_sig` (short hashes of the page's script/stylesheet URLs and of its headings and landmarks), and `knowledge`: the start pack the map holds for this app and path (≤ 2 KB; `pitfalls`, `mechanisms`, `readers`, `flows`, `selectors`, `warnings`, each item with `confidence` fresh | unverified | failing and its raw `evidence`). Read `knowledge` before acting; failing targets appear only under `warnings`.
- `browser.claim_tab`: Claim a tab so other agents stop touching it. Returns ok:true with your claim, or ok:false reason:"conflict" with the existing claim. Pass an optional label (eg "claude-code") that other agents will see in browser.list_tabs. Pass ttl_minutes (default 10, max 60) — the claim auto-expires after that many minutes of inactivity. A running browser.flow you launched holds the claim: it cannot expire while the flow runs, and the clock restarts from the last step of the flow when it ends (a long single call such as wait_for holds nothing). Action tools (click/type/navigate/evaluate) auto-claim free tabs, so an explicit claim_tab is only needed when you want to reserve a tab before you start, or to refresh the label/TTL.
- `browser.release_tab`: Release a tab claim you hold. Returns ok:true on success, ok:false reason:"not-owner" if another agent holds it, or ok:false reason:"not-claimed" if the tab is free. Releasing is also automatic on agent disconnect and when the inactivity TTL elapses, so calling this explicitly is only needed for early hand-off.
- `browser.my_tabs`: List the tabs YOU currently hold a claim on. Returns { claims: [{ tab_id, claimed_at, last_activity_at, ttl_ms, label? }] } sorted by claimed_at. Use this to answer the user when they ask which tabs you are working on.
- `browser.manual`: The browser-link manual on demand; needs no tab. No arguments: the index (server version, the instructions-block status per client, one line per tool, the topic list). { tool: "browser.click" }: that tool's full doc (purpose, when to use, gotchas, example) plus one line per parameter. { topic: "downloads" }: one hand-written topic. Pass at most one of tool or topic; an unknown name fails listing the valid ones.
- `browser.ping`: Verify the bridge to a tab. Returns its current title and url.
- `browser.navigate`: Navigate the connected tab to a URL. By default waits for the load event. The result carries `knowledge` (the start pack of the app and path it landed on, same shape as in browser.list_tabs) when the map has evidence for it.
- `browser.snapshot`: Snapshot of the tab: title, url, visible text (truncated) and a list of interactive elements (buttons, links, inputs, selects, textareas) with a CSS selector and labels. Use this to understand page state before clicking or typing. Elements whose computed `pointer-events` is `none` (invisible accessibility layers that can never receive a real click) are excluded from the interactive list, though their text still contributes to headings/text; a descendant that re-enables itself with `pointer-events:auto` is still listed. The scan pierces OPEN Shadow DOM roots and same-origin iframes (nested arbitrarily) — a web component internal or an in-page iframe shows up without extra steps. An entry for an element living inside an iframe carries an extra `frame` field (the CSS selector of the innermost hosting iframe) so you know it is framed; entries in the top document or in Shadow DOM omit it. An entry whose selector could not be made unique across all roots (structurally-identical component twins) carries `ambiguous: true` — that selector resolves first-match-wins, so use it immediately and do NOT store it in the persistent map. Optional filters keep the response small: `within_selector` restricts the scan to a subtree (also deep-search-aware — it can target a subtree inside a shadow root or iframe); `only_interactive` skips headings and the text dump; `exclude` drops landmarks like nav/footer; `max_interactive` overrides the default cap of 120. A result that left something out says so in `truncated` (absent when nothing was cut): `{ interactive?, headings?, text?, not_compared?, next_offset?, hint }` counts what was left out after the returned window of each part (entries; characters for text; the cuts are 120 or `max_interactive` entries, 30 headings, 4000 characters), and passing `next_offset` back as `offset` returns the rest, nothing twice; or narrow the scope instead. When an `offset` leaves every requested part empty, the result says so in `offset_past_end` (`{ <part>: { offset, total } }`): nothing is left there, which is not the same as the page having nothing. Paging with `next_offset` never carries it. The per-entry serializer omits empty-string fields, so the same call returns a leaner payload than before — no behavior change for clients that read by key. When the page observer is running in the tab, each interactive entry also carries `ref` (right after `selector`): a per-document element handle `<doc_tag>:e<N>` (like `k3x9ab:e12`; `doc_tag` is the first 6 characters of `doc_id`) issued by the page observer, stable for the same element across snapshot/find/state calls and valid only for the document that issued it; unlike `ambiguous` (a selector-level warning), a `ref` names exactly one element of the current document. The result then also carries `doc_id` (the document instance that issued the refs; it changes on every new document) and `snapshot_id` (`<doc_id>:s<N>`, one per snapshot call in that document). All three are additive and ignorable, and are absent when the observer is not in the page. Pass `since: <snapshot_id>` to get a diff instead of the whole page: `{ title, url, doc_id, snapshot_id, since, added, removed, changed, overflow? }`, where `added` and `changed` are full entries (added first) and `removed` is `{ ref, tag, text? }`. `max_interactive` applies after diffing to `added` + `changed` and `overflow` (count dropped) appears only when above 0, with `truncated` (`offset.interactive` continues the same diff); `truncated.not_compared` counts entries past the first 500 of either snapshot, which a diff never compares; `headings` and `text` appear in a diff only when `only_interactive` is false and they changed. When no diff can be made the result is the full snapshot plus `since` and `since_status`: `doc-changed` (the `since` prefix is not the current `doc_id`, or it has no `:`), `evicted` (same document, but not among the last 4 snapshots or never issued) or `observer-unavailable`. An invalid `since` (not a string, or over 64 characters) is dropped and a plain full snapshot is returned; a `within_selector` miss ignores `since`.
- `browser.find`: Locate ONE interactive element by its visible text and return a stable selector plus viewport coordinates. The match is case-insensitive substring by default (set `exact:true` for full-string equality). Pass `role` to narrow to a specific ARIA role (`button`, `link`, `textbox`, `checkbox`, `tab`, `menuitem`) — without it the scan covers buttons, links, inputs, role-bearing elements, contenteditable nodes, and `[onclick]` divs (the "peruvian markup" case). Elements whose computed `pointer-events` is `none` (invisible accessibility layers that can never receive a real click) are never returned as matches, though they can still surface as `near_misses` hints. The scan pierces OPEN Shadow DOM roots and same-origin iframes, same as browser.snapshot. Returns `{ matched: true, selector, ref?, coords:{x,y}, tag, text, frame?, ambiguous?, doc_id? }` on a unique hit, `{ matched: false, reason: "not-found", error?, near_misses?, doc_id? }` when nothing matches, or `{ matched: false, reason: "multiple-matches", candidates: [{selector, ref?, text, tag}], truncated?, doc_id? }` (up to 5) when several elements match — pick one and try again with `exact:true` or a longer text. When more than 5 match, `truncated: { candidates, next_offset, hint }` counts the matches left out; pass `next_offset` back as `offset` (text mode) to list the rest, nothing twice; when an `offset` leaves the candidates empty, the result says so in `offset_past_end: { candidates: { offset, total } }`. On `not-found`, `near_misses` carries up to 3 VISIBLE candidates (`{text, selector, ref?, role?}`) ranked by substring containment then token overlap — omitted entirely when nothing plausible exists. When `role` excluded matches that the text DID find elsewhere, `error` names it explicitly (e.g. `text matched 2 elements but none with role "button" — closest: <div onclick> "GIF picker"`). `frame`, when present, is the CSS selector of the innermost iframe hosting the match. `ambiguous: true`, when present, means the selector could not be made unique across all roots (structurally-identical twins) and resolves first-match-wins — use it immediately, never cache it. `coords` are already mapped to TOP-LEVEL viewport coordinates even when the match lives inside an iframe. The returned `selector` uses the same heuristic as `browser.snapshot` (id → data-testid → aria-label → name → positional fallback, each verified unique across the full deep search scope), so a subsequent `browser.click` / `browser.type` works without re-querying. `ref` and `doc_id` are additive, ignorable fields present only when the page observer is running in the tab: `ref` is the same per-document element handle `<doc_tag>:e<N>` that browser.snapshot reports for that element, valid only for the document that issued it. Give exactly one of `text`, `ref` or `key`; `role` and `exact` apply to `text` only, and any other combination is rejected. Pass `ref` alone to describe that element directly (single-match shape plus `reresolved: true` when its node was replaced by a re-render and re-found by its semantic key); a ref that no longer resolves fails with `ref-stale: <ref> not found in document <doc_id>: the element is gone, take a new snapshot`. A ref is rebound only to an element that first appeared after the original was gone (a re-render, `reresolved: true`); a look-alike that already existed, such as the other row when one of two identical rows is deleted, gives `ref-stale`; the same node detached and re-attached resolves as itself. With the observer running, a single match also carries `semantic_key` (`{ role, name, path }`: role, accessible name and the ancestor tag path with sibling indices); pass it back as `key` alone to find that element again by role and name (with `path`, exactly one candidate with the same tag path must exist, else `not-found` with `key: <N> candidates share role, name and tag path`; several role + name candidates without `path` give `not-found` with `key: <N> candidates share role and name; pass path to disambiguate`). When the target (a `selector`, or a find `key`) has evidence on this app, the result carries `known: { confidence, ok_n, fail_n, last_reason, alternative? }`; `alternative` is the best fresh target for the same action on this path.
- `browser.state`: Compact orientation snapshot — cheaper than a full browser.snapshot when the agent only needs to know where it is. Returns { url, title, viewport:{w,h}, focused?, dialogs?, scroll? }. `focused` is the innermost actually-focused element (descending through open Shadow DOM roots and same-origin iframes past `document.activeElement`, which by itself only reports a shadow host or an <iframe> element) as `{ selector, ref?, tag, ambiguous? }`. `dialogs` lists visible `[role=dialog]`, `[role=alertdialog]` and open `<dialog>` elements as `{ selector, role, label? }`, `label` best-effort from aria-label / aria-labelledby / the first heading inside. `scroll` is `{x,y}` and is omitted when the page is at its default (0,0) position. Every optional field is omitted when there is nothing to report. When the page observer is running in the tab, `focused.ref` is the same per-document element handle `<doc_tag>:e<N>` that browser.snapshot reports for that element and the result carries `doc_id`; both are additive, ignorable, valid only for that `doc_id`, and absent when the observer is not in the page.
- `browser.canvas_screenshot`: Capture a `<canvas>` element from the connected tab as a PNG/JPEG and return it base64-encoded. Designed for pages whose visible UI is rendered to a canvas — Qt for WebAssembly (Venus OS, Felgo apps), WebGL games, custom rendering, etc. — where `browser.snapshot` and `browser.find` return nothing useful because there is no DOM inside the canvas to inspect. The finder traverses nested Shadow DOM roots, so a canvas hidden behind one or more `attachShadow` boundaries (very common in Qt-WASM apps) is still reachable without passing an explicit selector. Pass `selector` only when several canvases exist and you want a specific one; otherwise the first visible canvas wins. `region` crops to a sub-rect in canvas pixels — useful when you want to focus the LLM on one area and save tokens. Returns `{ ok: true, canvas_size, canvas_pixels, region, format, image_b64, taken_at_ms }` on success; `{ ok: false, reason: "no-canvas" }` when no canvas is found.
- `browser.screenshot`: Take a real screenshot of a tab and return it as an MCP image (plus a JSON text block with the metadata). `mode: "viewport"` (default) captures what is visible now; `mode: "full_page"` captures the WHOLE document from top to bottom in one image, without scrolling or stitching; `mode: "element"` captures one element (pass `selector`; the same deep Shadow DOM / same-origin iframe search as click/find, scrolled into view first). Unlike `browser.canvas_screenshot` this renders the page as the browser paints it, so it works on any page, not just a `<canvas>`. Returns `{ ok, mode, format, width, height, scale, bytes, truncated? , size_reduced? }` plus the image.
- `browser.console`: Return recent console messages (log, info, warn, error) from the connected tab since it was attached. Rolling buffer (last 200).
- `browser.network`: Return recent network requests from the connected tab (rolling buffer, last 200). Includes request_id, method, url, status, mime, size, timing. Use browser.network_body to fetch the body of a specific request.
- `browser.network_body`: Fetch the response body of a single network request by request_id (from browser.network).
- `browser.wait_for`: Wait for a condition to become true on the page before continuing. Pick exactly ONE target: (a) `selector` — or `ref`, an element ref from browser.snapshot / find / state, where a ref that no longer resolves counts as a missing element for `hidden` and `detached`; for `visible` and `attached` a ref of another document fails at once with `ref-stale`, and a ref whose node is only gone keeps polling and times out with `reason: "timeout"` plus `ref_gone` — plus an optional `condition` of visible|hidden|attached|detached (default visible), (b) `expression` — any JS that should become truthy, or (c) `network_url` — a substring that a completed network request URL must contain. Returns { matched, elapsed_ms, checks, reason? }. `matched: false` is NOT an error — the caller decides whether to proceed or branch. Polls every `poll_interval_ms` (default 100, range 50–1000) until `timeout_ms` (default 5000, capped at 30000). This is a read tool and does not require a claim — multiple agents can wait on the same tab in parallel.
- `browser.wait_for_tab`: Wait for a new tab opened by a previous action on a connected tab. The extension auto-emits `tab-created` events to the bridge stream whenever a tab connected to browser-link spawns a new one (via window.open, target=_blank, etc.). This tool polls that stream until it sees a matching `tab-created` event whose `opened_from` equals the `opened_from` you passed (the tab_id of the action originator). On match, browser-link automatically claims the new tab under YOUR agent_id — the waiting call IS the explicit intent — and returns its tab_id ready to use. Optional `url_substring` narrows the match (case-insensitive). Returns `{ matched, tab_id?, url?, elapsed_ms, checks, claimed?, claim_conflict?, reason? }`. `matched: false` is NOT an error — the action may have failed to open a tab, or the tab opened too slowly.
- `browser.dialog_respond`: Respond to a pending native JavaScript dialog (alert / confirm / prompt / beforeunload) on a connected tab. browser-link does NOT auto-dismiss dialogs — when a dialog opens, the page JS thread freezes and the bridge emits a `dialog-opening` event in browser.events with `{ tab_id, type, message, default_prompt }`. The agent reads that, decides what to answer based on the page flow, and calls this tool. `accept:true` is the "OK" path (submit for prompt, continue for beforeunload); `accept:false` is "Cancel". `prompt_text` is only used for `prompt` type — ignored otherwise. After the response, the page JS thread resumes and a `dialog-closed` event lands on the stream.
- `browser.set_permission`: Grant or deny a browser permission for a given origin BEFORE the page asks for it. Backed by `chrome.contentSettings` (the surface exposed to MV3 extensions — `Browser.setPermission` would need a browser-level CDP target that `chrome.debugger` does not give us). Subsequent page calls to navigator.geolocation / Notification.requestPermission / navigator.mediaDevices.getUserMedia / etc. then return the chosen state without surfacing a native prompt. Scope is per-ORIGIN (URL pattern `<origin>/*`), persistent until you call again or the user clears settings.
- `browser.download`: Download a file to disk WITHOUT Chrome's native "Save as" dialog — a dialog nothing in CDP or the page can press, which strands an agent that just clicks a download button. Two modes, pass exactly one: `selector` clicks the element and captures the download the clicked tab starts (Chrome's download is held so it cannot prompt, the file is re-fetched, and Chrome's copy is cancelled and erased only after the file is written; if the fetch or the write fails it is released untouched); `url` fetches that URL directly. Either way the bytes are fetched IN THE PAGE with the page's own cookies/credentials and written by the server into the human-configured downloads directory (`browser-link config get downloads.dir`, default `<data dir>/downloads`). Returns `{ ok, state: "complete"|"interrupted"|"timeout", path, filename, bytes, mime, url, error?, chrome_download? }`; selector mode adds `chrome_download`: "removed" (Chrome's download cancelled and erased after the write), "cancelled" (the erase failed), "left_in_chrome" (untouched: Chrome carries on with its own copy and may ask the user where to save it) or "unknown" (not known: the settle answer was lost, or the extension no longer held the download; a saved file then carries chrome_download_note, there may be a second copy in Chrome) — the error of a failed save ends with what happened to the Chrome copy; a timeout or failure still reports what it knows (url, mime, bytes received so far), never nothing.
- `browser.click`: Click an element by CSS selector in the connected tab. The selector usually comes from browser.snapshot or browser.find. The lookup pierces open Shadow DOM roots and same-origin iframes (nested arbitrarily), so a selector for a web-component internal or an in-page iframe works without extra steps. Before dispatching the click, the element is hit-tested at its own click point (starting from its own shadow root / iframe document) — if a different element covers that point, the call returns ok:false with a description of the blocker instead of clicking the wrong thing blindly. Pass `force:true` to skip that guard. A target whose computed `pointer-events` is `none` (an invisible accessibility layer over the real control) is NOT treated as covered: the click proceeds at the same point — that is what a real user click does — and the result carries `hit_element` naming the element that actually receives it. `hit_element` (same compact descriptor format as occlusion blockers) appears in an ok:true result only when the click proceeds onto a different element by design — the pointer-events:none case above (including an icon inside its button), or a `force:true` click landing on whatever covers the point — and is omitted when the click hits the resolved element itself or one of its descendants. When the hit-test lands on an ANCESTOR of a target that takes clicks (the target is clipped by an overflow container, zero-size, or covered by its own parent), the call fails with `Click would land on <hit_element>, not on <target>: …` instead of clicking the ancestor. A target with no visible box (not rendered: display:none, display:contents, content of a closed <details>, an <option> of a <select>; or visibility:hidden) is never clicked by pointer and never at (0,0): without `force` the call fails with `Element <target> has no visible box …`; with `force:true` the element's own click() is called, with no pointer and no coordinates, and the result carries `programmatic_click` saying so — such a click sends no hover, pointer, mousedown or mouseup events and moves focus only if the element takes focus itself. That click is refused, with nothing clicked, on a disabled control (the element or a disabling ancestor fieldset) and on an `<option>` or `<optgroup>`: click() does nothing there, and an option is never selected by clicking it, the select's value must be set instead. Optionally waits for the page to settle after the click — see `settle_ms`. Give exactly one of `selector` or `ref` (an element ref from browser.snapshot / find / state); a ref whose node was replaced by a re-render is re-found by its semantic key and the result carries `reresolved: true`, and a ref that no longer resolves fails with `ref-stale: <ref> not found in document <doc_id>: the element is gone, take a new snapshot`. A ref is rebound only to an element that first appeared after the original was gone (a re-render, `reresolved: true`); a look-alike that already existed, such as the other row when one of two identical rows is deleted, gives `ref-stale`; the same node detached and re-attached resolves as itself. When the target (a `selector`, or a find `key`) has evidence on this app, the result carries `known: { confidence, ok_n, fail_n, last_reason, alternative? }`; `alternative` is the best fresh target for the same action on this path.
- `browser.type`: Focus an input by CSS selector and type text into it. If clear=true, clears the current value first. The lookup pierces open Shadow DOM roots and same-origin iframes, same as browser.click. Optionally waits for the page to settle after typing — see `settle_ms`. Give exactly one of `selector` or `ref` (an element ref from browser.snapshot / find / state), with the same `reresolved` / `ref-stale` behaviour as browser.click. When the target (a `selector`, or a find `key`) has evidence on this app, the result carries `known: { confidence, ok_n, fail_n, last_reason, alternative? }`; `alternative` is the best fresh target for the same action on this path.
- `browser.press`: Press a single key, optionally with modifiers, using a TRUSTED CDP `Input.dispatchKeyEvent` sequence (`isTrusted: true`) — not a synthetic `KeyboardEvent` dispatched via `browser.evaluate`, which many rich text editors, autocompletes, and non-DOM runtimes (Qt-WASM, WebGL — see browser.canvas_screenshot) silently ignore. `key` accepts a human name (`Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight`, `Home`, `End`, `PageUp`, `PageDown`, `Space`), case-insensitive, or a single printable character, case-sensitive (`"a"` vs `"A"`, `"@"`). `modifiers` combines with the key for shortcuts (`Ctrl+A` = `{ key: "a", modifiers: ["Control"] }`). Pass `selector` to focus an element first (same deep Shadow DOM / iframe search as click/type/find); omit it to send the key to whatever currently has focus. `ref` (an element ref from browser.snapshot / find / state) focuses that element instead of `selector`, with the same `reresolved` / `ref-stale` behaviour as browser.click. Optionally waits for the page to settle after the key press — see `settle_ms`. When the target (a `selector`, or a find `key`) has evidence on this app, the result carries `known: { confidence, ok_n, fail_n, last_reason, alternative? }`; `alternative` is the best fresh target for the same action on this path.
- `browser.drag`: Drag an element from a source to a destination. Provide each end as either a CSS selector OR a viewport coordinate pair (x,y). A selector endpoint is resolved through the same deep search snapshot/find/click/type use — it reaches into open Shadow DOM roots and same-origin iframes, with coordinates mapped to the top-level viewport. The drag is interpolated over duration_ms (default 1500) so you can watch the cursor traverse the path — this also helps activation-by-distance constraints in pointer-based libraries. Auto-detects HTML5 native drag (element.draggable, <img>, <a href>) vs pointer-based drag (dnd-kit and similar). For HTML5 it uses Input.setInterceptDrags + Input.dragIntercepted + Input.dispatchDragEvent. For pointer-based it interpolates Input.dispatchMouseEvent only. setInterceptDrags is always cleared in finally. Both source and destination must be visible in the viewport simultaneously — drag does NOT scroll between them. Returns { from, to, duration_ms_actual, drag_mode: "html5"|"pointer", events_fired }.
- `browser.flow`: Run a declarative sequence of steps (find/click/type/press/wait_for/drag/sleep/repeat) in ONE round trip instead of one MCP call per step. Steps execute strictly in order and STOP at the first failure (fail-fast) — there is no branching. A `find` step's resolved selector becomes the IMPLICIT TARGET for the very next click/type/press step that omits its own `selector` (an explicit `selector` on that step always overrides it and leaves the implicit target untouched for a later step). `type` and `press` steps that end up with no selector at all — no explicit one, no implicit one — act on whatever currently has focus, same as standalone browser.press; only `click` requires a resolved target and fails the flow if none is available. A `drag` step runs a full drag-and-drop gesture with the SAME params as standalone browser.drag (each endpoint a CSS selector or a viewport x/y coordinate pair, plus duration_ms/hold options) — its endpoints are ALWAYS explicit: it neither consumes nor sets the implicit target, which survives a drag step untouched for a later click/type/press. Drag steps work on extension tabs only: on a cdp: tab_id the flow fails fast at the drag step with the same "not supported over cdp-direct" error standalone browser.drag returns there. `click`/`type`/`press` default `settle_ms` to 150 exactly like the standalone tools, unless a step overrides it. They also accept the standalone `expect` (`url_changed` / `selector_appears` / `selector_disappears` / `text_appears` / `timeout_ms`): settle proves QUIET, not EFFECT, so put `expect` on the step whose effect the next steps depend on, and a click that did nothing fails THAT step (`expectation not met: ... after Nms`, with the usual recovery_snapshot) instead of timing out several steps later. Example: `{ click: { selector: "a.next-lesson-link", expect: { url_changed: true } } }`. Example (GIF picker): `{ find: { text: "GIF", role: "button" } }, { click: {} }, { wait_for: { selector: "[data-testid=gif-search]", condition: "visible" } }, { type: { selector: "[data-testid=gif-search]", text: "shrek" } }, { press: { key: "Enter" } }` — 5 steps, 1 round trip. On success returns `{ ok: true, steps_completed, results }` where each entry is `{selector}` for a find step, `{ok, settle?, expect?}` for an action/wait_for step (`expect: { met: true, elapsed_ms }` appears only on a step that set `expect`), or `{ok, drag_mode}` for a drag step (`drag_mode: "html5"|"pointer"` — the same silently-failing-drop diagnostic standalone browser.drag returns) — a click step's entry additionally carries `hit_element` exactly like standalone browser.click: present only when the dispatched click landed on a different element than the resolved target, omitted when the click hit the target itself; and `programmatic_click` when a force click found no visible box and called the element's own click(). On failure returns `{ ok: false, failed_step, step_kind, error, steps_completed, recovery_snapshot }` — `error` is the same message the standalone tool would have returned for that failure, and `recovery_snapshot` is a focused `browser.snapshot({only_interactive:true, max_interactive:40})` of the page as it stands, so you see where the flow stopped without a follow-up call. Every response also carries `flow_id`, the opaque id of this run. A flow can additionally come back `{ ok: true, stopped_by: "cancelled", steps_completed, results }`: the HUMAN stopped it from the extension popup (or, on a cdp: tab, revoked the cdp-direct grant). That is a success carrying the partial work that really happened — do NOT relaunch it, and do NOT treat it as a transient failure to retry; report what completed and ask the user what they want instead. A flow that runs out of TIME comes back differently: `{ ok: true, stopped_by: "timeout", steps_completed, results }` (a `repeat` entry carries `iterations_completed`, `stopped_by: "timeout"` and, if the deadline landed mid-iteration, `partial_iteration`). The server computes the flow's worst-case budget (each click/type/press is charged its `settle_timeout_ms`, default 2000, NOT `settle_ms`; a repeat multiplies by `max_iterations` and adds `delay_ms`) and hands the runner a deadline slightly shorter than the bridge timeout, so it stops at the next step/iteration boundary and returns what it did instead of dying with nothing. Unlike a human stop, a timeout is NOT a decision: you MAY continue the remaining work, but do NOT relaunch steps that already completed if they are irreversible (clicks that delete/send/pay) — resume from `steps_completed` / `iterations_completed`, using a repeat's `while_found` where you can. If the runner is wedged inside one step and cannot answer at all, the server cancels it and recovers progress from the flow registry: `{ ok: true, stopped_by: "timeout", steps_completed, iterations_completed?, results: [], results_available: false, flow_id }` — the per-step results are lost in that case, only the counts survive, and `steps_completed` can be ONE LOWER than what really ran (the step in flight when the cancel landed is not counted), so before resuming verify the page state of the first step you would re-run instead of blindly repeating it. `settle_timeout_ms` (click/type/press, same meaning as on the standalone tools) is the knob that lowers or raises the settle cap a step may burn. `evaluate` and `navigate` are intentionally NOT flow steps in v1 — arbitrary JS inside a flow raises permission-model questions this tool does not solve yet, and a navigation mid-flow can tear down the very document later steps expect to act on; use standalone browser.navigate before a flow, or browser.evaluate after one.
- `browser.flow_status`: Progress, outcome and ACTION MANIFEST of one browser.flow run, by its flow_id. Returns { flow_id, tab_id, state, detached, started_at, ended_at?, steps, steps_completed, iterations_completed?, stopped_by?, error?, manifest? }. `state` is one of running | completed | cancelled | failed | expired | unknown. While a flow is RUNNING you get live progress (steps_completed, iterations_completed) but no manifest — the runner is still holding the results; once it ends, `manifest` is exactly the `results` array a foreground flow would have returned, which is how you answer "which N things did that actually do?" after a detached run. `cancelling:true` means a stop was requested and the runner has not reached its next check yet (up to one step). `unknown` is not an error: it means this bridge has no record of that id — a foreground flow that already returned, a detached flow evicted after 10 newer ones, or an id from before the extension service worker restarted. `manifest_truncated:true` means the manifest existed but is not retrievable (over the storage ceiling, or lost with a terminated service worker). The tab_id only routes the request: any connected tab can answer for any flow_id, so a finished flow whose own tab has since closed is still readable through another one.
- `browser.flow_cancel`: Stop a running browser.flow by its flow_id. Cancellation is cooperative and lands within ONE STEP: the runner declines to dispatch the next step rather than interrupting one in flight (an in-flight CDP command cannot be un-sent). Returns the same payload browser.flow_status returns, plus cancel_requested:true — so immediately after the call you will typically see state:"running" with cancelling:true, and a poll a moment later shows state:"cancelled". The flow keeps everything it already did: a cancelled flow is a SUCCESS carrying partial results, never a failure, and its manifest stays readable through browser.flow_status. Cancelling an unknown or already-finished flow_id is a clean no-op (state:"unknown" or the terminal state it already reached), never an error.
- `browser.evaluate`: Run a JavaScript expression in the page context and return its result. Use an IIFE with return if you need multi-step logic. The bridge waits up to `timeout_ms` (default 15000, capped at 60000) for the result — raise it for long-running in-page work instead of splitting one loop across several calls.
- `browser.events`: Return recent bridge lifecycle events: primary-elected (a new browser-link primary started), tab-registered / tab-disconnected (Chrome tabs joined/left), tab-renamed (the same Chrome tab got a new tab_id, usually after a primary swap), tab-claimed / tab-released / tab-claim-rejected (multi-agent tab ownership changes — see browser.claim_tab), dialog-opening / dialog-closed (a native alert/confirm/prompt/beforeunload started or finished blocking a tab — see browser.dialog_respond), tab-created (a new tab opened from an existing one, e.g. target="_blank" or window.open — see browser.wait_for_tab), flow-recorded (a demonstrated flow was saved to the persistent map — see browser.map.recall), flow-finished (a DETACHED browser.flow ended — one summary entry per flow with its outcome and counts, never one per iteration; read the action manifest itself with browser.flow_status). Call this when you get "Tab not connected: …" so you can pick up the new tab_id and resume work, to notice a newly-recorded flow without polling, or to notice that a detached flow you launched has ended. Returns { events, latest_id } — pass latest_id back as since_id next time to get only new entries.
- `browser.activity`: Read the persistent activity trail: every browser tool that any agent dispatched, oldest kept for 50k rows, stored on disk in the user's data dir and surviving both browser and server restarts. Each row carries when it ran, which agent ran it (self-declared claim label, e.g. "claude-code" / "opencode", plus pid), the tool, the tab and page URL, the CSS selector it targeted, the payload (typed text, evaluate expression, navigate URL), the outcome and the duration. DISTINCT from browser.events, which is a 200-entry in-memory ring of bridge LIFECYCLE events (tab connected, dialog opened) that dies with the process — this is what agents actually DID. Use it to review your own work before reporting it, to see what a different agent did to a tab you just claimed, or to reconstruct a run that went wrong. Returns { records, latest_id, total, agents } — pass latest_id back as since_id to page through new entries. Every record carries resultBytes (size of the serialised result). With `summary: true` it returns the friction report instead: { summary: { records, errors, by_flag, by_tool_errors, evaluate_calls, timeouts, top_failing_targets, sessions, bytes_total, bytes_by_tool, evaluate_share, list_tabs_calls, map_recall_calls, readers_run } }, narrowed by since_id, since and agent_id only (any other filter alongside summary: true is an error naming it). Reading the trail is itself recorded.
- `browser.reset`: Soft-reset the bridge state. Drops every connected tab session, releases every claim, and clears the in-memory event log — but does NOT kill the MCP server itself. The user has to re-press Connect in the extension popup for each tab they want back. Use this when the bridge state looks inconsistent (stale tab_ids that browser.events does not explain, tab.click that hangs, claims you cannot release through normal means) and you are sure a clean slate is the right move.
- `browser.wrap_up`: Close the loop before you answer the user after using the browser. Step 1, no arguments: what this session left to decide, per app touched (≤ 2 KB): { step: 1, apps: [{ origin, app_key, build, readers: [{ id, expression (first 160 chars), kind, flags, ok_n, fail_n, result_bytes_avg }], flows_run: [{ session_index, name, saved_name, steps, stopped_by, ok }], selectors, friction, pitfall_candidates: [{ id, sentence }], feedback_candidates }], omitted? }. Step 2, your decisions: { readers: { keep: [{ id, name, template? }], drop: [id] }, flows: { keep: [{ session_index, name }] }, pitfalls: { confirm: [id], drop: [id] }, feedback: [{ tool, observed, expected }] }, validated against the eight curation rules and applied in ONE transaction: { step: 2, applied: [{ item, action, name? }], rejected: [{ item, rule, reason }] }. Anything you do not decide stays pending and is offered again next time. While work is pending, every object result carries pending_wrap_up: n.
- `browser.read`: Run a KEPT JS reader of the tab's app by name (or id) instead of writing the expression again: { tab_id, name | id, values?, timeout_ms? }. A templated reader needs a value for every <PLACEHOLDER> (inserted as string-literal content, quotes escaped); a missing one fails before anything runs. Returns the raw value exactly like browser.evaluate and counts the outcome on the reader. Kept readers are listed in the knowledge start pack (list_tabs / navigate) and in browser.map.recall.
- `browser.feedback`: Tell the browser-link owner that a tool misbehaved or fell short: { tool, observed, expected }, each at most 500 characters. Stored in the owner's local activity database with your session and the app; returns { id, stored: "local" }. Nothing leaves the machine: the owner reviews it with `browser-link feedback` and decides whether to open an issue. You never open one.
- `browser.map.recall`: Recall what is already known about a browser app/route from the local map DB. Call this first when you arrive at a tab so you can reuse known selectors, flows and gotchas instead of rediscovering them. Pass origin (scheme://host:port). Optionally pass app_key to disambiguate when multiple apps share an origin, and url to filter entries down to a specific pathname. Response sections, in order: `pitfalls` (what does NOT work — read these first), `mechanisms` (how the app behaves underneath), `entries`, `learned` (present only when the map learned something from use: up to 50 `{ target, target_kind, action, ok_n, fail_n, last_reason, url_pattern, last_ok_at, last_fail_at }` recorded automatically from click/type/press/find/wait_for outcomes, rows that ever failed first, then the most used; `target` is a CSS selector or a `browser.find` semantic key as JSON, never a typed value), `flows`. `flows` are named browser.flow-replayable recipes saved for the app (`{ name, description, steps, use_count }`, not filtered by url) — adapt any placeholder text in `steps` (e.g. `type text "<QUERY>"`) to the real value before replaying with browser.flow. A selector entry whose payload carries `semantic_key` (`{ role, name, path }`) AND whose stored selector is a structural `:nth-of-type(` fallback is returned with `prefer: "semantic_key"` (computed at recall, never stored): target it with browser.find({ key: payload.semantic_key }) rather than the brittle selector. Optional `scope`: `"path"` (default, exactly the response above), `"app"` (the WHOLE map of the app, unfiltered and uncapped: `scope`, `app`, `current_build` (the most recently seen build fingerprint of the app), `pitfalls`, `mechanisms`, every `entries` row, `flows`, `readers` (every recorded browser.evaluate expression of any status with `kind`, `flags`, counters and `confidence`), `outcomes` (every learned target with counters, builds, view signature and `confidence`: fresh | unverified | failing against `current_build`), `builds` (fingerprints with first/last seen) and `learned_failures`), or `"all"` (`{ scope, apps: [<the app scope result per app of the origin>] }`). Use "app"/"all" only when you need the whole map; the start pack on list_tabs/navigate (`knowledge`) already carries the best of it.
- `browser.map.save`: Persist something learned about a browser app. Three entry kinds are supported: "selector" (a CSS selector tied to a purpose), "flow" (a free-form note about a multi-step path), and "gotcha" (a free-form note). The entry fields (url_pattern, kind, purpose, payload) are optional AS A GROUP: pass all four, or omit all four to save only `flows`, `mechanisms` or `pitfalls` (no throwaway entry needed); a partial entry or a call carrying nothing to save is rejected. Saving auto-creates the app row if needed (app_key is derived from title when not provided). Upsert on (app, url_pattern, kind, purpose). Marks verified_at = now and clears failed_at. Never save selectors or flows you have not just successfully executed. Optionally pass `flows`: an array of NAMED, REPLAYABLE flow recipes (`{ name, description?, steps }`) — `steps` must follow the EXACT browser.flow step grammar and is validated with the same rules browser.flow itself enforces. Upserts on (app, name); saving an existing name replaces its steps/description. Distinct from the "flow" entry kind above: that is a free-form note, this is a structured, browser.flow-replayable recipe returned by browser.map.recall. Also optionally pass `mechanisms` (`{ key, description }`: how the app behaves underneath) and `pitfalls` (`{ key, description, symptom? }`: what does NOT work) — behaviour, never content. A "selector" entry payload may also carry `semantic_key` (`{ role, name, path }`, the value a browser.find single match returned for that element) next to the selector: save it when the selector is a structural `:nth-of-type(` fallback, never for an `ambiguous: true` entry (refused); browser.map.recall then marks such an entry `prefer: "semantic_key"`. Never save a `ref`: refs die with the document.
- `browser.map.record_use`: Mark an entry as freshly verified or freshly failed after you used it. ok=true updates verified_at and clears failed_at; ok=false updates failed_at. Always call this after using an entry from recall so the map stays honest about what works today.
- `browser.map.forget`: Permanently delete an entry (entry_id), ONE mechanism/pitfall (insight: { app_id, kind, key } — the app_id, kind and key come straight from a browser.map.recall item), or a whole app and everything in it (app_id). Use when a refactor or app change makes the saved knowledge actively wrong.
- `browser.map.rename_app`: Rename an app_key. Useful when the heuristic from the document title picked a poor name (e.g. typos like "FLIGHT MANAGMENT" → "flight-management").
- `browser.map.apps`: List apps currently tracked in the map, most recently used first. Use to discover known origins and their app_keys.

## FAQ

### What can the agent do once a tab is connected?

The agent can read the DOM, click, type, drag, run multi-step flows, execute arbitrary JavaScript, navigate, and handle browser dialogs.

### Is my data safe when using browser-link?

The server uses a loopback-only WebSocket bridge and does not touch tabs unless you explicitly connect them. It does not persist page content in its UI map.

### Can I stop an automated process if it goes out of control?

Yes, the Chrome extension provides a Flows panel where you can see all running flows and stop them with a single click.

### What browsers are supported?

It works with Chrome, Chromium, Edge, Brave, and Vivaldi on Chromium version 118 or higher.
