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.
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:
- A local
tweaks/ folder.
- A runtime that loads renderer and main-process tweaks.
- A Codex++ Settings section inside Codex.
- CLI tools for install, repair, update, debug, and tweak development.
- A watcher that repairs Codex++ after Codex updates.
- A public SDK for tweak authors.
- Native bridge APIs for advanced macOS tweaks.
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:
- Codex++ finds your Codex app.
- It backs up the unpatched app files.
- It patches Codex
app.asar so a Codex++ loader runs first.
- It stages the Codex++ runtime in your user data directory.
- It re-signs the app when needed.
- It installs a watcher for future Codex updates.
Runtime flow:
- You launch Codex.
- The Codex++ loader starts.
- The loader starts the Codex++ runtime from disk.
- Codex starts normally.
- Codex++ discovers enabled tweaks.
- Renderer tweaks run in Codex windows.
- Main-process tweaks run in the Codex main process.
- 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:
api.codex.runtime.getInfo()api.codex.runtime.getCapabilities()api.codex.windows.*api.codex.cdp.*api.codex.native.*
Native bridge support includes:
- Tweak-owned
.node modules.
- Objective-C++/N-API shims for Swift, AppKit, Metal, and MetalKit.
- Native child panels.
- Metal-backed child-window overlays.
- Helper processes.
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:
- Codex++ does not silently update tweak files.
- Tweak update checks link to GitHub Releases for review.
- Native tweaks can run native code and need extra review.
- Native bridge paths are restricted to files inside the tweak directory.
- Tweak data APIs default to Codex++'s user data directory.
See Security.
More Docs
Contributors
License
MIT.
一个针对 OpenAI Codex 桌面应用的扩展加载器：它会修改你本地的 Codex 安装，让一个小型的 Codex++ 运行时在启动时加载，并运行本地的 tweak（扩展插件），这些 tweak 可以改变界面、添加设置页面，以及运行主进程代码。