chromium-browser

name	chromium-browser
description	Control Chrome and Chromium-based browsers through the OpenCode Browser extension and native host.

Chromium Browser

Use this skill when the user asks OpenCode to inspect, navigate, automate, test, screenshot, or interact with Chrome or a Chromium-based browser.

Runtime Model

This integration does not use Codex's Node REPL or browser-client.mjs runtime.

Use OpenCode browser tools directly:

• browser_status
• browser_capabilities
• browser_list_profiles
• browser_selected_profile
• browser_select_profile
• browser_name_profile
• browser_list_tabs
• browser_selected_tab
• browser_get_tab
• browser_new_tab
• browser_claim_tab
• browser_name_session
• browser_navigate
• browser_reload
• browser_back
• browser_forward
• browser_close_tab
• browser_history
• browser_screenshot
• browser_move
• browser_click
• browser_double_click
• browser_scroll
• browser_drag
• browser_type
• browser_keypress
• browser_snapshot
• browser_dom_snapshot
• browser_dom_click
• browser_dom_type
• browser_locator_count
• browser_locator_click
• browser_locator_fill
• browser_locator_text
• browser_set_file_input
• browser_clipboard_read_text
• browser_clipboard_write_text
• browser_enable_inspection
• browser_console_logs
• browser_network_events
• browser_clear_events
• browser_download_events
• browser_clear_download_events
• browser_cdp
• browser_turn_end
• browser_finalize

First Step

Before browser work, call browser_status.

If the native host is not reachable, tell the user to load the extension and install the native messaging manifest before retrying.

If more than one browser profile is connected, call browser_list_profiles and then browser_select_profile before opening, claiming, or inspecting tabs. Do not choose randomly. If the required profile is not listed, report that it is not open; do not launch another profile unless the user explicitly asks.

For setup diagnostics, use the repository scripts:

• bun run list:browsers
• bun run check:browser-running -- --browser chrome
• bun run check:extension -- --browser chrome --extension-id <extension-id>
• bun run check:native-host -- chrome --extension-id <extension-id> --json
• bun run open:browser -- --browser chrome --dry-run

Only run scripts/open-browser-window.js without --dry-run after the user agrees to open a browser window.

Tab Use

• Browser profiles are separate targets. Use browser_list_profiles to see only currently open profiles, and browser_select_profile to switch between them.
• Use browser_name_profile only when the user asks to label a profile, or when a short non-sensitive local label is useful for future selection.
• When a selected profile disappears, treat tool failure as a real disconnect. Do not fall back to another profile.
• Use browser_list_tabs with scope: "user" to find existing tabs.
• Use browser_claim_tab when the user wants to control an already-open tab.
• Claim only tabs returned by browser_list_tabs with scope: "user"; do not guess tab IDs.
• Use browser_new_tab or browser_navigate without tabId for a new controlled tab.
• Controlled tabs are session-owned. A tab created or claimed by one browser session cannot be controlled by another browser session.
• For sub-agents or parallel browser work, have each agent create or claim its own tab in its own session. Do not create tabs in the parent session and hand those tab IDs to sub-agents.
• If multiple agents need the same site, each agent should open the site independently in its own controlled tab.
• Session tabs are grouped in the browser by the extension.
• The extension tracks whether a tab was agent-created or user-claimed. browser_finalize closes unkept agent-created tabs and releases unkept user-claimed tabs without closing them.
• Use browser_finalize before ending browser work. Keep tabs only when the user needs the live page after the turn.
• Use status: "deliverable" for tabs that are final user-facing outputs.

Web Search

• Prefer interactive search over direct Google search-result URLs. Open https://www.google.com/, type the query into the page, and submit it like a user.
• Avoid constructing direct /search?q=... Google URLs unless there is a strong reason. Direct search-result navigation is more likely to trigger automated-traffic or CAPTCHA pages.
• Do not attempt to bypass CAPTCHAs or automated-traffic interstitials. If one appears, report it and use another source or a more targeted site URL.

Reliable Input

• Browser tools target the controlled tab through the extension and CDP without bringing that tab or window to the foreground by default.
• Use browser_move when you need to show the OpenCode cursor overlay before acting on the current tab.
• browser_click, browser_double_click, and browser_drag serialize mouse gestures per tab so concurrent agents do not interleave press/move/release events.
• browser_locator_click and browser_dom_click now verify that the target exists, is visible, is enabled, accepts pointer events, and is not covered at its click point. If those checks fail, treat the tool failure as real feedback and inspect again before retrying.
• browser_type, browser_dom_type, and browser_locator_fill require an editable focused/target element and verify the resulting value or text changed as expected.
• browser_keypress supports common chords such as Control+A, Ctrl+A, Meta+A, and Shift+Tab. Edit chords such as select-all require a focused editable element and fail if verification fails.
• browser_navigate waits for domcontentloaded by default. Pass waitUntil: "none" only when you intentionally want to race page loading, or waitUntil: "load" when full load completion matters.
• If a coordinate click misses, take a fresh screenshot or snapshot before choosing new coordinates.
• Prefer browser_dom_snapshot plus browser_dom_click for visible interactable elements when it avoids brittle coordinates. Node IDs are snapshot-scoped; take a fresh snapshot after navigation or major DOM changes.
• Use browser_locator_* for straightforward CSS-selector interactions; failed selectors, hidden elements, disabled controls, and covered targets should be handled by inspecting the page again rather than assuming success.

Inspection

• Use browser_enable_inspection before collecting console or network events.
• Use browser_console_logs for Runtime.consoleAPICalled and Log.entryAdded events.
• Use browser_network_events for captured Network.* events.
• Use browser_cdp for targeted CDP commands such as Runtime.evaluate, DOM.getDocument, or Performance.getMetrics; pass command parameters with params, or with paramsJson if the client does not expose arbitrary object params. The plugin enables the Performance domain automatically for metrics.
• Use browser_download_events after actions that may start downloads. Inline PDFs are reported with status: "opened_inline" when Chrome opens them in the browser instead of downloading them.
• Use browser_set_file_input for file inputs after confirming uploads with the user when required.
• Confirm before reading or writing clipboard content unless the user explicitly requested clipboard use.

Interaction Safety

Confirm before actions that submit forms, send messages, upload files, make purchases, change permissions, delete data, save passwords/payment details, or transmit sensitive personal data.

Do not solve CAPTCHAs, bypass paywalls, bypass browser safety interstitials, or complete final password-change submissions.

Current Limitations

• Initial browser target is Chrome and Chromium-based browsers.
• Firefox is not supported in this version.
• Locator-style interactions are CSS-selector based, not full Playwright parity.
• Screenshots return base64 PNG data from the tool.