compnew2006/browser-controller

The missing piece in AI coding: your agent can now see your REAL browser.
= 20" />
---
What this project solves
You ship a fix. Your agent says "done, please verify."
You alt-tab to Chrome, navigate to the page, log in, click around, find the bug.
Your agent just wrote the code. It could also verify it.
It already has your browser open right there. It just can't see it.
**Now it can.** Browser Controller gives any MCP-compatible AI agent (Cursor, Claude Desktop, Windsurf, …) direct control of the **browser you already have open** — your real sessions, your logins, your cookies. No headless browser, no fresh profile, no re-authentication.
Key capabilities
- **Multiple agents at once.** Cursor can drive tab 10 while Claude drives tab 11 — both through one shared daemon, neither blocking the other.
- **Tab targeting, not "the active tab."** Every action names a tabId. Move your mouse, switch tabs, watch YouTube — the agent keeps working on the tab you told it to. It never hijacks the page you're reading.
- **Per-tab isolation.** Element refs, console logs, and network buffers are scoped per tab. A ref from tab 10 can never click something in tab 20.
- **Per-tab concurrency.** Two actions on the _same_ tab serialize (no races); actions on _different_ tabs run in parallel.
- **Tab locking.** An agent can claim a tab so others queue behind it instead of racing (browser_tabs { action: "lock" }). Locks survive Chrome's service-worker recycling (chrome.storage.session).
- **Agent-control shield.** While an agent works on a tab you see a translucent blue inner frame and your input on that tab is blocked (mouse, keyboard, wheel) — the badge shows agent controlling the tab and disappears when the action finishes. Locking a tab keeps a plain frame for the lock's lifetime.
- **Visible agent cursor (optional).** Switch on *Show agent cursor* in the popup's Settings and every agent mouse action (click, hover, wheel, drag — including browser_act) draws a blue pointer that glides to its target before the input lands — a ripple marks each click, the arrow presses in while dragging — so you can follow what the agent does. Off by default: the glide adds ~0.2–0.35 s to each mouse action on a visible tab (none in hidden tabs). It fades after a few idle seconds and stays out of the agent's own screenshots.
- **Same-origin iframe piercing.** Legacy/enterprise UIs that live inside iframes (e.g. an ONT console in iframe#mainFrame) are reachable: all locator tools search iframe documents, and find/click_text walk every frame.
- **Open-dialog rescue.** A native alert/confirm/prompt freezes the page's JS thread — browser_handle_dialog dismisses it out-of-band via CDP, no page JS needed, which also un-blocks every other tool on that tab. browser_tabs close/focus always work, even on a frozen tab.
- **Authenticated local connection.** Token + enrollment secret, so no other local process can silently drive your browser — and after a one-time npm run setup:pairing the extension pairs itself, no secret to paste. Everything stays on localhost — no cloud, no telemetry.
- **Versioned compatibility handshake.** The daemon and extension advertise an application-protocol version, build version, and capabilities before tool traffic is accepted. Explicitly incompatible protocol majors fail with an actionable error instead of producing unexplained timeouts; the build version is diagnostic and does not by itself make compatible peers fail.
- **Real, trusted input.** Clicks, typing and key presses go through the Chrome DevTools Protocol, so the page sees isTrusted events, focus really moves, default actions run (Tab moves focus, Enter submits, arrows drive autocomplete menus) and focus/blur fire even while the window is in the background — legacy grids and lookup widgets behave as they do for a person. One debugger session per tab is reused and detached after 30 s idle (the yellow "being debugged" banner shows only while it is attached). Pass trusted: false for the old synthetic events with no banner; they are also the automatic fallback when the debugger can't attach.
- **Batches.** browser_batch runs a list of tool calls in one round-trip and stops at the first failure — a click → type → Tab → wait → read sequence is one call instead of five.
- **WebMCP-aware.** On sites that expose their own actions through WebMCP, browser_webmcp_list / browser_webmcp_call call them directly instead of clicking through the UI — with confirmation gates for consequential tools and page output flagged as untrusted.
- **Console-style JavaScript.** browser_evaluate accepts code as you'd type it in DevTools: top-level await, several statements, the last expression's value is returned, DOM nodes come back as readable descriptions — and page CSP doesn't block it.