Browser Control

Support

Install safely, verify the connection, and stay in control.

Browser Control currently supports Google Chrome and Brave on macOS and needs a local companion because Chromium extensions cannot start Codex CLI directly.

Requirements

node --version
codex --version

Install the companion

  1. Install Browser Control from its Chrome Web Store listing.
  2. Download the companion ZIP and matching SHA256SUMS from the official GitHub Releases page. Do not download a repackaged copy from another site.
  3. Extract the ZIP. In Terminal, change to that extracted directory.
  4. Verify the archive contents using the checksum instructions included with the release.
  5. Run node scripts/install-native-host.mjs. The installer prints the Chrome extension ID and registered host path.
  6. Restart Chrome, open Browser Control, and choose Sign in with ChatGPT.

The installer copies the host into ~/Library/Application Support/Browser Control/ and registers com.codex.sidebar with Chrome. It does not install an unrelated app, browser extension, analytics service, or background login item.

Update the companion

Download the newer companion from the same Releases page, verify its checksum, and run its installer again. Installation is idempotent and replaces only Browser Control companion files. The side panel reports an actionable error when its companion protocol is incompatible.

Troubleshooting

“Native host not found”

Install or reinstall the companion, confirm the installer reports success, fully quit and reopen the browser, and run node scripts/smoke-installed-host.mjs from the extracted release. A companion built for a different Store extension ID will be refused.

“Codex not found”

Run codex --version in Terminal. Install or repair Codex CLI, then reinstall the companion so it records the correct executable.

Sign-in does not finish

Keep the sign-in tab open until the Codex callback completes, then return to the side panel. If necessary, cancel and retry. Browser Control never reads ChatGPT cookies.

A site asks for access

Ask every time requests the exact site when needed. Full access requests optional normal-web access once from a sidebar gesture. You can revoke either choice from Browser Control settings or Chrome's extension site controls.

Codex cannot find a visible control

Page inspection returns at most 80 visible controls. Re-inspect after the page settles. Protected pages, cross-origin frames, browser dialogs, closed shadow roots, and canvas-only controls are unsupported.

Clear or delete data

Clear browser data and permissions

In Browser Control settings, choose Clear browser data and permissions. This removes Chrome-side transcripts, activity, preferences, temporary task state, and retained site grants. It keeps the dedicated Codex login and persistent Codex threads on the Mac.

Delete all Browser Control data and sign out

Choose Delete all Browser Control data and sign out and confirm the warning. Browser Control stops active work, clears Chrome-side data and permissions, signs out, and removes its dedicated ~/.codex-sidebar data. The companion stays installed so the extension can be used again later.

Manual deletion

If the extension is unavailable, first quit Chrome. Remove the dedicated ~/.codex-sidebar directory to delete Browser Control's Codex session and thread data. Take care not to remove the separate ~/.codex directory used by other Codex installations.

Uninstall the companion

  1. Use the in-product full deletion option if you also want to remove Browser Control data and sign out.
  2. Run node scripts/uninstall-native-host.mjs from the downloaded companion release.
  3. Remove Browser Control from Chrome.

The uninstaller removes the native-host registration and companion runtime. It does not delete the separate Codex data directory unless that destructive option is explicitly selected.