| name | codex-chrome-linux |
| description | Inspect, instrument, and control Linux Google Chrome through the local Codex Chrome Extension native messaging bridge. Use when Codex needs Chrome tabs, history, navigation, Chrome DevTools Protocol commands, native host manifest/socket troubleshooting, or a Linux browser-control path instead of Chrome DevTools MCP. |
Codex Chrome Linux
Use codex-linux-extension-host as the only interface to the Codex Chrome
Extension bridge. It talks to the Chrome native messaging host over a local
Unix socket and returns JSON for Codex turns.
Read references/protocol.md when setup, method names, fixed paths, or
troubleshooting details matter.
Workflow
- Verify the CLI and bridge health:
HOST_BIN="$(command -v codex-linux-extension-host || printf '%s' "$HOME/.local/bin/codex-linux-extension-host")"
"$HOST_BIN" --json doctor
- If
manifest-json, manifest-origin, or manifest-host-path is false,
install the Chrome native messaging manifest, then restart or trigger Chrome:
HOST_BIN="$(command -v codex-linux-extension-host || printf '%s' "$HOME/.local/bin/codex-linux-extension-host")"
"$HOST_BIN" --json install-manifest --host-path "$HOST_BIN"
- Confirm the Codex Chrome Extension is installed and enabled. Extension ID:
hehggadaopoacecdllhhajmbjkdcmajg. Web Store URL:
https://chromewebstore.google.com/detail/codex/hehggadaopoacecdllhhajmbjkdcmajg
- Use stable IDs for operations that touch tabs:
export CODEX_CHROME_SESSION_ID="codex-linux"
export CODEX_CHROME_TURN_ID="manual"
- Prefer read-only probes first:
codex-linux-extension-host --json info
codex-linux-extension-host --json profiles --include-tabs
codex-linux-extension-host --json tabs
codex-linux-extension-host --json history --limit 10
When multiple Chrome profiles may have the Codex extension enabled, run
profiles first and pass --profile <selector> to later commands. The
selector may be default, a bridge PID, a socket basename, or an
extensionInstanceId/prefix from profiles.
Before opening a URL, look for an existing tab to reuse. navigate <url>
without --tab-id creates a new session tab and can create a new Codex tab
group. If a suitable tab already exists, use navigate <url> --tab-id <id>.
If the tab is visible but not yet in the session, claim it first with
claim-tab --tab-id <id>.
-
Use browser-control commands only when requested: create-tab,
claim-tab, navigate, attach, cdp, detach, name-session,
finalize-tabs, and turn-ended.
-
Finalize session tabs after browser work, keeping only deliverable or
handoff tabs. Use handoff for tabs that future turns should reuse; use
deliverable only for tabs that should remain for user inspection but do
not need browser-session reuse. Then release controls for the turn:
codex-linux-extension-host --json finalize-tabs --session codex-manual --turn nav --keep 123:handoff
codex-linux-extension-host --json turn-ended --session codex-manual --turn nav
Examples
List tabs:
codex-linux-extension-host --json tabs --session codex-manual --turn inspect
codex-linux-extension-host --json tabs --profile default --session codex-manual --turn inspect
Reuse an existing tab when navigating:
codex-linux-extension-host --json claim-tab --tab-id 123 --session codex-manual --turn nav
codex-linux-extension-host --json navigate https://example.com --tab-id 123 --session codex-manual --turn nav
Create a new tab only when there is no suitable tab to reuse:
codex-linux-extension-host --json navigate https://example.com --session codex-manual --turn nav
Finalize the session, keeping a tab for handoff:
codex-linux-extension-host --json finalize-tabs --session codex-manual --turn nav --keep 123:handoff
codex-linux-extension-host --json turn-ended --session codex-manual --turn nav
Evaluate JavaScript after claiming, creating, or navigating a tab:
codex-linux-extension-host --json cdp --tab-id 123 Runtime.evaluate --params '{"expression":"document.title","returnByValue":true}' --session codex-manual --turn inspect
Construct CDP parameters safely
Do not hand-embed nontrivial JavaScript inside shell-quoted --params JSON.
Selectors and scripts commonly contain single quotes, dollar signs, backticks,
or newlines that the shell can reinterpret before the CLI receives them.
When orchestrating through functions.exec, serialize the parameter object and
shell-quote the completed JSON value:
const expression = `document.querySelector(
"button[aria-label^='Time range selected:']"
)?.click()`;
const params = JSON.stringify({ expression, returnByValue: true });
const shellQuote = (value) =>
"'" + value.replaceAll("'", "'\\''") + "'";
const result = await tools.exec_command({
cmd: `codex-linux-extension-host --json cdp --tab-id 123 Runtime.evaluate --params ${shellQuote(params)} --session codex-manual --turn inspect`,
});
text(result);
Use the short inline --params '{...}' form only for simple expressions that
contain no conflicting shell syntax. If the CLI prints its own usage followed
by unexpected argument '<word>', and that word came from the JavaScript, treat
it as shell tokenization rather than a missing CDP feature. Rebuild the command
with programmatic JSON serialization and quoting.
Safety
Do not inspect cookies, passwords, local storage, or arbitrary Chrome profile
files. Do not run raw CDP commands against logged-in sites unless the user asks
for that browser action. Do not change the native messaging manifest to allow
another extension ID without explicit approval.
