Customizing the Codex Desktop Theme: Official Appearance Settings and Dream Skin

Who This Guide Is For

First, decide whether the extra customization is worthwhile for you:

• You only want to switch between light and dark themes or adjust the fonts: The first section on official settings is all you need. It takes five minutes and requires no third-party software.
• You want the kind of result that makes someone ask what they are looking at: Continue to the second section on Dream Skin for a custom full-window illustration, anime image, or photograph.
• You use a company-managed device or have concerns about third-party injection: Stick to the official settings and the alternatives near the end of this guide; skip Dream Skin.

Level One: Official Appearance Settings

Codex desktop provides its customization controls under Settings → Appearance, and they cover more than many users realize:

1. Base theme: Switch among the built-in dark and light foundations.
2. Fine-tuned colors: Adjust the accent, background, and foreground colors independently if none of the built-in combinations feels right.
3. Fonts: Configure UI and code fonts separately. Switching code to a monospaced typeface such as JetBrains Mono or Sarasa Term—with ligatures or proper CJK alignment—can improve the experience immediately.
4. Theme sharing: Export a custom theme and share it with others, which is useful when a team wants a consistent visual setup.

There is also an Easter-egg-like Pets feature under Settings → Appearance → Pets. It puts a pixel pet in the interface and lets you select a built-in animal or load a custom one from your local Codex home directory. It is purely decorative, but genuinely relaxing.

Note: Appearance settings affect only presentation. They are completely independent of your models and API configuration, so experimenting with them will not affect conversations or usage allowances.

Level Two: Custom Skins with Codex Dream Skin

The official settings can change colors but not the overall texture of the interface. To cover the workspace with a background of your choice, you need a community solution. Codex Dream Skin is currently the most complete open-source skinning project, and it has prompted popular discussions on V2EX and CSDN. Its key characteristics include:

• Native controls remain interactive: The sidebar, cards, and input box are real UI elements, not a fake screenshot layered over the app. The background fills the window at 16:9, and task pages automatically reduce visual distraction.
• Official files remain untouched: It does not modify the .app, app.asar, or installation directory, so it does not break the code signature. Instead, after the application starts, it dynamically injects styles and a background over local CDP (Chrome DevTools Protocol, restricted to 127.0.0.1).
• Save, switch, and restore: Themes are stored locally. You can keep several, switch among them at any time, and restore the original official appearance in one step.

The repository currently includes two curated presets: Gothic Void Crusade (the macOS default, designed by community contributor @seansong-ideogram) and Arina Hashimoto (tuned for both light and dark modes and also preinstalled by the Windows installer). Once installed, macOS users can switch presets with a single command:

~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh \
  --id preset-gothic-void-crusade

The dark version of the “Arina Hashimoto” preset running in the app. The background and foreground retain readable contrast in dark mode. The theme adapts to the active appearance without changing your light/dark preference. (Source: project README)

A preview of “Gothic Void Crusade,” the default macOS preset. The subject sits on the right, leaving open space on the left for native content—the standard composition recommended by the project. (Source: project README)

Installation Option One: The Setup Scripts

On macOS, from the repository root:

cd macos
# 双击 “Install Codex Dream Skin.command”，或命令行：
./scripts/install-dream-skin-macos.sh --no-launch
# 可选：安装菜单栏集成（基于 SwiftBar，🎨 图标管理主题）
./Install\ Menu\ Bar.command

After installation, the engine is placed at ~/.codex/codex-dream-skin-studio, and four shortcuts appear on the desktop: launch/reapply (Codex Dream Skin.command), customize (Customize), status check (Verify), and one-click recovery (Restore). Routine image changes, pausing, and theme switching can all be managed from the 🎨 menu-bar icon.

On Windows, first install Node.js 22 or later, then run in PowerShell:

powershell -ExecutionPolicy Bypass -File .\windows\scripts\install-dream-skin.ps1
powershell -ExecutionPolicy Bypass -File .\windows\scripts\start-dream-skin.ps1

The installer preserves your native appearance settings, includes the Arina Hashimoto theme, and copies the runtime to %LOCALAPPDATA%\CodexDreamSkin. You can then apply or pause the skin, import images, save and switch themes, and fully restore the app from the system tray. Recovery uses scripts\restore-dream-skin.ps1 and offers granular flags: -RestoreBaseTheme restores only appearance values, -RecoverConfigBackup restores the configuration backup byte for byte, and -Uninstall removes shortcuts.

Installation Option Two: The Skill Edition

The community also maintains a matching Skill distribution, aithink001/Codex-Dream-Skin-Themes. It packages skin management as a Codex skill, allowing you to change themes through conversational instructions:

git clone --depth 1 https://github.com/aithink001/Codex-Dream-Skin-Themes.git
mkdir -p ~/.codex/skills
cp -R Codex-Dream-Skin-Themes/skills/codex-dream-skin ~/.codex/skills/

After restarting Codex, invoke $codex-dream-skin with a natural-language instruction to install a theme, list saved themes, switch themes, or restore the original appearance. For the lowest-effort route, send the repository URL to Codex and ask it to handle the installation.

Specifications for Custom Backgrounds

• Dimensions: 2560×1440 (16:9) is recommended, with a minimum width of 2,000 pixels. Processed images are limited to 16 MB, 16,384 pixels on either side, and 50 million total pixels. On macOS, the source image may be as large as 50 MB and is automatically compressed to fit. Smaller images such as 1672×941 also work and will be scaled proportionally, but images that are too small will look blurry.
• Formats: macOS supports PNG, JPEG, HEIC, TIFF, and WebP; Windows supports JPEG and PNG. On macOS, the source can be a local path or an HTTPS CDN image URL. CDN backgrounds remain exclusive to macOS for now.
• Composition: Use a pure background image. It must not contain a fake window, sidebar, button, readable text, logo, or watermark. The project recommends keeping roughly the left 50–58% quiet and low-contrast for native interface content, while placing the subject within the 58–88% region on the right without pushing it against the edge.
• Platform differences: Windows now supports custom-image imports, saving several themes, and switching from the system tray, bringing it broadly in line with macOS. CDN backgrounds and SwiftBar menu integration are exclusive to macOS, while Windows uses a native system-tray controller.

For advanced customization on macOS, customize-theme-macos.sh can override the accent color while changing the image. load-image-theme-macos.sh also lets you specify the visual focal point and safe area manually:

~/.codex/codex-dream-skin-studio/scripts/load-image-theme-macos.sh \
  --file "/path/to/image.png" \
  --appearance auto \
  --focus-x 0.72 --focus-y 0.45 \
  --safe-area left --task-mode banner

The repository also includes eight concept images in different styles—pink custom, God of Wealth, red-and-white science fiction, transparent design, inspiration cosmos, purple night talk, cyan virtual singer, and stage black-and-gold—which can serve as references when choosing your own background:

The “Inspiration Cosmos” concept: a subject placed to one side and a unified palette make this a suitable type of background composition. (Source: project README; concept images cannot be imported directly.)

The “Cyan Virtual Singer” concept. Images like this demonstrate a style rather than provide an importable theme package; prepare your own image according to the specifications above. (Source: project README)

Security Considerations for Third-Party Injection

Solutions like Dream Skin are fundamentally based on injection through a local debugging protocol. Consider the following before using one:

• Injection is local only: CDP listens on 127.0.0.1 and is not exposed to the public internet. Before injection, the project verifies the official Codex signature and Team ID and enforces resource restrictions. The project is open source under the MIT license, so you can audit the injected CSS and scripts yourself.
• Accounts and data are unaffected: It does not touch API keys, the base URL, model configuration, or conversation data. The worst outcome of a failed skin is a display problem, which you can resolve by restoring the official appearance.
• Check before using it on a company device: Some enterprise endpoint-security policies block or flag debugging ports. Confirm compliance before installing it on a managed machine.
• Install Skills only from trusted sources: Skills under ~/.codex/skills/ can act with conversational context. If you install the skinning Skill, use the official repository rather than an unknown repackaged copy. This matters more than the skin itself. The project also advises against running untrusted local programs while the skin is active, so nothing can piggyback on the local debugging port.

Common Pitfalls

1. The skin stops working after a Codex update: Injection solutions are version-sensitive. A major upgrade may require you to rerun installation or apply the skin again. The project supports recovery after upgrades, so this is expected behavior rather than a broken installation.
2. The image contains “fake UI”: A background with baked-in windows, buttons, text, or watermarks will look awkward at best and violate the project’s requirements at worst. Use a pure background and follow the composition guidance above.
3. Portrait or low-resolution images look poor: Background fitting is designed around a horizontal 16:9 safe area, so a portrait wallpaper will crop out its subject. Preparing the image at 2560×1440 avoids the problem.
4. The interface text becomes hard to read: A busy background can destroy text contrast. Choose an image with its subject on the right and a calm area on the left, or increase foreground contrast in the official settings first. You can also use load-image-theme-macos.sh to move the focal point and safe area apart manually.
5. Recovery is attempted at the wrong time: The macOS one-click recovery script (Restore.command) requires Codex to be closed first and checks process information before making changes. If recovery fails, make sure Codex has completely exited.
6. Deleting the repository directory also deletes the theme: The Skill edition keeps themes in its local skill directory, so do not accidentally remove ~/.codex/skills/codex-dream-skin during disk cleanup. Script-edition themes and images live under ~/Library/Application Support/CodexDreamSkinStudio on macOS and %LOCALAPPDATA%\CodexDreamSkin on Windows.

Alternatives

• Use only the official themes: Codex’s built-in theme system is already strong, with styles corresponding to popular palettes such as Everforest, One Dark, Dracula, Nord, Catppuccin, Gruvbox, Tokyo Night, and Rose Pine. Paired with font adjustments, it will satisfy most preferences.
• Bring Codex colors to VS Code: The open-source BXCQ/Codex-Theme-Collection project ports the official Codex themes to VS Code, reproducing accent colors, diff colors, and Skill highlighting. It suits people who switch between the two editors and want a consistent appearance. For this kind of editor-plus-AI setup, see the combined AI coding-tool workflow.
• Leave it alone: Spend the time on making AI coding tools genuinely productive and keep the default interface. That is entirely reasonable; visual customization is optional.

Conclusion

In order of return on effort, start by tuning the official Appearance theme, colors, and fonts. It is free, risk-free, and produces the greatest benefit. Then decide whether Dream Skin is worthwhile. Its custom backgrounds, multiple-theme switching, and menu-bar management form the most mature loop on macOS, while Windows has caught up with custom images and system-tray management. Both platforms offer one-click recovery. The process leaves official installation files untouched and does not affect APIs or conversations; the one issue that deserves serious attention is the trustworthiness of a Skill’s source.

A tool must work well first, but enjoying how it looks is a worthwhile bonus. If you stare at it for ten hours a day, half an hour of customization is not unreasonable.

(This guide and its commands are based on the open-source Fei-Away/Codex-Dream-Skin repository and its Skill distribution README. It was published on July 17, 2026, and updated on July 19, 2026, to reflect the repository’s latest instructions. Screenshots and concept art in this article were obtained from the project repository and stored locally.)