What is browser-controller?

Browser-control instructions for operating the user's real Chrome browser, including its existing tabs, logins, and cookies.

Controlling pages in the user's browser, such as reading, clicking, typing, or navigating within a selected tab.

They prevent actions from going to the wrong tab or disrupting work the user is doing. They also require choosing and, when needed, locking the exact tab first.

browser-controller — Cursor rule for Cursor by compnew2006

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Clone the repo

git clone --depth 1 https://github.com/compnew2006/browser-controller

Made for: Cursor.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/rules/compnew2006/browser-controller/browser-controller/github.svg)](https://agentmods.dev/rules/compnew2006/browser-controller/browser-controller)

Your own site

<a href="https://agentmods.dev/rules/compnew2006/browser-controller/browser-controller"><img src="https://agentmods.dev/badge/rules/compnew2006/browser-controller/browser-controller/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/rules/compnew2006/browser-controller/browser-controller"><img src="https://agentmods.dev/badge/rules/compnew2006/browser-controller/browser-controller.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 2,947 This file is loaded in full into every session.

When invoked 2,947 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.02947	$0.02947
Opus 5.5	$0.01179	$0.01179
Sonnet 5.5	$0.00589	$0.00589
Haiku 4.5	$0.00295	$0.00295

Measured 2d ago against content hash 98bf28fa4bb2, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

browser-controller scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

agent-config/cursor/rules/browser-controller.mdc · 119 lines

How it starts

The opening of the file, as written. The whole thing — 119 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Browser Controller

MCP server: browser-controller. Controls the user's REAL Chrome browser - not headless. All sessions, logins, cookies are already active.

CRITICAL: Tab-targeting model (v2)

This is a multi-client server. Other agents may be working in other tabs right now. Never assume which tab your actions hit. You MUST target a tab explicitly.

The required flow (instead of "snapshot the active tab")

browser_tabs with action: "list" → get a tabId for the tab you want to work in
Pass that same tabId to EVERY page-interaction tool (browser_snapshot, browser_click, browser_type, …)
Refs from a snapshot are only valid for the tabId that produced them. A ref from tab 10 will never resolve on tab 20.
If you need exclusive access to a tab (another agent might touch it), browser_tabs with action: "lock", tabId first; action: "unlock" when done.

If tabId is missing on a page tool, you'll get: "tabId is required. Call browser_tabs list first."

Rules

NEVER close tabs you didn't create
NEVER navigate away from pages the user is working on without asking
ALWAYS pass tabId — the "active tab" the user is looking at is NOT yours to act on
Prefer browser_snapshot over browser_screenshot (cheaper, faster, parseable)
Several steps you already know → one browser_batch call (it stops at the first failing step)
Refs break after navigation/scroll/DOM changes - re-snapshot before using stale refs
Refs recover automatically: if a ref goes stale but the element still exists, the tool finds it via a robust selector + text/role scan (response carries via: "fallback"). If the element was scrolled away entirely, the response carries freshRefs: [...] — retry with one of those new refs in the same step, no separate snapshot needed.
isNew: true on a snapshot ref means the element appeared since the last snapshot. After an action opens an overlay/dropdown, filter to isNew refs instead of re-reading the whole tree.
After browser_scroll, expect refsMayBeStale: true on feeds that recycle DOM nodes (Facebook/Instagram/Twitter) — re-snapshot before interacting.
browser_evaluate runs over CDP by default: DevTools-console semantics (top-level await, last expression returned) and page CSP does not block it; the yellow "being debugged" banner shows while the debugger is attached. mode: "scripting" runs it via chrome.scripting instead — no banner, but a strict page CSP can block it.

Read the full file on GitHub · 119 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

2d ago Changed · +1 lines · +125 tokens per session 98bf28fa4bb2
7d ago Changed · +4 lines · +143 tokens per session 95de3e3365bb
9d ago Changed · +19 lines · +1,108 tokens per session b897a17515f9
1mo ago First seen · 95 lines · 1,571 tokens per session scan A 11f0a8f7d4df

Subscribe to this mod's changes

browser-controller is a cursor rule published in the GitHub repository compnew2006/browser-controller (8 stars, last pushed yesterday), licensed MIT. It adds 2,947 tokens to every session, about $0.0118 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Browser automation TypeScript ai-agents browser-automation chrome-extension mcp mcp-server

browser-controller

Getting it into your agent

Wrote this? Show the measurements

What it costs to keep this loaded

Grade A, and why

Nothing flagged

How it starts

Browser Controller

CRITICAL: Tab-targeting model (v2)

The required flow (instead of "snapshot the active tab")

Rules

What this file has done since we first saw it

Other cursor rules, from other repositories

real-browser-mcp

invictum-browser

testing

ponytail

angular-20

dev-standard