CodexSkinBuild a Skin
Menu
Independent Codex appearance guide

Codex Dream Skin Setup, Verification, and Restore Guide

Codex Dream Skin is an independent, public-source third-party project for the Codex desktop app. It can add an image and deeper visual styling by opening a local debugging connection and changing the running interface. It does not replace the official app package, but it is still an unofficial method. Review the license that applies to each file or directory before you copy, modify, or redistribute anything from the upstream repository.

CodexSkin.im does not host or repackage Dream Skin. These instructions were reviewed against the upstream files at commit 26c6c410e0e0bfc053356474620e17f934f483fc. Download that reviewed archive if you want the files that match this guide.

Source checked: Fei-Away/Codex-Dream-Skin commit 26c6c410e0e0bfc053356474620e17f934f483fc, July 17, 2026. The macOS package version in this source lock is 1.1.2.

Verification status: Both platform paths are source-reviewed. CodexSkin.im has not independently reproduced them on a real Mac or Windows device.

CodexSkin.im is not affiliated with or endorsed by OpenAI or the Codex Dream Skin project.

Download Reviewed Source (.zip)View Reviewed CommitView Latest Upstream (Not Reviewed)

The latest upstream repository may contain changes made after July 17, 2026. CodexSkin.im has not reviewed those newer changes. Do not assume the latest files match these steps, limits, or safety notes.

Read the Safety Checklist

Choose the right path first

Use Codex's built-in Appearance settings when:

  • You only want different colors or fonts.
  • You do not need a background image.
  • You want the lower-risk path.
  • You do not want to run third-party scripts or a debugging connection.

Review Dream Skin when:

  • You want an image background or deeper interface styling.
  • You understand that the method is unofficial.
  • You can close and restart Codex when prompted.
  • You are prepared to verify the result and restore the default look.
PLATFORM LIMIT

Custom images are a macOS-only upstream workflow in this source lock

The checked macOS package includes an image customizer. The checked Windows package applies its bundled skin and does not provide the same custom-image path.

Source reviewed at upstream commit 26c6c410… on July 17, 2026.

Lower-risk option: change the built-in appearance

  1. Open the Codex desktop app.
  2. Open Settings from the app menu, or press Cmd+, on macOS or Ctrl+, on Windows.
  3. Open Appearance.
  4. Choose a base theme.
  5. Adjust the available accent, background, foreground, UI font, or code font settings.
  6. Check Home, Task, and Diff views for readable text and visible controls.
  7. To undo the change, return to Appearance and select the previous or default choices.

This path stays inside the app's own controls. It does not add a background image.

Before you install Dream Skin

  • Install the official Codex desktop app and open it at least once.
  • Save unfinished input and close private work that you do not want visible in screenshots.
  • For instructions that match this page, use the reviewed commit archive linked above. If you choose a newer upstream version, review its changes, license notices, open issues, and instructions before running it.
  • Read the open issues that apply to the reviewed commit. Treat this guide as stale for any source changed after July 17, 2026 until CodexSkin.im reviews that newer commit.
  • Close software you do not trust while Dream Skin is active. Loopback reduces exposure, but does not authenticate other software running as your user.
  • Keep the restore section open.
  • Use only an image you created, licensed, or have permission to use.
GET THE REVIEWED SOURCE

Download the commit that matches this guide

Use the reviewed archive for commit 26c6c410e0e0bfc053356474620e17f934f483fc. CodexSkin.im does not mirror or repackage it.

The separate latest-upstream link is not covered by this review.

macOS: install and apply Dream Skin

Requirements

  • A Mac running macOS.
  • The official Codex desktop app installed and launched at least once, creating ~/.codex/config.toml.
  • No separate Node.js installation. The checked installer validates and uses Codex's signed bundled Node runtime.
  • Permission to run a downloaded .command file from the upstream folder.

1. Get the reviewed files

  1. Select Download Reviewed Source (.zip) at the top of this guide.
  2. Confirm that the download URL contains commit 26c6c410e0e0bfc053356474620e17f934f483fc.
  3. Open the ZIP and its extracted Codex-Dream-Skin-26c6c410e0e0bfc053356474620e17f934f483fc folder.
  4. Open the macos folder.

2. Prepare Codex

  1. Open Codex once if this is a new installation.
  2. Quit Codex.
  3. Save unfinished work before continuing; the installer may restart Codex.

3. Install

  1. Double-click Install Codex Dream Skin.command.
  2. Read the macOS prompt before allowing it to continue.
  3. If Codex is open, approve the restart only after saving unfinished input.
  4. Wait for the installed message.

The engine is copied to ~/.codex/codex-dream-skin-studio. State, logs, user images, and the theme backup are stored under ~/Library/Application Support/CodexDreamSkinStudio.

AFTER INSTALLATION

Four launchers keep the path clear

  • Codex Dream Skin.command — Start
  • Codex Dream Skin - Customize.command — Customize
  • Codex Dream Skin - Verify.command — Verify
  • Codex Dream Skin - Restore.command — Restore
Instructional summary based on upstream launcher names, not a CodexSkin.im real-device screenshot.

Do not move files into the Codex app bundle. The upstream installer is designed to leave .app, app.asar, and the official code signature unchanged.

4. Use the bundled look or choose your image

Open Codex Dream Skin.command for the bundled look. For your own image, open Codex Dream Skin - Customize.command, choose a PNG, JPEG, HEIC, TIFF, or WebP image, enter a theme name, allow a restart when asked, and wait for the ready message.

  • Source image: 50 MB or smaller.
  • Prepared image: 16 MB or smaller.
  • Wide images work best; upstream recommends at least 2000 pixels wide.
  • Keep the left side visually calm so titles remain readable.

If you built a recipe on CodexSkin.im

The download is a reviewable ZIP, not a direct installer. Extract it, then choose background.webp through the upstream Customize launcher. The checked upstream does not document one-click import of the recipe ZIP, and browser preview-only adjustments may not all carry into the applied result.

macOS: verify the live result

  1. Open Codex Dream Skin - Verify.command.
  2. Wait for the verifier to finish.
  3. Open Codex Dream Skin Verification.png if the launcher creates it.
  4. Check the live app, not only the screenshot.
  • Codex opens normally and the expected background or skin is visible.
  • The sidebar, project selector, task content, menus, and composer remain usable.
  • Home, Task, and Diff remain readable.
  • Buttons, typing, scrolling, and navigation work.
  • The screenshot has no conversations, project names, account details, or other private information before sharing.
  • You can find the Restore launcher.
Illustrative current Codex-style desktop task shell with a configured abstract Dream Skin behind neutral work controls.
Illustrative preview. Illustrative task-shell preview showing how a configured Dream Skin can affect the app surface. Not a verified compatibility result.
DO NOT CHECK THE BACKGROUND ALONE

Verify the controls, not just the look

A screenshot can confirm appearance. Only the live app can confirm navigation, menus, typing, scrolling, and Diff readability.

CodexSkin.im has not performed this check on a real Mac. A successful result on your device is specific to your Codex version and date.

macOS: update or reapply

  1. Check the upstream repository for a newer commit, release note, or open issue.
  2. If you move to a newer upstream commit, stop treating this page as reviewed instructions for that version. Read the upstream changes and issues, confirm the applicable licenses, and repeat source review plus device verification before relying on the new files.
  3. Quit Codex and run Install Codex Dream Skin.command from the new macos folder.
  4. Run Customize again if needed.
  5. Run Verify and repeat the full live-app checklist.

A reinstall is not proof of compatibility. Restore if verification fails.

macOS: restore the default appearance

  1. Save unfinished input.
  2. Double-click Codex Dream Skin - Restore.command.
  3. Approve the restart and wait for completion.
  4. Confirm Codex opens normally and custom styling is gone.
  5. Open Appearance and confirm the expected base choices returned.

The launcher stops the recorded injector, removes the live skin, closes the saved debugging session, restores saved appearance values, and restarts Codex. It is designed to stop rather than act on an unverified process.

Windows: install and apply the bundled Dream Skin

Current limitation: The checked Windows package does not provide the macOS user-image customizer. These steps apply the upstream bundled skin. Do not present a CodexSkin image recipe as a supported Windows import.

Requirements

  • Windows with the official OpenAI Codex app installed from Microsoft Store.
  • Codex closed before initial install.
  • Node.js 22 or newer in PATH.
  • Windows PowerShell and the original repository extracted.

1. Confirm Node.js

node --version

Continue only with version 22 or newer. If Node is missing, install a current release from the official Node.js website, reopen PowerShell, and check again.

2. Open the reviewed files

Download the reviewed commit archive linked at the top of this guide, extract it, and open PowerShell.

  1. Confirm the archive URL contains the reviewed commit.
  2. Open PowerShell.
  3. Change to the extracted reviewed folder.
cd "$env:USERPROFILE\Downloads\Codex-Dream-Skin-26c6c410e0e0bfc053356474620e17f934f483fc"

3. Close Codex

Save unfinished input and quit every Codex window. The installer refuses to update config.toml while a matching Codex process is active.

4. Install

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

The installer validates the Microsoft Store package and Node.js, saves relevant appearance configuration, and creates Start/Restore shortcuts. State and logs are stored under %LOCALAPPDATA%\CodexDreamSkin. It does not take ownership of or replace files under WindowsApps.

5. Start

Open the Codex Dream Skin Desktop shortcut, or run:

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

Save unfinished input before approving a restart. Do not add -RestartExisting unless you intentionally authorize it. The default port is 9335; the checked script can scan for another free loopback port when no port is forced.

Windows: verify the live result

powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\windows\scripts\verify-dream-skin.ps1" -ScreenshotPath "$env:USERPROFILE\Desktop\Codex Dream Skin Verification.png"
  • Codex opens normally and the bundled Dream Skin is visible.
  • The sidebar, project selector, suggestion cards, task content, menus, and composer remain usable.
  • Home and a normal task render correctly.
  • Buttons, typing, scrolling, and navigation work.
  • The screenshot contains no private data before sharing.
  • The verifier reports neither a missing injection marker nor an unverified CDP endpoint.

A responsive suggestion-card count between two and four can be normal; do not fail verification on count alone.

Windows: update or reapply

  1. Save input and close Codex.
  2. If you move to a newer upstream commit, stop treating this page as reviewed instructions for that version. Read the upstream changes and issues, confirm the applicable licenses, and repeat source review plus device verification before relying on the new files.
  3. Open PowerShell in the new folder.
  4. Run install, start, and verify again.
  5. Inspect both Home and a normal task.

The scripts discover the current registered Store package instead of blindly trusting an old path.

Windows: restore the default appearance

Open Codex Dream Skin - Restore on the Desktop, or run:

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

To remove the shortcuts at the same time, add -Uninstall:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\windows\scripts\restore-dream-skin.ps1" -RestoreBaseTheme -PromptRestart -Uninstall

In this source lock, -Uninstall removes shortcuts. Do not describe it as deleting every downloaded or state file.

Troubleshooting

macOS config file is missing

Open the official Codex app once, quit it, and run the installer again. It expects ~/.codex/config.toml.

macOS cannot find the official app or signed runtime

Stop. Do not bypass the identity or signature check. Confirm the official app is installed and launched once, then review current upstream issues if it still fails.

macOS says Codex is already running

Save input, quit Codex, and open the launcher again. Approve a restart only when ready to lose unsaved input.

macOS image selection or conversion fails

Use PNG, JPEG, HEIC, TIFF, or WebP. Keep the source at 50 MB or less. Resize or simplify it if the prepared image exceeds 16 MB.

The macOS skin is visible but controls are wrong

Run Verify. Restore if Home, Task, Diff, menus, typing, or scrolling is not usable.

Windows says Node.js is missing or old

Run node --version and install Node.js 22 or newer from the official Node.js site.

Windows cannot validate the Store package

Stop. Confirm the official Microsoft Store Codex package is installed. Do not bypass the identity check.

Windows says Codex must be closed

Save work, quit every Codex window, and rerun install only after the app is closed.

Port 9335 is occupied

Do not stop an unknown process. Let the script select another port when no port is forced, or choose a different unused loopback port.

No verified loopback endpoint

Restore or close Codex, then start again. Do not connect the injector to an endpoint that cannot be tied to the official Codex process.

The skin disappears after an update

Check upstream, reinstall or reapply from a fresh original copy, and verify again. Restore if verification fails.

Restore cannot confirm process identity

Do not force-kill by saved PID alone. Close Codex manually, preserve redacted state and logs, and report the issue upstream.

What to include in a support report

  • Platform and operating-system version.
  • Codex version.
  • Dream Skin commit or release.
  • Exact error and failed step.
  • Whether restore completed.

Remove conversations, project names, revealing local paths, account details, passwords, sign-in files, and private access keys. Do not attach auth.json.

IF SOMETHING FEELS WRONG

Restore before you troubleshoot further

Save unfinished input, run the restore action for your platform, restart Codex, and confirm that the default appearance returns.

Known limits

  • Dream Skin is unofficial and depends on interface details that may change.
  • Loopback CDP is locally reachable and does not authenticate other software running as the same user.
  • CodexSkin.im has not independently reproduced the macOS or Windows runtime paths.
  • The checked Windows path does not support the macOS user-image workflow.
  • A CodexSkin browser preview is illustrative.
  • A recipe ZIP is not an installer or a documented one-click upstream import.
  • A dated result applies only to the named platform, Codex version, upstream commit, and check date.

Final safety note: If Codex becomes hard to read, a control stops working, or verification fails, restore the default appearance first. A custom look is optional. A usable editor is not.