How to Create a Custom Codex Skin with Any Image

The native Codex theme editor is useful when you want to change colors and fonts. But what if you want a real background image, a custom home banner, translucent panels, or an interface inspired by a game, character, photograph, or brand?

That requires a different approach.

Codex Dream Skin is an open-source, third-party skinning tool for the Codex desktop app. It launches the official Codex app with a local Chrome DevTools Protocol connection, then injects CSS and a small amount of decorative DOM into the renderer.

The result looks much more customized than a native color theme, while the real Codex sidebar, project picker, suggestion cards, conversations, and composer remain interactive.

Native Codex themes vs. Codex Dream Skin

These two kinds of customization solve different problems.

If you only want a clean palette such as Dracula, Nord, or Catppuccin, use a native Codex theme. Use Dream Skin when the image and layout are part of the design.

What you will create

A Dream Skin can combine:

• a wide image used as a home banner and low-noise background;
• a theme name, tagline, and short quote;
• primary, secondary, and highlight colors;
• frosted or translucent content layers;
• custom sidebar, card, button, and composer styling;
• decorative crops that do not block the native interface.

The important rule is that your image should decorate Codex, not replace it. Do not turn a full screenshot into a fake overlay. Keep real controls visible, clickable, and above decorative layers.

What you need

macOS

• the official Codex desktop app installed and launched at least once;
• Apple Silicon or Intel Mac;
• the Codex Dream Skin repository;
• a PNG, JPEG, HEIC, TIFF, or WebP image.

The macOS workflow validates and uses the Node.js runtime bundled with Codex, so it does not require a separate global Node.js installation.

Windows

• the official Microsoft Store version of Codex;
• Node.js 22 or newer;
• PowerShell;
• the Codex Dream Skin repository.

The Windows scripts dynamically find the currently installed Store package instead of relying on a hard-coded application path.

Security warning before you continue

Dream Skin launches Codex with a Chrome DevTools Protocol endpoint on 127.0.0.1. Binding to the loopback address prevents direct access from other devices on your network, but CDP has no same-user authentication. While the themed session is active, another process running under your local user account may be able to inspect or control the Codex renderer.

Only continue if you trust the repository and the other software running on your computer. Review the scripts before executing them, keep the debugging address on 127.0.0.1, and use the Restore workflow when you finish using the skin.

The installer does not modify the official application package or its signature. It does create local launchers and state files, and it backs up and may adjust Codex appearance settings so the injected skin has a compatible base palette.

Step 1: Download Codex Dream Skin

Open the Codex Dream Skin repository and download it with Git or GitHub's Download ZIP option.

Using Git:

git clone https://github.com/Fei-Away/Codex-Dream-Skin.git
cd Codex-Dream-Skin
git switch --detach 26c6c410e0e0bfc053356474620e17f934f483fc

The final command pins the exact revision reviewed for this guide. If you intentionally use the latest main branch instead, read the current platform instructions and changelog before running its scripts.

The repository is divided into separate macos and windows directories. Use the instructions for your operating system; the implementations are not interchangeable.

Step 2: Choose the right image

The source image has more influence on the finished skin than any individual CSS value.

For the best result:

• use a wide image at least 2,000 pixels across;
• keep the left side relatively calm because native home text may appear there;
• leave some low-detail or darker space for interface panels;
• avoid important faces or text near the edges, where responsive cropping may hide them;
• choose one or two colors from the image for the UI accents;
• verify that you have the right to use and redistribute the image.

On macOS, the customization script accepts source images up to 50 MB. It converts the selected image into an optimized JPEG with a maximum dimension of 3,200 pixels and requires the prepared image to remain under 16 MB.

Step 3: Pick three interface colors

Dream Skin's macOS customizer uses three color inputs:

• accent: the primary interactive color;
• secondary: a supporting color for gradients and details;
• highlight: a stronger decorative color.

For example:

Accent:    #7cff46
Secondary: #36d7e8
Highlight: #642a8c

Sample these colors from the source image, but do not use three colors with the same brightness. A practical combination is one bright accent, one medium supporting color, and one darker highlight.

The content must remain readable. Test text, buttons, cards, and code diffs—not just the banner.

Create and install a Dream Skin on macOS

1. Open the macOS directory

cd Codex-Dream-Skin/macos

Close Codex before installation. This allows the installer to create a safe appearance backup without the configuration changing during the operation.

2. Run the optional checks

./tests/run-tests.sh

These checks are useful before installation, especially after downloading a newer version of the repository.

3. Install the engine and launchers

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

The engine is installed at:

~/.codex/codex-dream-skin-studio

User images, state, logs, and the theme backup are stored under:

~/Library/Application Support/CodexDreamSkinStudio

The installer also creates desktop launchers for starting, customizing, verifying, and restoring the skin.

4. Create a theme with the visual customizer

Run:

~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh

The script opens a Finder image picker and asks for a theme name. It prepares the image, writes the theme files, and applies the skin.

5. Or create it with one command

You can provide the image, name, and colors directly:

~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh \
  --image "/path/to/image.png" \
  --name "Midnight Garden" \
  --tagline "A quiet place to build." \
  --quote "MAKE SOMETHING WONDERFUL" \
  --accent "#7cff46" \
  --secondary "#36d7e8" \
  --highlight "#642a8c"

Use a real absolute image path. The script applies the theme immediately unless you add --no-apply.

6. Start, verify, or restore from the desktop

After installation, use the generated launchers:

• Codex Dream Skin.command — start or reapply the skin;
• Codex Dream Skin - Customize.command — choose a new image and colors;
• Codex Dream Skin - Verify.command — verify that the injection is active;
• Codex Dream Skin - Restore.command — stop the injector and return to the official appearance.

The optional SwiftBar menu adds a 🎨 Skin item to the macOS menu bar for applying, pausing, or changing the image.

Install Codex Dream Skin on Windows

The Windows and macOS workflows are not feature-equivalent. The Windows version currently ships a prepared decorative skin and exposes the CSS and image assets for further editing, while macOS provides an interactive image customizer. The Windows workflow is therefore more manual and more technical.

1. Install Node.js 22 or newer

Confirm the version:

node --version

2. Close Codex and run the installer

From the repository's windows directory:

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

-ExecutionPolicy Bypass applies to this PowerShell process rather than changing the machine-wide policy. It still permits the downloaded script to run, so inspect the repository and confirm the checkout before executing it.

The installer validates the official Store package, saves the existing base appearance, and creates Start and Restore shortcuts.

3. Start the themed session

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-dream-skin.ps1 -PromptRestart

If Codex is already open without the required debugging port, the script asks before restarting it. Unsaved text in the composer may be lost during that restart.

4. Customize the Windows assets

The main visual files are:

windows/assets/dream-skin.css
windows/assets/dream-reference.png
windows/assets/renderer-inject.js

Start by replacing the reference image with an image of the same filename, then adjust the color variables near the top of dream-skin.css:

:root.codex-dream-skin {
  --dream-ink: #4c2364;
  --dream-purple: #8b3dce;
  --dream-violet: #b45cff;
  --dream-pink: #ff73bd;
  --dream-blush: #fff3f9;
}

Keep decorative elements set to pointer-events: none so they cannot intercept clicks intended for Codex controls. After editing assets, rerun the installer and launcher, then verify both the home screen and a normal conversation.

Avoid editing renderer-inject.js unless you understand the renderer integration and cleanup behavior. Most visual changes belong in the image and CSS.

5. Restore the official appearance

Use the generated Codex Dream Skin - Restore shortcut, or run:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\restore-dream-skin.ps1 -RestoreBaseTheme -PromptRestart

This closes the themed CDP session, stops the verified injector, restores the saved appearance values, and reopens Codex normally.

Test the finished skin

Check both appearance and functionality:

1. Confirm that the banner and background image load.
2. Open and close the sidebar.
3. Select a project from the real project picker.
4. Click a native suggestion card.
5. Type and submit a prompt in the composer.
6. Open a normal task containing long text and code.
7. Review a diff with additions and removals.
8. Resize the window and check image cropping.
9. Navigate between the home screen and existing threads.
10. Run the Verify launcher or script before considering the skin complete.

If a decorative layer blocks a button, it is a failed skin even if the screenshot looks good.

Important safety notes

Dream Skin uses CDP, which is a powerful local debugging interface.

The project binds it to 127.0.0.1, so it is not exposed to other devices on your network. However, CDP does not authenticate other programs running under the same local user account.

While a themed session is active:

• run only software you trust;
• do not expose the debugging port to the network;
• do not change the address from 127.0.0.1;
• use Restore when you are finished with the skin;
• download scripts only from the repository you have reviewed;
• rerun installation after a Codex update if the skin stops applying.

The project does not need your OpenAI password, API key, or Base URL. A skin installer should never silently change model-provider settings.

Common problems

The skin does not appear

Close Codex, rerun the installer, then start Codex through the Dream Skin launcher instead of the normal app icon. The injector must remain running to reapply the skin after renderer reloads and navigation.

Codex is already running

Save any unsent composer text, then allow the launcher to restart Codex. The app must start with the local debugging flags for injection to work.

The image is unreadable behind text

Use a calmer image, reposition the important subject, darken or blur the background, or increase the opacity of content panels. The goal is atmosphere without sacrificing readability.

The skin stops working after an update

Rerun the current repository's installation and launch steps. Codex UI markup can change, so an older CSS selector or renderer marker may need an upstream project update.

I want the normal Codex interface back

Use the Restore launcher. Do not delete random Codex files or edit the official application package.

Make the skin your own

Begin with one image and three colors. Keep the first version simple, test it during a real coding task, and only then add typography, decorative crops, gradients, or custom card treatments.

A good Codex skin should still feel like Codex. The image creates the mood; the real interface remains in control.

Sources

• Codex Dream Skin repository
• macOS setup and customization at the reviewed commit
• Windows Dream Skin workflow at the reviewed commit
• Windows runtime and safety notes at the reviewed commit