What is openbrowser CLAUDE.md?

Project guidance for OpenBrowser, a Chrome extension and zero-dependency MCP server that lets coding agents control real Chrome tabs using the user’s logged-in browser.

Use it when changing the MCP server, Chrome extension, browser sessions, WebSocket hub, or routing between clients, browsers, and windows.

It explains the separate server and extension parts, their failure modes, and the rules needed to preserve the project’s dependency-free design.

How dylansantwani/openbrowser configures Claude Code

Reuse

Borrowing it

Nothing to install: this file belongs to dylansantwani/openbrowser. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/dylansantwani/openbrowser/main/CLAUDE.md

Clone the repo

git clone --depth 1 https://github.com/dylansantwani/openbrowser

Made for: Claude Code.

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/instructions/dylansantwani/openbrowser/claude-md/github.svg)](https://agentmods.dev/instructions/dylansantwani/openbrowser/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/dylansantwani/openbrowser/claude-md"><img src="https://agentmods.dev/badge/instructions/dylansantwani/openbrowser/claude-md/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/instructions/dylansantwani/openbrowser/claude-md"><img src="https://agentmods.dev/badge/instructions/dylansantwani/openbrowser/claude-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 13,648 This file is loaded in full into every session.

When invoked 13,648 The same file — it is already loaded in full.

Security scan A 1 finding. 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.13648	$0.13648
Opus 5.5	$0.05459	$0.05459
Sonnet 5.5	$0.02730	$0.02730
Haiku 4.5	$0.01365	$0.01365

Measured 1mo ago against content hash 7ad9b4550fcf, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

openbrowser CLAUDE.md scanned grade A with 1 finding 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 1mo 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.

Runs shell commandslowCapability

Expected in a hook, worth knowing in a rule or an instructions file.

import { spawn } from 'node:child_process';

CLAUDE.md · 950 lines

How it starts

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

OpenBrowser — working guidance

Read this before changing anything in openbrowser/. It exists because most of what is non-obvious here was learned by driving the extension against real sites and watching it fail in ways that are invisible from unit tests.

What this is

A Chrome extension plus a zero-dependency MCP server, letting any MCP client (Claude Code, opencode, Cursor) drive a real Chrome browser with the user's real logins.

  MCP client ──stdio──> mcp-server ──ws://127.0.0.1:8848──> extension ──> tabs

Several MCP clients share one hub, and one hub drives several browsers. A session is bound to one browser and to one window inside it; the hub routes by that binding. See "The browser was never a singleton" below.

Two halves, two languages of failure:

mcp-server/ is Node. Bugs here look like "the tool never appears in my client" or "every call times out".
extension/ is MV3. Bugs here look like "it says it worked but nothing happened".

Hard rules

Never add a dependency. Both package.json files have empty dependencies and that is the single most important property of this project. npm install failing is the most common reason a local MCP server does not work, and it fails silently from the user's point of view. The WebSocket (src/ws.js) and the MCP protocol (src/mcp.js) are hand-written for exactly this reason. If you need a library, write the 200 lines instead.

stdout is protocol-only. In mcp-server/, anything written to stdout that is not a JSON-RPC frame corrupts the stream and the client drops the connection with no useful error. Human-readable output goes to stderr.

The service worker has no memory. MV3 kills it after ~30s idle and restarts it constantly. Anything durable lives in chrome.storage; anything else is rebuilt on demand. Every top-level statement in background/ must be safe to run many times.

Errors are written for a model to recover from. "ref e12 no longer exists — the page changed; take a fresh snapshot" beats "Error: null". Put the recovery action in the message. This is not politeness; it is the difference between an agent retrying correctly and an agent giving up.

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

1mo ago Changed 7ad9b4550fcf
2mo ago Changed · +58 lines · +918 tokens per session 0d847a3da0c4
2mo ago Changed · +112 lines · +1,927 tokens per session 260b2d1cdc02
2mo ago Changed · +36 lines · +556 tokens per session 38d426c8b443
2mo ago First seen · 744 lines · 10,247 tokens per session scan A d00484153412

Subscribe to this mod's changes

openbrowser CLAUDE.md is an instructions file published in the GitHub repository dylansantwani/openbrowser (0 stars, last pushed 1mo ago), licensed MIT. It adds 13,648 tokens to every session, about $0.0546 per session on Opus 5.5. A static security scan graded it A with 1 finding (runs shell commands). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Browser automation ai-agents browser-automation chrome-extension claude llm-tools mcp

openbrowser CLAUDE.md next to 6 instructions from other repositories
Mod	Type	Stars	Last push	Licence	Scan	Tokens	Works with
openbrowser CLAUDE.mddylansantwani/openbrowser	Instructions file	0	1mo ago	MIT	A	13,648	Claude Code
vscode buildNext.instructions.mdmicrosoft/vscode	Instructions file	195k	today	MIT	A	9,719	GitHub Copilot
next.js AGENTS.mdvercel/next.js	Instructions file	143k	today	MIT	A	7,461	Codex, OpenCode
vscode oss-third-party-notices.instructions.mdmicrosoft/vscode	Instructions file	195k	today	MIT	A	5,649	GitHub Copilot
langchain AGENTS.mdlangchain-ai/langchain	Instructions file	149k	today	MIT	A	4,680	Codex, OpenCode
vscode copilot-instructions.mdmicrosoft/vscode	Instructions file	195k	today	MIT	A	3,093	GitHub Copilot
vscode model-prompts.instructions.mdmicrosoft/vscode	Instructions file	195k	today	MIT	A	2,022	GitHub Copilot

openbrowser: Instructions file for Claude Code