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 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.

agentmods

npx agentmods add rules/compnew2006/browser-controller/browser-controller

Clone the repo

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

Per session 1,571 This file is loaded in full into every session.

When invoked 1,571 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

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	$0.01571	$0.01571
Opus 5	$0.00785	$0.00785
Sonnet 5	$0.00314	$0.00314
Haiku 4.5	$0.00157	$0.00157

Measured yesterday against content hash 11f0a8f7d4df, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, 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 yesterday.

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 · 95 lines

How it starts

The opening of the file, as written. The whole thing — 95 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)
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 now runs in the page's MAIN world via chrome.scripting (no debugger banner, CSP-safe). It no longer needs CDP.

Read the full file on GitHub · 95 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.

yesterday 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 (1 stars, last pushed 3d ago), licensed MIT. It adds 1,571 tokens to every session, about $0.0079 per session on Opus 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

browser-controller

Getting it into your agent

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

webkit-browser

cypress-e2e-testing-cursorrules-prompt-file

vasu-playwright-utils

dev-browser

node-dependencies

security-standards