opencode-browser-plugin

opencode-browser-plugin

Prefer a structured connector or API when it can complete the task. Use these browser tools for UI-only work, connector gaps, and visual verification. Do not switch to raw Node, Playwright, or another browser integration when this runtime is available.

Use browser_run, browser_observe, browser_session, and browser_finalize. Pass a user-named profile on the first useful call. Avoid status-only calls. Combine find, action, conditional settling, and post-observation in one browser_run; never synthesize fixed-delay wait steps.

Reuse sessionId. Page search uses the Snowflake model by default. Pass searchStrategy: "lexical" for lowest latency, "auto" for lexical-first adaptive retrieval, or "deep" for multilingual, code-heavy, or genuinely semantic retrieval. Request advanced descriptions with browser_observe mode capabilities, then execute a capability through a browser_run step without adding top-level tools.

Choose the browser surface deliberately. An explicit user request for a named profile or browser wins over URL-based selection; when no profile is named, let the target URL select the profile; with neither, use the default profile. Selection and discovery stay read-only — never inspect cookies, storage, profiles, passwords, or session stores. When authentication blocks a requested navigation, ask the user to sign in directly in their browser; do not substitute another profile or bypass the sign-in with a search engine, a mirror site, or any other source.

When browser setup succeeds but discovery or selection fails, read docs/troubleshooting.md — topic #discovery — before retrying. When extension or native-host installation or communication fails, read #installation before taking another recovery action.

When the user asks to continue, resume, or recall what a prior session did — or when the target describes a reasonably repeatable multi-step workflow (logins aside) that you or a previous run already attempted — consult local action memory instead of re-exploring from scratch: call memory_status first, then one bounded memory_search "<task intent>" (and memory_query only for provenance) before broader page or tab discovery. memory_search returns at most three high-level recipes and already rejects unrelated matches. Replay needs no flag: when action memory is enabled, browser_run automatically replays a remembered recipe for the steps you issue again on the same host, re-resolving each remembered target against the live DOM through the ordinary execution path, and reports memory.used with stepsReused; it falls back to normal exploration automatically when a step is stale. Pass memoryIntent only when you want bounded semantic recall for an intent that is not an exact repeat, and memoryMode: "off" only when the user asks you not to use memory at all. Typed values and URLs always come from your own request, never from memory. Treat results as evidence, not a transcript: reuse confirmed routes, treat returned negative lessons as what failed, verify current page state through the least intrusive observation, and ask the user when intent is missing. Never consult memory for unrelated tasks, and continue normally when memory is absent, disabled, unhealthy, or search returns nothing. If memory_status reports replays stuck at zero, check usage.replay_rejections_by_reason before concluding memory is broken.

For deeper network inspection of one controlled tab, request the lazy network pack and then run network.inspect:

{"mode":"capabilities","pack":"network"}

{
  "steps": [{
    "action": "capability",
    "capability": "network.inspect",
    "input": {"tabId": 123, "urlIncludes": "/api/", "includeHeaders": true}
  }]
}

The default network result is lifecycle-only. Headers are redacted, bodies are disabled by default, and includeBody: "request" | "response" | "both" is bounded, redacted, and approval-gated.

When a result is approval_required, review the chain and call browser_run again with only approvalToken. Never recreate or modify the approved chain. Retrieve screenshots and oversized results from their artifact URI. When the work is complete, call browser_finalize and pass keep only for tabs that must survive: