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
Что это такое?Загрузчик твиков для десктопного приложения OpenAI Codex: он патчит вашу локальную установку Codex так, чтобы при запуске подгружалась небольшая среда Codex++ и выполняла локальные твики, которые могут менять интерфейс, добавлять страницы настроек и запускать код в main-процессе.
Codex++ — это отдельное приложение или оно изменяет мой уже установленный Codex?Оно изменяет уже установленное приложение: Codex++ патчит файл app.asar приложения Codex, чтобы загрузчик Codex++ запускался первым, а ваши твики, настройки, логи и резервные копии хранятся в отдельной пользовательской папке. Codex он не заменяет и ваш аккаунт не проксирует.
Как установить Codex++?Через Homebrew, установщик из исходников на GitHub, Windows PowerShell или Bun — либо попросите кодинг-агента установить его из Codex. После установки просто запустите Codex как обычно и найдите раздел Codex++ в настройках.
Что будет с моими твиками, когда Codex обновится?Обновление Codex обычно затирает патч, но Codex++ устанавливает наблюдателя, который это замечает и автоматически накладывает патч заново. Если это не сработало, команда codexplusplus repair накладывает патч вручную.
Насколько глубоко тик может залезть в систему?На macOS — очень глубоко: твики с нативным мостом могут поставлять собственные модули .node и использовать обёртки Objective-C++/N-API для Swift, AppKit, Metal и MetalKit, а также нативные дочерние панели, оверлеи на базе Metal и вспомогательные процессы.
Безопасно ли ставить твики из случайных источников?Относитесь к твикам как к любому локальному коду, который вы запускаете внутри приложения: README предупреждает, что ставить их можно только из источников, которым вы доверяете, нативные твики требуют дополнительной проверки, а Codex++ никогда не обновляет файлы твиков молча — проверки обновлений просто дают ссылку на GitHub Releases.
Codex++ сделан OpenAI?Нет. В README сказано, что это неофициальный проект, не связанный с OpenAI, и вы используете его на свой страх и риск.
Зачем нужен режим browser host?Он открывает React-интерфейс Codex в обычной вкладке браузера, пока скрытое окно Codex обеспечивает приватный мост приложения — удобно для отладки и браузерной автоматизации. Режим экспериментальный, и некоторые сайты могут блокировать встраивание из-за iframe-шим.
Codex только что обновился и твики сломались — как отлаживать или откатиться?Команда codexplusplus doctor диагностирует подписи, целостность, права доступа и типичные сбои, debug выводит пути приложения и состояние моста, а safe-mode отключает все твики без их удаления, пока вы не выполните safe-mode --off.
Что такое Owl, который упоминается для macOS?Нативная оболочка приложения в актуальных сборках Codex для macOS — Chromium плюс совместимый с Electron JavaScript-рантайм. Codex++ 1.0.0 определяет Owl, а авторам твиков стоит использовать SDK Codex++ (api.codex.*) вместо прямого обращения к внутренностям Owl.
What are similar projects?evenfire, rea, nylas-mail, bb, dsh-market, codex-security, penguin-harness, gitagent
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