codex-plusplus-tweak-system

# codex-plusplus Tweak System > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. `codex-plusplus` is a tweak injection system for the [Codex](https://chatgpt.com/codex) desktop app (Electron-based). It patches `app.asar`, injects a loader stub, and runs a hot-reloadable runtime from the user directory. Tweaks are small ESM modules with a manifest and `start/stop` lifecycle — no app rebuild required. --- ## Installation ### Homebrew (macOS, recommended) ```sh brew install b-nnett/codex-plusplus/codexplusplus codexplusplus install ``` ### Bun (global) ```sh bun install -g github:b-nnett/codex-plusplus codexplusplus install ``` ### Source bootstrap (macOS / Linux) ```sh curl -fsSL https://raw.githubusercontent.com/b-nnett/codex-plusplus/main/install.sh | bash ``` ### Windows PowerShell ```powershell irm https://raw.githubusercontent.com/b-nnett/codex-plusplus/main/install.ps1 | iex ``` The installer: 1. Locates `Codex.app` (or Windows equivalent) 2. Backs up the original to `~/.codex-plusplus/backup/` 3. Patches `app.asar` to require the loader 4. Recomputes asar header SHA-256, writes it into `Info.plist` 5. Flips `EnableEmbeddedAsarIntegrityValidation` in the Electron Framework binary 6. Re-signs ad-hoc on macOS (`codesign --force --deep --sign -`) 7. Installs a launch agent / login item for auto-repair on Codex updates 8. Installs default tweaks unless `--no-default-tweaks` is passed --- ## Key CLI Commands ```sh codexplusplus install # Patch Codex and install runtime codexplusplus install --no-default-tweaks # Skip default tweak set codexplusplus status # Show patch status and runtime version codexplusplus doctor # Diagnose issues (integrity, signing, etc.) codexplusplus repair # Re-apply patch (e.g. after Codex update) codexplusplus repair --quiet # Silent repair (used by watcher/launch agent) codexplusplus update # Pull latest codex-plusplus source, rebuild, repair codexplusplus update-codex # Restore official-signed Codex for Sparkle updater codexplusplus uninstall # Revert all patches, restore backup codexplusplus tweaks list # List installed tweaks and enabled state codexplusplus tweaks open # Open user tweaks directory in Finder/Explorer ``` --- ## File Locations | Artifact | Path | |---|---| | Loader stub | `Codex.app/Contents/Resources/app.asar` | | Runtime | `<user-data-dir>/runtime/` | | Tweaks | `<user-data-dir>/tweaks/` | | Config | `<user-data-dir>/config.json` | | Backup | `<user-data-dir>/backup/` | **`<user-data-dir>` per OS:** - macOS: `~/Library/Application Support/codex-plusplus/` - Linux: `$XDG_DATA_HOME/codex-plusplus/` (default `~/.local/share/codex-plusplus/`) - Windows: `%APPDATA%/codex-plusplus/` --- ## Writing a Tweak ### Folder Structure ``` <user-data-dir>/tweaks/my-tweak/ ├── manifest.json └── index.ts # or .js / .mjs ``` ### manifest.json ```json { "id": "com.yourname.my-tweak", "name": "My Tweak", "version": "0.1.0", "githubRepo": "yourname/my-tweak", "author": "yourname", "description": "Short description of what this tweak does.", "minRuntime": "0.1.0" } ``` **Required fields:** `id` (reverse-domain), `name`, `version`, `githubRepo` (for update checks), `author`, `description`, `minRuntime`. ### index.ts — Minimal Tweak ```ts import type { Tweak } from "@codex-plusplus/sdk"; export default { start(api) { api.log.info("My tweak started"); }, stop() { // Cleanup: remove event listeners, DOM nodes, etc. }, } satisfies Tweak; ``` ### index.ts — Settings Panel ```ts import type { Tweak } from "@codex-plusplus/sdk"; export default { start(api) { api.settings.register({ id: "my-tweak", title: "My Tweak", render(root) { root.innerHTML = ` <div style="padding: 16px;"> <h2>My Tweak Settings</h2> <label> <input type="checkbox" id="my-tweak-toggle" /> Enable feature </label> </div> `; const toggle = root.querySelector<HTMLInputElement>("#my-tweak-toggle")!; toggle.checked = api.storage.get("enabled") ?? false; toggle.addEventListener("change", () => { api.storage.set("enabled", toggle.checked); }); }, }); }, stop() {}, } satisfies Tweak; ``` ### index.ts — DOM Injection with Cleanup ```ts import type { Tweak } from "@codex-plusplus/sdk"; let cleanup: (() => void) | null = null; export default { start(api) { // Wait for DOM element to appear const unobserve = api.dom.waitFor(".codex-toolbar", (toolbar) => { const btn = document.createElement("button"); btn.textContent = "My Action"; btn.className = "codex-plusplus-btn"; btn.addEventListener("click", () => { api.log.info("Button clicked"); }); toolbar.appendChild(btn); cleanup = () => btn.remove(); }); api.onStop(() => { unobserve(); cleanup?.(); }); }, stop() {}, } satisfies Tweak; ``` ### index.ts — Keyboard Shortcut ```ts import type { Tweak } from "@codex-plusplus/sdk"; export default { start(api) { const handler = (e: KeyboardEvent) => { if ((e.metaKey || e.ctrlKey) && e.shiftKey && e.key === "k") { e.preventDefault(); api.log.info("Shortcut triggered: Cmd/Ctrl+Shift+K"); // your action here } }; document.addEventListener("keydown", handler); api.onStop(() => document.removeEventListener("keydown", handler)); }, stop() {}, } satisfies Tweak; ``` --- ## Tweak API Reference (`api` object in `start`) | API | Description | |---|---| | `api.log.info(msg)` | Log to Codex++ console | | `api.log.warn(msg)` | Warning log | | `api.log.error(msg)` | Error log | | `api.settings.register({ id, title, render })` | Add a panel under Settings → Tweaks | | `api.storage.get(key)` | Read persisted value for this tweak | | `api.storage.set(key, value)` | Persist value (JSON-serializable) | | `api.dom.waitFor(selector, cb)` | Watch for a DOM element; returns unobserve fn | | `api.onStop(fn)` | Register a cleanup callback called on `stop()` | --- ## Config (`config.json`) ```json { "autoRepair": true, "autoUpdateRuntime": true, "tweaks": { "com.yourname.my-tweak": { "enabled": true } } } ``` - **`autoRepair`** — watcher re-patches after Codex updates (default `true`) - **`autoUpdateRuntime`** — daily runtime refresh from CLI (default `true`); disable in Settings → Codex Plus Plus → Config --- ## Tweak Update Checks Every tweak with `githubRepo` set is checked against GitHub Releases once per day. Codex++ compares the latest release tag (semver) to the local `manifest.json` version. - **No auto-update** — users see "Update Available" in Settings → Tweaks with a link to the release. - To publish a tweak update: create a GitHub Release with a semver tag (e.g. `v0.2.0`) and attach the tweak folder as a zip. --- ## Default Tweaks Installed on first run (skip with `--no-default-tweaks`): | ID | Repo | |---|---| | `co.bennett.custom-keyboard-shortcuts` | `b-nnett/codex-plusplus-keyboard-shortcuts` | | `co.bennett.ui-improvements` | `b-nnett/codex-plusplus-bennett-ui` | --- ## Updating Codex (macOS — Sparkle conflict) Codex++ ad-hoc signs the app, breaking Sparkle's integrity check. Use: ```sh codexplusplus update-codex ``` This restores an official Developer ID–signed build for the updater. After Codex updates and restarts, the launch agent watcher re-applies Codex++ automatically. --- ## Uninstall ```sh codexplusplus uninstall ``` Restores the backed-up original `app.asar`, removes the launch agent, and removes `<user-data-dir>`. Tweaks you wrote remain on disk unless you delete them manually. --- ## Troubleshooting ### "App is damaged and can't be opened" (macOS) The ad-hoc signature isn't trusted on first launch. Run: ```sh xattr -cr /Applications/Codex.app ``` Then open the app again. ### Patch not persisting after Codex update The launch agent should re-run `repair` automatically. Check status: ```sh codexplusplus status codexplusplus doctor ``` If the launch agent isn't running, reinstall: ```sh codexplusplus uninstall && codexplusplus install ``` ### Tweak not loading 1. Check `manifest.json` has all required fields (`id`, `name`, `version`, `githubRepo`, `author`, `description`, `minRuntime`). 2. Ensure `index.js` / `index.ts` exports a default object with `start` and `stop`. 3. Check logs: `api.log.error` output appears in Codex DevTools console. 4. Run `codexplusplus doctor` for runtime integrity checks. ### Runtime version mismatch ```sh codexplusplus repair # refreshes runtime from CLI ``` ### Tweaks directory location ```sh codexplusplus tweaks open # opens in Finder/Explorer ``` --- ## Security Model - Tweaks run in the **renderer process** with the same privileges as Codex's own renderer code. - Codex++ does **not** auto-update tweak code — users must manually review and install updates. - `githubRepo` is only used for version checks via the GitHub Releases API, not for auto-downloading code. - See [`SECURITY.md`](https://github.com/b-nnett/codex-plusplus/blob/main/SECURITY.md) for the full policy and vulnerability reporting process. --- ## Community - [Discord](https://discord.gg/6bY6gGX36H) — `#tweak-dev` channel for tweak authors - [GitHub Issues](https://github.com/b-nnett/codex-plusplus/issues) — bug reports and feature requests - Docs: [`docs/WRITING-TWEAKS.md`](https://github.com/b-nnett/codex-plusplus/blob/main/docs/WRITING-TWEAKS.md) and [`docs/ARCHITECTURE.md`](https://github.com/b-nnett/codex-plusplus/blob/main/docs/ARCHITECTURE.md)