ifuryst/open-browser-use/chrome

Chrome

Use this skill when the user mentions @chrome.

Chrome is the routing touchpoint for the Codex Chrome Extension:

• Use Chrome directly for browser automation requests and for Chrome setup, detection, repair, or profile checks.
• For bare or general @chrome requests, do not ask a clarification question just because the request is ambiguous. Proceed with browser automation in this skill using the chrome backend.
• If communication with the Codex Chrome Extension ultimately fails, even after checks, do not attempt to complete the user's request using applescript, bash commands or any other scripting methods.
• Do not install or repair the native host yourself. If native host setup appears broken, tell the user to reinstall the Chrome plugin from the Codex plugin UI.

Before using this skill for the first time in the current conversation context, read the entire SKILL.md file in one read. Do not use a partial range such as sed -n '1,220p'; read through the end of the file. Do not mention this internal skill-loading step to the user.

Chrome Extension Checks

On the first Chrome-backed browser task in a session, try a lightweight browser-client call such as listing open tabs after bootstrap. If the call fails, wait 2 seconds and retry the same lightweight browser-client call once. Any non-error response means the extension is installed and working.

If browser-client still reports that it cannot communicate with Chrome after that retry, confirm that Chrome is installed, running and that the extension is present in the selected Chrome profile:

From the plugin root, use node_repl to run:

scripts/chrome-is-running.js --check
scripts/installed-browsers.js --check
scripts/check-extension-installed.js --json
scripts/check-native-host-manifest.js --json

Depending on the outcome follow the following checks. Be sure to ask the user permission when required, if it is stated in the check.

1. Chrome is not installed

Keep the first response short and non-technical unless the user asks for more information.

If Chrome is not installed, then inform the user that this plugin only works with the Chrome browser.

2. Chrome is not running

Keep the first response short and non-technical unless the user asks for more information.

If Chrome is not running then ALWAYS ask the User if they would like to launch Chrome. ALWAYS wait for a user response before taking action.

3. The native host manifest is not installed, or is invalid

Keep the first response short and non-technical unless the user asks for more information.

Do not install or repair the native host yourself. If native host setup appears broken, tell the user to reinstall the Chrome plugin from the Codex plugin UI.

4. The Codex Chrome Extension is not installed

Keep the first response short and non-technical unless the user asks for more information.

If the Codex Chrome Extension is missing, tell the user:

Cannot communicate with the Codex Chrome Extension. Confirm that the extension is installed and enabled in Chrome.

Ask the User if you can open the Codex Chrome Extension webstore page so they can verify that the extension is installed. ALWAYS wait for a user response before taking action. ALWAYS refer to the extension as the Codex Chrome Extension, and not by it's extension ID.

You can construct the URL of the Codex Chrome extension webstore page by appending the extensionId from scripts/extension-id.json to https://chromewebstore.google.com/detail/codex/.

4. The Codex Chrome Extension is not enabled

Keep the first response short and non-technical unless the user asks for more information.

If the Codex Chrome Extension is not enabled ask the User if you can open the Google Chrome Extension Manager so they can verify that the extension is enabled. ALWAYS wait for a user response before taking action. Always refer to the Google Chrome Extension Manager as Google Chrome Extension Manager.

5. Codex Extension is installed and enabled, the manifest file is installed, but communication still fails

Keep the first response short and non-technical unless the user asks for more information.

If Chrome is running and the extension/native-host checks pass, ask the User if you can open a Chrome window for the selected Chrome profile and retry the connection. ALWAYS wait for a user response before taking action.

If the User agrees, run:

scripts/open-chrome-window.js

Then wait 2 seconds and retry the browser-client setup once.

After one successful setup check in a session, do not repeat extension detection unless browser-client reports an extension connection failure.

If the issue is specifically the native host or extension-backed install path, or if communication still fails after opening a Chrome window and retrying setup once, tell the user to reinstall the Chrome plugin from the Codex plugin UI. Never import or run scripts/installManifest.mjs yourself.

Chrome Error handling

File upload errors

Keep the first response short and non-technical unless the user asks for more information.

If file upload fails when using playwright_file_chooser_set_files, set_files or similar tell the user exactly this:

To enable file upload, go to chrome://extensions in Chrome, click Details under the Codex extension, and enable "Allow access to file URLs." See [here](https://developers.openai.com/codex/app/chrome-extension#upload-files) for details.

Commands

installed-browsers.js

This script reports which browsers are installed.

From the plugin root, use node_repl to run:

scripts/installed-browsers.js

Use JSON output when another tool or script needs structured data:

scripts/installed-browsers.js --json

chrome-is-running.js

This script checks whether Google Chrome is actively running. It exits 0 when Chrome is running, 1 when Chrome is not running, and 2 for usage or runtime errors.

From the plugin root, use node_repl to run:

scripts/chrome-is-running.js --check

Use JSON output when another tool or script needs structured data:

scripts/chrome-is-running.js --json

open-chrome-window.js

This script opens about:blank in a Google Chrome window for the same selected Chrome profile used by check-extension-installed.js. Use it only after the User gives permission.

From the plugin root, use node_repl to run:

scripts/open-chrome-window.js

Use dry-run JSON output when another tool or script needs to verify the selected launch command without opening Chrome:

scripts/open-chrome-window.js --dry-run --json

check-extension-installed.js

This script checks whether the selected Google Chrome profile has installed version directories for the configured public Chrome Web Store extension ID. It exits 0 when installed and enabled, 1 when installed but not enabled, 2 when not installed, and 3 for usage or runtime errors.

From the plugin root, use node_repl to run:

scripts/check-extension-installed.js

Use JSON output when another tool or script needs structured data:

scripts/check-extension-installed.js --json

The check reads the configured extension ID from scripts/extension-id.json. It detects the Chrome profile from Local State, then falls back to the highest-numbered Profile X or Default directory with Preferences. For debugging or tests, override profile selection with CODEX_CHROME_USER_DATA_DIR=/path/to/chrome-root or CODEX_CHROME_PREFERENCES_PATH=/path/to/Profile/Preferences.

check-native-host-manifest.js

This script checks whether the Chrome Native Messaging Host manifest exists for the configured native host name and allows the Chrome extension ID from scripts/extension-id.json. On Windows it also checks the Chrome NativeMessagingHosts registry key. It exits 0 when correct, 1 when missing or incorrect, and 2 for usage or runtime errors.

From the plugin root, use node_repl to run:

scripts/check-native-host-manifest.js

Use JSON output when another tool or script needs structured data:

scripts/check-native-host-manifest.js --json

Chrome Safety

• Do not inspect browser cookies, local storage, profiles, passwords, or session stores.
• Keep browser discovery read-only.
• Treat the helper output as local environment information, not as authoritative inventory for unmanaged machines.

User Tab Claiming

• To take over an already-open Chrome tab, call browser.user.openTabs(), choose the matching returned tab by its visible title, URL, recency, and tab group, then pass that exact object to browser.user.claimTab(tab).
• Claiming moves the chosen Chrome tab into the current agent tab group and returns a normal controllable Tab. Reuse that returned tab for navigation, Playwright, screenshots, CUA, and content reads.
• Do not guess tab ids. Only claim ids that came from the current openTabs() result.

File uploads

Handle file inputs and uploads through the file chooser flow.

Use this pattern:

const chooserPromise = tab.playwright.waitForEvent("filechooser", { timeoutMs: 10000 });
await tab.playwright.locator('input[type="file"]').click();
const chooser = await chooserPromise;
await chooser.setFiles(["/absolute/path/to/file.txt"]);

Notes:

• Start waitForEvent("filechooser") before clicking the file input or its associated upload control.
• Prefer the actual input[type="file"] when it is available; if the UI uses a visible button or label, click that only when it is the control that opens the chooser.
• Use absolute local paths for setFiles(...).
• Use chooser.isMultiple() before passing multiple files when needed.
• Do not look for locator.setInputFiles(...) in this wrapper; uploads are exposed via the chooser object instead.

If the task involves attaching a local file, check for a file input and try the filechooser flow before falling back to a native picker.

Tab Cleanup

• Before ending a turn after Chrome browser work, call browser.tabs.finalize({ keep }).
• Treat browser.tabs.finalize({ keep }) as the final Chrome browser action of the turn. Do not call Chrome browser tools after finalizing. If more browser work is needed, do it before finalizing, then finalize once with the final tab disposition.
• Omit tabs by default. A tab is worth keeping only when the user needs that live page after the turn; otherwise leave it out of keep.
• Omit research, search, source, intermediate, duplicate, blank, error, and login/navigation tabs after you have extracted what you need. If the user asked a question and the answer can be given in the thread, omit the tab even if it helped you answer.
• Keep a tab with status: "deliverable" when the tab itself is a user-facing output or requested open page: for example a created/edited document, spreadsheet, slide deck, dashboard, checkout/cart, submitted form result, or a page the user explicitly asked to keep open or inspect directly. Deliverable tabs move to the shared ✅ Codex tab group.
• Keep a tab with status: "handoff" only when the task is still in progress and the user or a later turn should continue from the current task tab group: for example a page waiting for user input, login, approval, payment, CAPTCHA, or an unfinished workflow.
• Explicitly agent-created omitted tabs are closed. Claimed user tabs and restored tabs without an explicit agent origin are released from the agent tab group and left open.

Bootstrap

These setup details are internal. User-facing progress updates should be less technical in nature. Never mention Node REPL, node_repl, REPL, JavaScript sessions, or module exports unless a user is asking for that exact information. If setup or recovery is needed, describe it naturally as connecting to the browser or retrying the browser connection.