codex-plusplus README

The project's README from github.com/b-nnett/codex-plusplus. As one markdown file: README.md.

Codex++

Codex++ lets you install local tweaks into the OpenAI Codex desktop app. Tweaks can change UI, add settings pages, run main-process code, and use native OS-level features through the Codex++ bridge. Join the Discord community.

Codex++ settings screenshot

Unofficial project. Not affiliated with OpenAI. Use at your own risk.

TL;DR

Codex++ patches your local Codex app so Codex loads a small Codex++ runtime on startup.

That runtime lives in your user data directory, not inside Codex. It finds tweaks in a local tweaks/ folder and loads them when Codex opens.

The app patch is tiny. Your tweaks, config, logs, backups, and runtime files stay outside the app bundle, so you can edit tweaks without rebuilding Codex.

When Codex updates, the patch is usually removed. Codex++ installs a watcher that notices this and re-applies the patch.

1.0.0 adds cleaner patching, better debug output, Owl runtime detection, browser-host debugging, and native bridge support for AppKit, Metal, helper processes, and tweak-owned native modules.

Table Of Contents

Install

Agentic install, from Codex:

Inspect and install this for me: https://github.com/b-nnett/codex-plusplus
Tell me where you install it and send me the local path for adding new tweaks.

Homebrew:

brew install b-nnett/codex-plusplus/codexplusplus
codexplusplus install

GitHub source installer:

curl -fsSL https://raw.githubusercontent.com/b-nnett/codex-plusplus/main/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/b-nnett/codex-plusplus/main/install.ps1 | iex

Bun:

bun install -g github:b-nnett/codex-plusplus
codexplusplus install

After install, launch Codex normally. Open Settings and look for the Codex++ section.

What Codex++ Is

Codex++ is a tweak loader for Codex Desktop.

It gives you:

It does not replace Codex, proxy your account, or run a separate Codex clone. It modifies your installed app so it can load local code.

How It Works

Install flow:

  1. Codex++ finds your Codex app.
  2. It backs up the unpatched app files.
  3. It patches Codex app.asar so a Codex++ loader runs first.
  4. It stages the Codex++ runtime in your user data directory.
  5. It re-signs the app when needed.
  6. It installs a watcher for future Codex updates.

Runtime flow:

  1. You launch Codex.
  2. The Codex++ loader starts.
  3. The loader starts the Codex++ runtime from disk.
  4. Codex starts normally.
  5. Codex++ discovers enabled tweaks.
  6. Renderer tweaks run in Codex windows.
  7. Main-process tweaks run in the Codex main process.
  8. The Settings UI shows Codex++ pages and tweak controls.

Common Commands

Command What it does
codexplusplus install Patch Codex and install the runtime.
codexplusplus status Show installed version and patch state.
codexplusplus debug Show app path, runtime type, paths, open state, and bridge status.
codexplusplus repair Re-apply the patch after an app update or broken install.
codexplusplus update Update Codex++ from the latest GitHub release.
codexplusplus update-codex Prepare Codex for its official updater, then re-patch after restart.
codexplusplus doctor Diagnose signatures, integrity, permissions, and common failures.
codexplusplus safe-mode Disable all tweaks without deleting them.
codexplusplus safe-mode --off Leave safe mode.
codexplusplus uninstall Remove Codex++ and restore the app when safe.
codexplusplus uninstall --purge Also delete tweaks, config, logs, backups, and Codex++ user data.

Tweak development commands:

Command What it does
codexplusplus create-tweak ./my-tweak Create a new tweak folder.
codexplusplus validate-tweak ./my-tweak Validate a tweak manifest and entry file.
codexplusplus dev ./my-tweak Link a local tweak into Codex++ for development.

Source checkout commands:

npm run build
npm test
node packages/installer/dist/cli.js install
node packages/installer/dist/cli.js debug

Where Files Live

Codex++ keeps almost everything outside Codex.

Item Location
Loader patch Inside Codex app.asar
Runtime <user-data-dir>/runtime/
Tweaks <user-data-dir>/tweaks/
Tweak data <user-data-dir>/tweak-data/
Config <user-data-dir>/config.json
State <user-data-dir>/state.json
Logs <user-data-dir>/log/
Backups <user-data-dir>/backup/

Default user data paths:

OS Path
macOS ~/Library/Application Support/codex-plusplus/
Windows %APPDATA%/codex-plusplus/
Linux $XDG_DATA_HOME/codex-plusplus/ or ~/.local/share/codex-plusplus/

On Windows Store installs, Codex++ also creates a writable managed app copy under %LOCALAPPDATA%/codex-plusplus/store-apps/. Use the Codex++ shortcut for that copy.

Writing Tweaks

A tweak is a folder with a manifest and an entry file:

my-tweak/
  manifest.json
  index.js

Minimal manifest.json:

{
  "id": "com.you.my-tweak",
  "name": "My Tweak",
  "version": "0.1.0",
  "githubRepo": "you/my-tweak",
  "description": "Adds a Codex++ settings page.",
  "scope": "renderer",
  "main": "index.js"
}

Minimal index.js:

module.exports = {
  start(api) {
    api.settings.registerPage({
      id: "main",
      title: api.manifest.name,
      render(root) {
        root.textContent = "Hello from Codex++.";
      },
    });
  },
  stop() {},
};

Local dev loop:

codexplusplus create-tweak ./my-tweak --id com.you.my-tweak --name "My Tweak"
codexplusplus validate-tweak ./my-tweak
codexplusplus dev ./my-tweak

Full docs are in Writing Tweaks.

Owl And Native Bridge

Current macOS Codex builds use Owl: a native app shell with Chromium and an Electron-compatible JavaScript runtime.

Codex++ 1.0.0 detects Owl and reports capability status through:

codexplusplus debug

Tweak authors should use the Codex++ SDK, not raw Owl internals:

Native bridge support includes:

Start with Native Bridge.

Browser Host Mode

Browser host mode opens the Codex React UI in a normal browser tab while a hidden Codex window provides the private app bridge:

codexplusplus browser --port 8765

Then open:

http://127.0.0.1:8765/

This is useful for debugging and browser automation. It is experimental. The in-app browser uses iframe shims in this mode, so some websites may block embedding.

Updates And Recovery

Update Codex++:

codexplusplus update

Run the official Codex updater on macOS:

codexplusplus update-codex

Repair Codex++:

codexplusplus repair --force

Disable tweaks temporarily:

codexplusplus safe-mode

Re-enable normal tweak loading:

codexplusplus safe-mode --off

Uninstall:

codexplusplus uninstall

Clean uninstall, including tweaks/config/logs/backups:

codexplusplus uninstall --purge

Security

Codex++ runs local code inside your Codex desktop app. Install tweaks only from sources you trust.

Important details:

See Security.

More Docs

Contributors

License

MIT.

codex-plusplus (b-nnett/codex-plusplus)

Searching Database…

3.8K ·GitHub
Codex-plusplus
What is this?A tweak loader for the OpenAI Codex desktop app: it patches your local Codex install so a small Codex++ runtime loads on startup and runs local tweaks that can change the UI, add settings pages, and run main-process code.
Is Codex++ a separate app, or does it modify the Codex I already have?It modifies the app you already have: it patches Codex's app.asar so the Codex++ loader runs first, while your tweaks, config, logs and backups stay in a separate user data folder. It doesn't replace Codex or proxy your account.
How do I install Codex++?Via Homebrew, a GitHub source installer, Windows PowerShell, or Bun — or have a coding agent install it from Codex. After installing, just launch Codex normally and look for the Codex++ section in Settings.
What happens to my tweaks when Codex updates itself?A Codex update usually wipes the patch, but Codex++ installs a watcher that notices and re-applies it automatically. If that fails, codexplusplus repair re-applies the patch by hand.
How deep into the OS can a tweak go?Far, on macOS: native-bridge tweaks can ship their own .node modules and use Objective-C++/N-API shims for Swift, AppKit, Metal and MetalKit, plus native child panels, Metal-backed overlays and helper processes.
Is it safe to install tweaks from random sources?Treat tweaks like any local code you run inside your app: the README warns to install only from sources you trust, native tweaks need extra review, and Codex++ never silently updates tweak files — update checks just link to GitHub Releases.
Is Codex++ made by OpenAI?No. The README states it is an unofficial project, not affiliated with OpenAI, and you use it at your own risk.
What is browser host mode for?It opens the Codex React UI in a normal browser tab while a hidden Codex window provides the private app bridge — useful for debugging and browser automation. It is experimental, and some sites may block embedding due to iframe shims.
Codex just updated and tweaks broke — how do I debug or bail out?codexplusplus doctor diagnoses signatures, integrity, permissions and common failures, debug prints app paths and bridge status, and safe-mode disables all tweaks without deleting them until you run safe-mode --off.
What is Owl, which comes up for macOS?The native app shell in current macOS Codex builds — Chromium plus an Electron-compatible JavaScript runtime. Codex++ 1.0.0 detects Owl, and tweak authors should use the Codex++ SDK (api.codex.*) rather than raw Owl internals.
What are similar projects?evenfire, rea, nylas-mail, bb, dsh-market, codex-security, gitagent, deno
Which topics is it in?modding, plugin-system, homebrew, electron, customization, sdk, openai, codex, security, npm, desktop-app, tool
Creator
b-nnett
Size
89.8 MB
Stars
3.8K
Updated
CommitOct 15Releasev2.0.0Oct 14
Age
5mo
Commits · 90 Days