Skip to content

AGENTS.md

Latest commit

 

History

History
44 lines (38 loc) · 1.9 KB

AGENTS.md

File metadata and controls

44 lines (38 loc) · 1.9 KB
Raw

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