Project rules and technical context for browser-controller, a system that lets AI agents control browser tabs through a local server and Chrome extension.

Use it when changing the TypeScript server, daemon, Chrome extension, browser tools, tab selection, local networking, or stored state.

It records the architecture and rules that prevent agents from targeting the wrong tab or breaking communication between the components.

project — 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/project

Clone the repo

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

Made for: Cursor.

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

When invoked 1,281 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.01281	$0.01281
Opus 5	$0.00641	$0.00641
Sonnet 5	$0.00256	$0.00256
Haiku 4.5	$0.00128	$0.00128

Measured yesterday against content hash 38aba765156f, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

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

.cursor/rules/project.mdc · 76 lines

How it starts

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

browser-controller

Multi-client MCP server (TypeScript) + Chrome extension (plain JS). Renamed from real-browser-mcp (v2.0.0). npm browser-controller, MCP id io.github.noiemany/browser-controller.

Three-piece architecture

Agent ─stdio─ thin MCP client (index.ts) ─IPC─► daemon (daemon.ts, owns :7225) ─WS─► extension (background.js)

The daemon owns the WS server on 7225 AND an HTTP server on the same port (/pair returns the token, /status returns agents). The extension auto-fetches the token via /pair (MV3 can't read the filesystem).
Bind host is 127.0.0.1 (NOT 'localhost' — macOS resolves localhost to IPv6 ::1 first and refuses IPv4). Both WS connect and HTTP fetch use 127.0.0.1.
Thin client auto-spawns the daemon if absent. State in ~/.browser-controller/.

The two invariants

tabId is mandatory for every page-interaction tool. navigate is the ONE exception (optional, active-tab fallback). tabs create/close/focus/list take no target tabId. Enforced via requireTabId() in tools/types.ts.
background.js never acts on "the active tab" implicitly — resolveTab(tabId) is the entry point. The active-tab fallback survives ONLY inside handleNavigate.

Element identification (3 layers + auto-recovery)

data-mcp-ref="e5" (fast, breaks on re-render)
robust CSS selector via smart-selector.js (climbs ≤3 ancestors, ignores React/generated classes+ids)
text+role+tag scan (survives total class/id churn) — resolves the correct sibling via nth ordinal when several elements share text+role (e.g. 3 "Like" buttons)

autoReSnapshot: on ref failure (virtualized feed), snapshot the tab and embed freshRefs in the response so the agent retries in one step. Do NOT auto-retry the click (non-idempotent). browser_scroll returns refsMayBeStale: true as a hint.
isNew: each snapshot tracks role|name fingerprints per tab; elements appearing since the last snapshot are tagged isNew: true so the agent can focus on what changed (big token saver after an overlay/dropdown opens). State lives in lastSnapshotFingerprints Map, cleared on tab close.

Read the full file on GitHub · 76 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 · 76 lines · 1,281 tokens per session scan A 38aba765156f

Subscribe to this mod's changes

project is a cursor rule published in the GitHub repository compnew2006/browser-controller (1 stars, last pushed 3d ago), licensed MIT. It adds 1,281 tokens to every session, about $0.0064 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 Languages

project

Getting it into your agent

What it costs to keep this loaded

Grade A, and why

Nothing flagged

How it starts

browser-controller

Three-piece architecture

The two invariants

Element identification (3 layers + auto-recovery)

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