Codex Dream Skin — Control Panel Edition

Theme the official ChatGPT / Codex desktop app — with a native macOS control window.
Local-only · Loopback CDP · Never modifies the official app · MIT licensed

What is it?

Codex Dream Skin is an unofficial, local-only theming tool for the official ChatGPT / Codex desktop app (bundle id com.openai.codex). It injects a theme through a Chrome DevTools Protocol (CDP) connection bound to 127.0.0.1 — it never modifies app.asar, code signatures, or any installed file of the official app.

This repository is a fork of the original Fei-Away/Codex-Dream-Skin project (MIT), based on tag v1.5.14, that adds a native macOS control window on top of the existing menu-bar app. Before this fork, double-clicking the app produced only a menu-bar icon; now it opens a real, visible panel.

What's new in this fork — the Control Panel

• Double-click = a visible window. Launching the app opens a window titled "Codex Dream Skin", while the menu-bar icon and every existing menu keep working.
• Close ≠ quit. Closing the panel only hides it; the menu-bar service keeps running. Opening the app again re-shows and focuses the panel. A new "Open Control Panel…" menu item does the same.
• One source of truth. The panel and the menu share the same DreamSkinCore state snapshot: Skin ON / Skin OFF / Applying / Pausing / Unavailable, the applied theme, the pending theme, and whether ChatGPT is running.
• Explicit, safe actions. Apply skin · Pause skin · Choose a background image (validation + preview only — nothing is applied until you press Apply skin) · Saved-theme list with switching · Import theme ZIP (path-traversal / symlink / zip-bomb / Safe-CSS validated) · Open theme/image folders · Install or repair the engine · Check for updates · Launch at login · Language (Follow system / 中文 / English).
• Restart consent. If applying or switching a theme would have to close and reopen ChatGPT, the panel asks first — with Cancel as the default button — and only proceeds after you explicitly choose "I saved my work, restart now".
• Uninstall is tucked away. "Restore and uninstall" lives in a collapsed Advanced maintenance section, requires two confirmations, and always keeps your images and saved themes.
• No Dock icon. The app remains an LSUIElement menu-bar application; the panel is a normal window.

Screenshots: development build with a bundled fixture theme.

How it works

1. The app launches ChatGPT with --remote-debugging-port bound to 127.0.0.1 only.
2. A node-based injector pushes the validated theme (Safe-CSS + background image) into the renderer over CDP and verifies the visible rendering.
3. Install, pause, restore, ZIP import, engine management and update checks are orchestrated by the bundled engine scripts (macos/scripts/).

Read SECURITY.md for the exact security boundary. In short: the debug port is loopback-only, but CDP is not an authentication boundary — use it on a trusted personal machine and close the debug session when you are done (Restore does this).

Getting started (macOS)

Requirements: macOS 13+, Xcode with Swift 5.9+.

# Build the universal menu-bar app
cd macos
./scripts/build-menubar-app.sh --skip-tests

# Run the test suite (skips branches that need a signed ChatGPT runtime)
CODEX_DREAM_SKIN_SKIP_SIGNED_RUNTIME_TESTS=1 CODEX_DREAM_SKIN_SKIP_DOCTOR=1 ./tests/run-tests.sh

# Isolated development build (dev Bundle ID + sealed test home; never touches your real state)
./scripts/build-dev-panel.sh

On first run the app installs its bundled engine into ~/.codex/codex-dream-skin-studio. Your themes, background images and state live under ~/Library/Application Support/CodexDreamSkinStudio/.

Relation to upstream

Friendly fork of Fei-Away/Codex-Dream-Skin at tag v1.5.14 (commit 95423d8). The theme engine, injector, Windows support and community-theme contracts are upstream's work and remain unchanged. This fork adds:

• the native control window (ControlPanelWindowController),
• panel localization keys (Chinese / English),
• the restart-consent flow with cancel-by-default dialogs,
• a --skip-confirm flag for the apply script used by the panel,
• background-image validation and panel/window lifecycle tests,
• an isolated development build script.

Design notes: docs/control-panel-design.md · Upstream documentation: README.zh.md and README.en.md.

License & notices

• Software source code: MIT, Copyright (c) Codex Dream Skin Studio contributors.
• Not affiliated with, endorsed by, or sponsored by OpenAI. OpenAI/Codex trademarks and official app binaries are not part of this repository.
• Bundled demo artwork is original to the project; user-supplied images and any third-party artwork remain the property of their owners — see macos/NOTICE.md and macos/references/asset-provenance.md.

Acknowledgments

All engine, injector and Windows work is by the upstream Codex Dream Skin contributors. This fork only builds the native macOS control window on top of it.