README.md

GetCodexTheme companion runtime

This optional, open-source runtime makes installed GetCodexTheme packs visible in Codex Desktop. It launches Codex with a loopback-only Chromium DevTools port, injects responsive artwork and component-level color rules, then watches for renderer reloads.

It does not patch app.asar, modify the signed application, or add an entry to Codex Settings → Appearance. Quit the themed session and reopen Codex normally to close the DevTools port.

Theme switcher surfaces

All switchers share runtime/theme-control.mjs and the same atomic library state. The controller can be tested without opening or connecting to Codex:

node runtime/theme-control.mjs --library /path/to/library status
node runtime/theme-control.mjs --library /path/to/library switch aurora-glass
node runtime/theme-control.mjs --library /path/to/library pause
node runtime/theme-control.mjs --library /path/to/library resume
node runtime/theme-control.mjs --library /path/to/library stock

• The Codex top switcher is an isolated Shadow DOM surface. It is visually fixed in the top bar area and never inserts into, moves, or replaces native Codex controls. If its safe mount or CDP binding is unavailable, the theme continues and the menu reports that the controller is unavailable.
• The macOS menu bar client is built from platforms/macos/menu-bar with AppKit and no third-party dependencies.
• The Windows tray client is platforms/windows/tray.ps1 and uses built-in Windows Forms.

pause and stock hide the visual layer but keep the selected theme and switcher available; resume reapplies it. A switch writes active-theme.json atomically, retains the previous pointer under backups/, and resumes visuals. Broken installed packs are excluded from every switcher.

Optional watchdog

runtime/watchdog.mjs waits for an already debug-enabled Codex endpoint and supervises only the companion injector. In its default/session mode it does not open, quit, or restart Codex, and it stops after a bounded number of repeated injector failures. It is disabled by default. On macOS, a user must explicitly run enable-watchdog-macos.sh; disable-watchdog-macos.sh stops and removes the per-user LaunchAgent. Regular --watch already handles renderer navigation and reloads during one themed session; the watchdog only adds process recovery. Passing --persistent is a separate restart authorization: the service defers the currently running Codex instance, arms only after that instance exits, and may restart a future normal launch with the loopback theme arguments. Rapid restart failures are bounded and stop the service.

Theme library contract

The default library is ~/.codex/get-codex-theme on macOS and %USERPROFILE%\.codex\get-codex-theme on Windows:

get-codex-theme/
├── active-theme.json       # "aurora-glass" or { "themeId": "aurora-glass" }
├── active-theme            # legacy plain-text pointer, also supported
└── themes/
    └── aurora-glass/
        ├── manifest.json
        └── assets/background.jpg

active-theme.json takes precedence when both pointer formats exist. The loader rejects invalid IDs, paths escaping the theme directory, unsupported image types, unsafe CSS color strings, and backgrounds larger than 12 MB.

Validate without Codex

node runtime/injector.mjs --validate --library /path/to/get-codex-theme
node runtime/injector.mjs --dry-run --library /path/to/get-codex-theme

Both commands are read-only and do not connect to Codex. --dry-run prints the resolved delivery plan, including officialAppearance: false.

Component contract

Runtime v2 reads bounded component tokens from tokens/visual-theme.json and derives safe adaptive defaults for older packs. Its own classifier marks known native Codex controls with data-gct-component; authored packs cannot provide DOM selectors, CSS, HTML, JavaScript, or SVG paths. Focused profiles enable only their declared groups, while Complete and Assisted profiles receive all seven groups. Unknown surfaces retain the foundation fallback.

Install and run

macOS:

platforms/macos/install.sh
~/.codex/get-codex-theme/bin/start-macos.sh
~/.codex/get-codex-theme/bin/restore-macos.sh
npx -y get-codex-theme menu-bar start

Windows PowerShell:

.\platforms\windows\install.ps1
& "$HOME\.codex\get-codex-theme\bin\start-windows.ps1"
& "$HOME\.codex\get-codex-theme\bin\restore-windows.ps1"
npx -y get-codex-theme tray start

The first themed start may require closing Codex, or passing --restart on macOS / -Restart on Windows. Node.js 22 or later is required. The Windows launcher expects the official OpenAI.Codex MSIX package and an Appx-capable PowerShell environment.

Security and compatibility

• CDP is bound to 127.0.0.1; do not expose the port or run untrusted local processes during a themed session.
• Every live target read and WebSocket connection verifies the current listener owner first. macOS resolves the app by bundle identifier and accepts only the signed com.openai.codex bundle with OpenAI team identifier 2DC432GLL2 (the current app may be named ChatGPT.app); Windows accepts only ChatGPT.exe inside the matching installed OpenAI.Codex Appx root. Ownership failure closes active runtime sessions before retrying. Live CDP operation fails closed on other platforms; offline pack validation remains platform-independent.
• The runtime distinguishes Home, Task, Scheduled, Plugins, Pull Requests, Chat, Search, and unknown routes without matching user-visible text. It keeps the native Codex information architecture and styles only runtime-classified components. Codex UI updates may require selector-registry maintenance.
• background-size: cover makes 16:10, 16:9 and other landscape images responsive. Narrow windows crop around the manifest's focusX/focusY; they do not stretch the image.
• Artwork is rendered at full color without a uniform full-window scrim. Readability comes from opaque or near-opaque component surfaces, and the runtime does not render a floating brand logo.
• Restore removes the injected DOM/CSS. Reopening Codex normally is the definitive rollback and closes the debug endpoint.