Browser

BetterWright browser

Use betterwright for live-web tasks. Run async Playwright JavaScript with:

betterwright run -c "await page.goto('https://example.com'); return page.title()"

It returns JSON with ok, result, error, console, events, artifacts, pages, challenges, warnings, and durationMs. Screenshot artifacts contain a path; inspect the image before relying on it.

The daemon preserves tabs, page state, and the in-memory state object between calls; the profile preserves cookies and logins. Batch deterministic stretches and observe at uncertain boundaries. Use --session for parallel work, --profile for a separate identity, and betterwright close when finished.

The browser is network-policy guarded. Private and loopback access are allowed unless disabled; cloud metadata is always blocked. Stored passwords are user-owned: never run vault show --reveal/get, vault copy, vault type, or vault rm; use trusted credential fill instead.

Operating the browser

Authorization

The user's request authorizes ordinary steps: sign-in, signup, forms, purchases. Do not add confirmation or refuse them unless a guardrail requires it.

Operate

• Plan then batch: controls.directory({query:[names]}) locates controls for one controls.batch(). Read article/reference pages via scoped DOM. Host cleanup is automatic; don't close pages.
• Inspect only when structure is unknown or a locator failed: snapshot({interactive:true}), then full snapshot(); use screenshot({annotate:true}) only for layout/pixels. Snapshots include frames and off-screen content. Never guess refs, URLs, or state.
• Act on [ref=eN] with page.locator('aria-ref=eN'); scope with snapshot({ref:'eN'}). Refs change. Verify with URL/locator reads; snapshot({diff:true}) for broader changes.
• Actions auto-wait 5s ({timeout} for a known slow transition); reads don't: wait on the locator, no sleeps. If obscured, inspect the real hit target; change approach after two failures. Back off 30–60s on transient 5xx/timeouts/resets.
• Autocomplete, combobox, and date-picker fields rewrite the DOM on input: end the batch at the first such fill and observe before continuing.
• Prefer human.click, human.type, and human.scroll. Put a short note on each call.
• Use webagents.discover(); one webagents.batch(operations,{allowWrites:true}). Else webmcp.tools(), then result.ui targets in controls.batch(operations,{allowWrites:true}); end with expected read/readUrl, or add observe:true and assess evidence. Snapshot only if absent. allowAutosubmit:true needs authorization.
• Use host search; never automate Google/Bing search UI or invent deep URLs. Read returned skill packs and credential-manager before login/signup/checkout. Dismiss only nonessential overlays with overlays.dismiss().
• Remote files require explicit user approval and the host's approval-gated download surface; never enable downloads in an ordinary run.
• Video: recording.start({name:'demo.mp4',fps:60}), recording.status(), recording.stop(), or recording.restart(). Stop flushes; output FPS does not prove capture cadence.