Codex Theming Tutorial

Three core steps

1. 1

   Step 1: Install the theming engine (macOS)

   Double-click Install Codex Dream Skin.command in the repo's macos folder (or run the script below in a terminal). The engine deploys to ~/.codex/codex-dream-skin-studio/ and creates four desktop launchers: Start / Customize / Verify / Restore. Note: macOS needs no separate Node.js install — it reuses the signed Node bundled inside Codex.app, and never modifies Codex's official bundle or code signature.

   ./scripts/install-dream-skin-macos.sh

2. 2

   Step 2: Pick an image + palette, generate the theme

   Double-click Codex Dream Skin - Customize.command on your desktop, pick a wide image (2000px+ wide — for Miku, your favorite Miku wallpaper) in the Finder dialog, then enter a name and colors (Miku teal #39C5BB). The script converts the image to a ≤16MB JPEG, writes theme.json, and auto-applies it. PNG/JPEG/HEIC/TIFF/WebP are supported; keep the left side calm for the native title.

   ~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh --image "/path/to/miku.png" --name "Hatsune Miku" --accent "#39C5BB" --secondary "#FF61C7" --highlight "#00B4DC"

3. 3

   Step 3: Apply, verify, and restore in one click

   The theme auto-applies once generated. Later, double-click Start Codex Dream Skin.command to re-apply; Verify to screenshot the result; or Restore Codex Dream Skin.command to revert to Codex's default UI in one click — it won't affect future official updates. Theming works via CDP injection over the local loopback 127.0.0.1:9341, purely as a runtime overlay.

   ~/.codex/codex-dream-skin-studio/scripts/restore-dream-skin-macos.sh --restore-base-theme --restart-codex

Theme pack format & install

A theme is simply a folder: one theme.json (colors + text config) plus one background image. The open-source project has no theme store and no 'import theme' command, so 'downloading a theme' means getting such a folder, dropping it into the theme library, and switching with a single script. Below uses a theme named miku as an example.

~/Library/Application Support/CodexDreamSkinStudio/
└── themes/
    └── miku/
        ├── theme.json   # colors + text config
        └── miku.png      # filename named in theme.json's "image" field

After dropping the miku folder into the theme library, run this command to switch and apply:

~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh --id miku

Note: the "image" field in theme.json must exactly match the image filename in the same folder; the image must be png/jpg/jpeg/webp and ≤16MB. If Codex is already open it hot-switches; otherwise double-click Start Codex Dream Skin.command.

Change colors only (keep the image)

The customize command always needs an image, but you can skip it: hand-edit the colors field of the active theme.json (leave image alone) and re-apply. It's the fastest way to recolor — no need to source an image every time.

1. 1

   1. Open the active theme config

   The active theme's config lives at this path — open it in any editor (open -e uses the default editor; nano / VS Code work too).

   open -e ~/Library/Application\ Support/CodexDreamSkinStudio/theme/theme.json

2. 2

   2. Edit only the colors block, keep image

   Replace the whole colors block with your palette (#RRGGBB or rgba()); leave the image field as-is. Fastest: open any theme page here, click 'Download theme.json', and copy its colors block straight in.

   "colors": {
     "background": "#06121a",
     "panel": "#0c1e2a",
     "panelAlt": "#091820",
     "accent": "#0ea5e9",
     "accentAlt": "#0ea5e9",
     "secondary": "#22d3ee",
     "highlight": "#0ea5e9",
     "text": "#e0f7ff",
     "muted": "#6f9aab",
     "line": "rgba(14, 165, 233, 0.22)"
   }

3. 3

   3. Re-apply

   Save, then double-click Start Codex Dream Skin.command — the injector re-reads theme.json, so the new colors take effect while the background image stays. Colors must be #RRGGBB or rgba(), or the injector errors.

What about Windows?

Windows differs from macOS: it currently ships only one fixed pink-purple Dream skin (default port 9335) and can't yet customize the image or colors — custom themes are macOS-only. Below are the real PowerShell commands to install, apply, and restore on Windows.

1. 1

   1. Install Node.js 22+ first

   Unlike macOS, Windows can't reuse Codex's bundled Node — you must install Node.js 22 or newer first (the built-in WebSocket client requires it).

2. 2

   2. Install & apply the fixed skin

   From the repo root, run the install script in PowerShell — it sets up the fixed Dream skin, closes and relaunches Codex, and creates desktop and Start-menu shortcuts.

   powershell -File windows/scripts/install-dream-skin.ps1

3. 3

   3. Start / restore

   Then launch via the desktop shortcut 'Codex Dream Skin.lnk' or the start script; to restore the default UI run the restore script (supports -RestoreBaseTheme / -RecoverConfigBackup / -Uninstall).

   powershell -File windows/scripts/restore-dream-skin.ps1 -RestoreBaseTheme

One-click restore

Run the project's Restore script to clear the injection and return to Codex's default UI — it won't affect future updates.

Troubleshooting