browser-control: Instructions file for Codex

browser-control agent guide

Use this project as a tiny browser pipe, not an agent framework.

Quick loop:

browser-control launch about:blank
export BROWSER_CONTROL_CDP_URL=http://127.0.0.1:9222
browser-control open https://example.com
browser-control inspect    # compact title/url/text/headings/actions/links
browser-control snapshot   # observe also works
browser-control click @e1
browser-control eval 'document.title'
browser-control events
browser-control network
browser-control console
browser-control cdp Browser.getVersion

Rules:

• Use snapshot before ref actions.
• Use inspect first when you need compact page text + candidate links/actions.
• Use refs for simple actions, selectors/coordinates when needed.
• Use --wait N on click/fill for late-rendered elements; wait-element for explicit polling.
• Use press ctrl+a / press cmd+shift+t style combos; editing combos (select-all/copy/paste/undo) work headless and on macOS.
• Use scroll --at x,y for inner scrollable containers; plain scroll for the window.
• Use screenshot --full for full-page captures; click --clicks 2 / --button right for double/context clicks.
• page-info reports a pending {dialog} instead of hanging; clear it with dialog accept|dismiss.
• eval accepts top-level return (auto-wrapped in an IIFE).
• Use eval or cdp as the raw escape hatch.
• Use events, network, and console when diagnosing flaky waits/pages.
• Use --frame <target-id|url-substring> on eval, click, or fill for OOPIF/frame targets.
• Put reusable scripts in .browser-control/scripts.
• Verify with text, eval, screenshot, or raw CDP before saying done.
• Check .browser-control/traces/* after failures.
• Short env aliases BU_CDP_WS and BU_CDP_URL are accepted.

Lifecycle:

browser-control stop     # stop browser launched by browser-control
browser-control reload   # same minimal lifecycle reset