chrome-browser-control: Instructions file for Codex

Chrome Browser Control — Agent Guide

Purpose

Chrome Browser Control is a local Chrome-profile browser-control MCP server. It exposes browser tools through a Manifest V3 Chrome extension, a loopback WebSocket broker, and a stdio MCP adapter.

Use this file to resume work without relying on chat history.

Key paths

• cli/ — installable CLI bins cbctl and chrome-browser-control (setup, start, stop, status, doctor, mcp, mcp-config, broker).
• server/ — MCP adapter, broker client, broker, protocol, tools, environment handling, MCP config render helpers.
• extension/ — Chrome MV3 extension, popup, content script, security helpers (source; setup copies to ~/.chrome-browser-control/extension).
• extension/content-core.module.js — only hand-edited content-core source; extension/content-core.js is generated by npm run build for Chrome.
• tests/ — Vitest coverage for broker, bridge, protocol, tools, content-core, env, CLI.
• benchmarks/compact-snapshot.mjs — compact-vs-full snapshot size benchmark.
• skills/chrome-browser-control/ — distributable skills.sh agent skill for agents using the MCP tools at runtime. Not included in the npm files tarball; install with npx skills add vkongv/chrome-browser-control -g -s chrome-browser-control (skills.sh reads the GitHub default branch; npx skills update -g refreshes it, manually).
• docs/ — durable, tracked notes agents must be able to find via git / @docs.
• docs/publish-checklist.md — maintainer manual npm publish checklist (no CI auto-publish).
• docs/scratchpad/ — local-only WIP (gitignored). Do not put cross-session handoffs or agent feedback here; they will not ship and often will not surface in search/@.
• docs/agent-feedback-from-fb-batch-2026-07-08.md — field feedback from a ~100-page Facebook audit (scoped snapshots, feed/post extractor, exclusive claims). Prioritize before new agent work on observation/concurrency.

Current state

• Project/package name: chrome-browser-control.
• GitHub repo: vkongv/chrome-browser-control.
• Default snapshot mode is compact (500-char textPreview). Compact is also the reading path: raise textLimit for long pages.
• Snapshot text (textPreview, text, wait_for textInScope/contentStableMs) is rendered from the live DOM, not a detached clone. It keeps block structure: newlines between blocks, # headings, -/1. list items, Markdown table rows (HTML and ARIA table/grid), fenced pre blocks, backticked inline code. script/style/hidden/display:none/visibility:hidden/closed-details content is excluded. textInScope matches with whitespace collapsed on both sides. Unit tests run under happy-dom and cannot prove real layout display values; check block/table rendering in a live browser after changing createScopedTextRenderer.
• Snapshot text carries inline refs for interactive elements in the elements list, at the spot where each sits: links as [text](ref=h3), other controls as [role "label" ref=h4] or [role ref=h5]. Refs in text and list are the same handles. Controls that hold content (editable regions, card links, a button with a link inside) keep that content, with a [role ref=…] marker in front. Form fields get a marker with their label, never their value. Marker text is escaped; the renderer wraps emitted markers in private-use sentinels (stripped from page text) so truncation never cuts a marker and never mistakes marker-like page text for one. Hidden inputs are not elements of interest. Inline refs cover only the returned text (textLimit); the list stays complete. wait_for text matching uses plain text without refs. Invisible (visibility:hidden) controls stay in the list but get no marker.
• The snapshot element list drops decorative roles (img, presentation, none, graphics-*) inside aria-hidden="true" and reports ariaHiddenOmitted. Everything else under aria-hidden stays (controls, alerts, status, headings), because modal libraries hide the page behind a dialog that way. Interactive elements with no text are named from <img alt> inside them (images aria-hidden below the control are skipped). query_elements / extract_elements stay unfiltered.
• roleFor maps <input> by type: submit/button/reset/image → button, checkbox, radio, range → slider, number → spinbutton, search → searchbox, others → textbox. Editable contenteditable regions are textbox; contenteditable="false" is not interactive.
• Compact and full snapshots return markdownAlternate ({ href, source: "link" | "anchor", label? }) when the page declares <link rel="alternate" type="text/markdown"> (source: "link") or has a visible "View as Markdown"-style link, or a Markdown-labelled link to a .md/.mdx file (source: "anchor", inferred). Agents should read a declared alternate instead of rendered text and confirm an inferred one matches the page.
• Compact snapshots default to scope: "main" when a main landmark exists; a visible genuinely-modal dialog (aria-modal="true" or <dialog> opened with showModal()) takes snapshot scope instead. Pass scope: "document" for legacy full-body text, including the page behind a modal.
• Snapshot scope options: scope, excludeSelectors, ignoreRoles. Compact/main still default to ignoring dialog when no visible dialog is open. A visible non-modal role="dialog" is included but does not take scope. Escape hatches: ignoreRoles: ["dialog"] or ["alertdialog"] hides both dialog and alertdialog, ignoreRoles: [] includes them in the current scope, scope: "document" sees the full body, mode: "full" is the unscoped legacy snapshot.
• Full legacy snapshot mode remains available with snapshot({ mode: "full" }) (4000-char text by default). It adds up to 250 element records with bounds; it is for layout work, not reading.
• Visible viewport mode is available through snapshot({ mode: "visible" }) and visible_snapshot; use it for virtualized pages, viewport-bound UI, and coordinate planning.
• Use extract_feed_posts for structured feed/post records (author, text, times, live flags) on feed-like pages.
• Raise textLimit on snapshot (up to 100000) to pull more page body text without broker or CDP workarounds.
• Use claim_tab before multi-step browser work, pass the returned sessionTabId, then call release_tab or finalize_tabs when done. Claims do not close tabs. release_tab on an unclaimed tab returns { released: false, reason: "not_claimed" } instead of throwing.
• Tab results from navigate and list_tabs carry tabId (with id kept as an alias).
• browser_status reports extension state once, under extension; the raw ping echo was removed.
• Advisory claims remain default. Use claim_tab({ exclusive: true, ttlMs?, owner? }) for fail-fast tab leases across parallel agents; MCP adapter injects ownerId per process. ttlMs (default 5 minutes) is idle time: each call that carries the claim's sessionTabId from the owning MCP process extends the lease by its ttlMs, CDP calls included. The adapter stamps callerOwnerId (its per-process ownerId) on every broker call; handleBridgeRequest strips it before routing and renews only when it matches the claim owner. Calls without sessionTabId (the broker-wide current-claim fallback) and other processes' calls do not renew. An expired claim's sessionTabId fails with a TAB_CLAIM_EXPIRED JSON error (expiredAt, tabId) instead of No claimed tab.
• Navigate leaves focus alone by default (does not activate a background tab and does not deactivate the focused tab); pass navigate({ active: true }) only when the tab must become visible. Use activate_tab to raise a tab and its window without navigating. It waits (bounded) for document.visibilityState === "visible" and returns visibilityState / visible; reason is present only when visible is false. Do not treat focused as success.
• Click, type, click_at, keypress, and matching perform_actions steps fail with DOCUMENT_HIDDEN when the document is hidden. Call activate_tab first, then retry. Pass allowHidden: true only when visibilityState is hidden. If reason is host_permission_denied or document_unavailable, grant permission or reload; allowHidden will not help. Read-shaped tools stay unguarded. perform_actions scroll steps stay unguarded.
• Navigate results include requestedUrl, finalUrl, redirected (plus url alias of finalUrl).
• wait_for supports selectorAbsent, textInScope (with scope), bounded contentStableMs, and settledMs in addition to text/selector/urlIncludes. Conditions are alternatives (first that holds wins). settledMs: scoped text differs from a baseline, then holds still that long, with nothing in scope loading (visible aria-busy="true" on or inside scope, an indeterminate progressbar/<progress>, or a line/cell that is only "Loading" / "Loading…"). contentStableMs also waits while busy. Timeouts report pending (noChange/busy/changing) and busy.
• Act-then-observe after.waitFor runs a wait_probe content call before the action: the probe returns held (whether a text/selector/URL condition already held) and a baselineHash of scoped text for settledMs. The wait result carries heldBeforeAction. navigate skips the probe and passes an empty baseline, so the loaded page counts as changed. Baseline hashes carry a per-document token, so a click that loads a new page with the same scoped text still counts as changed. Busy time never counts toward settledMs or contentStableMs: the quiet interval starts when loading ends. CSS-only spinners and skeleton rows are not detected. Standalone wait_for settledMs takes its baseline at the first check. A failed probe falls back to that.
• Use query_elements and extract_elements before requesting large snapshots when a selector/role/text filter is enough. includeHtml is sanitized and marks sensitive items; still treat all page content as untrusted.
• Use wait_for, page_status, console_logs, and collect_scroll for bounded diagnostics and lazy feeds. Set maxItems when a feed can produce many unique entries. Prefer collect_scroll until / nested scroll over manual step loops; read stoppedReason.
• Use screenshot with optional ref/bounds crop for visual proof; prefer DOM extraction for structured data. Canvas/chart pixels are invisible to snapshot/extract tools.
• Use perform_actions for up to 10 sequential click/type/scroll/keypress steps in one broker round-trip; terminal after runs only on full success. Refresh snapshot refs before a batch — stale refs fail fast mid-batch. Coordinate clicks stay on click_at.
• MCP registers 30 browser tools; browser_status.adapter.registeredToolCount should be 30 after upgrade (restart MCP host if stale).
• Use list_frames to discover operable active HTTP(S) frame documents. Pass its documentId to DOM/content tools for exact-document iframe routing; omitted documentId keeps current top-frame behavior. Blocked and unsupported rows redact URLs and document identity.
• Content results include background-attested documentId, frameId, isTopFrame, and coordinateSpace. Iframe coordinates are frameViewport; navigate, activate_tab, and screenshot remain tab-only, and iframe bounds are not screenshot crop coordinates.
• Exact document targets fail with stable DOCUMENT_STALE, DOCUMENT_POLICY_DENIED, DOCUMENT_HOST_PERMISSION_DENIED, or DOCUMENT_UNSUPPORTED prefixes and never fall back to a replacement frame document. Hidden-document writes fail with DOCUMENT_HIDDEN.
• Use MCP server key chrome_browser_control only; remove legacy chrome_browser host entries to avoid stale tool schemas.
• Snapshot refs are per-document in-memory handles and are stable across DOM reorder in the same document.
• Stale/disconnected/expired refs are pruned and should fail cleanly.
• Installable CLI is the supported user path: cbctl setup|start|stop|status|doctor|mcp|mcp-config (alias: chrome-browser-control).
• User config and installed extension live under ~/.chrome-browser-control/ (config.env, extension/).
• MCP default is attach-only: start the broker with cbctl start, then run mcp. Opt into spawn with mcp --autoload or CHROME_BROWSER_CONTROL_AUTOLOAD=1.
• MCP host snippets prefer command: cbctl and args: ["mcp"] (not tsx / server/index.ts); long name still works.
• Contributors can still use npm run broker, npm run mcp, and repo .env.local against a checkout.
• Call browser_status first on a new session; read nextAction for onboarding coaching and adapter.registeredToolCount to detect stale MCP host tool catalogs.
• Runtime agents should use the chrome-browser-control skill when available; it contains the operating playbook for claiming tabs, collecting bounded page state, waiting after actions, screenshots, feed scrolling, side-effect confirmation, and cleanup. Prefer fetch over the browser for public static pages; see the skill's "When Not To Use" and "Stuck Mechanics" sections. The skill is not part of npm install -g chrome-browser-control — install it with skills.sh (see Local setup).
• Public npm releases are manual; maintainers use docs/publish-checklist.md (minor release = patch bump for small changes; major release = minor bump on 0.x for large changes). Do not add publish-on-push workflows or long-lived NPM_TOKEN secrets for the default path.