# Chromex puts Codex in a Chrome side panel without putting your keys in Chrome > A Manifest V3 side panel extension that reaches a local Codex app-server over Chrome Native Messaging, with a four package monorepo and a version floor on the Codex CLI that matters more than it sounds. **GENEXIS-AI/chromex** — A Codex-powered Chrome side-panel assistant for page context, tabs, voice, and image workflows. - Repository: https://github.com/GENEXIS-AI/chromex - Stars: 1,148 · Forks: 114 - Language: TypeScript - License: MIT - Published: 2026-10-06 · Updated: 2026-10-06 · Language: en - Canonical page: https://hysenlabs.com/projects/genexis-ai-chromex ## A side panel that cannot work without a process on your machine Chromex is a Chrome MV3 side panel assistant that connects Chrome to Codex through a local native bridge. The repository description says it helps with page context, tabs, voice, and image workflows, and the feature list in the README backs that up: chat against the current webpage, selected tabs, screenshots, uploaded files, PDFs, Office documents, images, and browser history, then summarize and compare page content, YouTube videos, news articles, research pages, PDFs, and arXiv papers. The interesting part is not the feature list, it is the boundary. The README draws the whole system in one line: ```text Chrome Extension -> Native Messaging Host -> Local Bridge -> codex app-server ``` A Manifest V3 extension cannot hold a long lived process and cannot quietly start one. So the right-hand end of that chain, the Codex app-server, has to be a program running on your machine, and something has to launch it. Chrome offers exactly one sanctioned path for that, Native Messaging, and Native Messaging requires a host manifest registered with the browser rather than something the extension can install on its own. The README is blunt about this: the Store extension can run only after a one-time local bridge registration, and the extension itself cannot install that local host automatically. That single sentence explains most of the troubleshooting documentation in the repository. When the side panel says the bridge is waiting, the problem is registration, not the model. ## Four packages, each with a job that does not overlap The source tree is organised as an npm workspace over `packages/*`, with the root package named chromex at version 0.1.8, `"type": "module"`, and MIT licensing. The four workspace packages map onto the runtime boundary in order: `packages/extension` is the Chrome MV3 side panel extension. `packages/bridge` is the local bridge daemon that owns the Codex app-server and multimodal workflows. `packages/native-host` is the Chrome Native Messaging relay, the piece Chrome actually launches. `packages/shared` holds shared types, policies, profiles, and helpers. That division is visible in the build script, which does not run in parallel. It builds shared first, then bridge, then native-host, then extension, because each package consumes the previous one. The test script mirrors the same ordering behind a `prepare:workspace` step, and typecheck does the same across bridge, native-host, and extension. If you are looking for a place to understand the dependency direction, `tsconfig.base.json` at the root and the build chain in package.json tell you more than the directory listing does. The rest of the root is ordinary and useful: `docs/`, `RELEASE.md`, `SECURITY.md`, `PRIVACY.md`, `assets/`, and a `scripts/` directory holding the installer, the smoke test, the packaging scripts, and two locale generators named `generate-extension-locales.mjs` and `generate-sidepanel-i18n-translations.mjs`. ## Two install paths, and the one that avoids a compiler Chrome Web Store users do not need to build Chromex from source. The README points them at a public setup page with copy buttons in four languages, then to `chromex-local-bridge.zip` from the latest GitHub Release. Unzipping that archive and running one command registers the host: ```bash npm install -g @openai/codex codex --version ``` ```bash node scripts/install-native-host.mjs --browser=chrome ``` The source path is the one you want if you intend to read or change the code, and it is five commands: ```bash git clone https://github.com/GENEXIS-AI/chromex.git cd chromex npm install npm run build node scripts/install-native-host.mjs ``` Either way you finish the same way: fully quit every Chrome window, reopen Chrome, then press `Check connection` in Chromex. A full quit matters because Chrome caches host registration per running instance, and the README repeats the instruction in both paths. Then `chrome://extensions`, enable `Developer mode`, choose `Load unpacked`, and point at: ```text packages/extension/dist ``` There is one filesystem trap worth naming, because the README calls it out and Windows users hit it constantly. The install, build, and installer commands have to run from the chromex folder that contains package.json. If Windows reports `ENOENT Could not read package.json`, you are in the wrong directory, not looking at a broken dependency tree. ## The Codex CLI version floor is the first real failure Chromex requires `@openai/codex` 0.130.0 or newer. This was documented in every README locale as of the v0.1.7 release, which suggests several people found out the hard way first. Older releases, the README names 0.124.x and 0.125.x, refuse some bootstrap feature flags, and the symptom is confusing: `codex app-server exited with code 1` immediately after a login that plainly succeeded. The Windows section is the most detailed part of the install docs, and most of it is about things that are not Chromex's fault. It says to install Node.js 20 LTS or newer, then use the npm install path even if `winget install Codex -s msstore` fails, because `0x8a15005e: The server certificate did not match any of the expected values` is a Windows Store and TLS certificate chain problem outside the extension. That distinction is genuinely useful, since searching that error code lands you in Store forum threads rather than Chromex issues. The rest covers executable discovery. If login fails with `Failed to start codex app-server`, Chromex reached the bridge but could not start the CLI, so the fix is to re-run `codex --version` and, if Windows cannot find it, set the optional Codex binary path to `%APPDATA%\npm\codex.cmd` or the folder to `%APPDATA%\npm`. The README warns specifically against pasting a workspace folder into that field, because the workspace and the executable path are separate settings. To force detection, `where codex` is the command that tells you what to paste: ```powershell npm install -g @openai/codex where codex codex --version ``` If Chrome displays an extension ID other than the expected public release ID `menmlhahmendmkiicbjihgjhppkgaeom`, re-run the installer with the ID Chrome shows, because the host manifest is bound to the extension ID that will call it. ## Three releases in six weeks, all of them startup failures The release history is short and unusually focused. Every entry since v0.1.6 deals with something failing at launch rather than a missing feature. v0.1.6, published 2026-05-08, added GitHub Release artifacts so Store users can grab a prebuilt bridge instead of compiling, and added a public step-by-step Store install guide. It also fixed model catalog fallback behaviour around API key sessions and preserved realtime interpreter settings during live transcript updates. v0.1.7, published 2026-05-09, is a one day later and reads like the follow-up patch: it added a General setting to disable the page image hover button, documented the 0.130.0 Codex CLI floor, and rebuilt the local bridge with a CommonJS compatible bundled launcher and an `import.meta` URL fallback. The bug it names is `Dynamic require of fs is not supported`, which is a packaging problem that only shows up when a CommonJS require lands in an ESM context. Validation for that release notes green GitHub Actions checks on macOS, Ubuntu, and Windows. v0.1.8, published 2026-06-15, fixes the local bridge startup crash reported as issue #21, where the native host could exit immediately with missing `@napi-rs/canvas` and `DOMMatrix` errors. The fix is lazy: `pdf-parse` now loads only during PDF text extraction, and the runtime installs minimal non-rendering `DOMMatrix`, `ImageData`, and `Path2D` globals when the host does not provide them. That release also switched the extension smoke test to the installed playwright-core CLI locally and Chrome for Testing in CI, and it publishes SHA256 digests for both `chromex-local-bridge.zip` and `chromex-public-source.zip`. The pattern across all three is that the hard part is not the agent. It is getting a Node daemon to start correctly under a browser supervisor on three operating systems. ## Keeping credentials out of extension storage The privacy defaults are the reason to care about this project even if you never install it. The extension does not store raw OpenAI API keys, OAuth tokens, or ChatGPT session tokens in Chrome extension storage. Codex OAuth and ChatGPT login is handled through the local Codex app-server flow, where the credential stays in the CLI's own login state on your machine. API key login exists as an optional local fallback and is never used automatically without user consent. This is why the native bridge is not optional plumbing. If the extension held the credential, it would need nothing but itself. Because it does not, it needs a registered local process, and that process is the thing that already knows how to authenticate. Localisation is handled with the same restraint. The extension follows the browser language automatically by default, and users can override it under `Settings > General > App UI language`. Chrome `_locales` entries ship for English, Korean, Japanese, Chinese, Arabic, French, German, Spanish, Portuguese, Hindi, Vietnamese, Thai, Turkish, Ukrainian, and many other Chrome compatible locales. Model responses are instructed to follow the selected UI language unless asked for another. The README itself is mirrored into `readmes/` as README.ko.md, README.ja.md, and README.zh-CN.md, which is a reasonable signal of who the audience is. On the feature side, two capabilities go beyond chat and are worth naming separately. The unified Translation/Live mode captures live transcripts with optional realtime translation and then lets you chat about the captured transcript. Browser control runs through Chrome content scripts and draws visible in-page activity indicators, so the user can see when automation is touching the page rather than guessing. ## Conclusion Chromex is most useful to someone who already lives in the Codex CLI and wants that same agent to see the page in front of them without leaving the browser, and least useful as a standalone chat client. The architecture makes the tradeoff explicit: the extension holds no credentials, so it needs a local bridge registered on the machine, so the setup has a moving part that no extension install can remove. The four packages divide the work cleanly, shared types first, then bridge, native host, and extension last, which is why `npm run build` is a chain rather than a single command. The last three releases between 2026-05-08 and 2026-06-15 all chased startup failures on Windows and macOS, so treat `npm run build` followed by `install-native-host.mjs` from the folder holding package.json as the path that the project itself has been debugging. With 1148 stars, 114 forks, 3 open issues, and a last push on 2026-06-15, this is an active line of work rather than an experiment, and the installed extension ID for the public build is `menmlhahmendmkiicbjihgjhppkgaeom`. ## FAQ ### What is Chromex and how does it connect to Codex? Chromex is a Chrome Manifest V3 side panel extension that reaches a local Codex app-server through Chrome Native Messaging. The chain runs from the extension to a native messaging host, into a local bridge daemon, and finally to the codex app-server on the machine. ### Why does Chromex need a local bridge installed separately? A Manifest V3 extension cannot launch a long lived process, so the Codex app-server has to run on your machine and be registered through Native Messaging. An extension cannot install that host automatically, which is why the one-time registration step is required before the side panel works. ### Which version of the Codex CLI does Chromex require? Chromex documents `@openai/codex` 0.130.0 or newer as the requirement. Older releases such as 0.124.x and 0.125.x refuse some bootstrap feature flags and fail with `codex app-server exited with code 1` right after a successful login. ### Does the Chromex extension store OpenAI API keys or ChatGPT tokens? No. The extension keeps no raw OpenAI API keys, OAuth tokens, or ChatGPT session tokens in Chrome extension storage. OAuth and ChatGPT login are handled by the local Codex app-server, and API key login is an optional local fallback that requires explicit user consent. ### How do you build and load Chromex from source? Clone the repository, run npm install and npm run build, then run node scripts/install-native-host.mjs from the folder containing package.json. Quit Chrome fully, reopen it, enable Developer mode at chrome://extensions, and use Load unpacked pointed at packages/extension/dist. ## Sources - [GENEXIS-AI/chromex on GitHub](https://github.com/GENEXIS-AI/chromex) - [Issues](https://github.com/GENEXIS-AI/chromex/issues) - [License: MIT](https://github.com/GENEXIS-AI/chromex/blob/main/LICENSE) - [README](https://github.com/GENEXIS-AI/chromex/blob/main/README.md) - [Releases](https://github.com/GENEXIS-AI/chromex/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/genexis-ai-chromex