Codex Dream Skin for Windows

中文 · English

Codex Dream Skin loads an external theme into the official Codex Windows desktop app through loopback CDP. The native sidebar, project picker, task content, and composer remain interactive. The tool does not modify WindowsApps, app.asar, or the app signature.

Requirements

• Windows 10 or newer on x64 (the installer declares Windows 10 as its minimum).
• The official OpenAI.Codex app installed from Microsoft Store and registered for the current user.
• Release Setup.exe bundles Node.js. Only source-based use needs Node.js 22 or newer on PATH.
• Windows PowerShell 5.1 or newer (the installer invokes it in the background; ordinary users do not open it).

Release install (recommended for users)

Download CodexDreamSkin-Setup-vX.Y.Z.exe from GitHub Releases and follow docs/install-windows.md. The installer contains the pinned Node runtime, so users do not need a source checkout or to run a .ps1 file. It installs per-user and should not request administrator access. An unsigned download may occasionally trigger SmartScreen; use More info → Run anyway only after checking the file came from this Release, and never disable Defender. Updates are new Setup.exe packages installed over the existing copy; themes and images are retained.

Run the installer after Codex has fully exited. Normal use does not require administrator access or ownership changes under WindowsApps.

Advanced: install from source

Ordinary users can skip this section. Open PowerShell in the repository's windows directory and run:

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

The installer validates the official Codex Store package and Node.js, saves a recoverable appearance baseline, and initializes the local theme store. By default it also creates these shortcuts:

• Codex Dream Skin: launch or reapply the skin.
• Codex Dream Skin - Tray: open the system tray theme controls.
• Codex Dream Skin - Restore: restore the stock appearance and close the saved CDP session.

Source-install commands and daily shortcuts both use RemoteSigned, so they do not override system or enterprise Group Policy. The installer verifies the runtime copy with SHA-256, then clears download-zone markers only from managed PowerShell copies under %LOCALAPPDATA%\CodexDreamSkin\engine.

Pass -Port during installation to use a fixed custom port. Valid ports range from 1024 through 65535.

powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\scripts\install-dream-skin.ps1 -Port 9444

Update

Exit the Dream Skin tray and close Codex, update the checkout (git pull, or download the latest source again), then rerun the install command above. The installer atomically replaces the managed runtime and rebuilds its shortcuts without deleting the active theme, saved themes, or imported images.

Launch and verify

The Codex Dream Skin shortcut is the recommended launcher. It asks for confirmation before restarting an open Codex window.

Command-line launch:

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

Run verification after launch:

powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\scripts\verify-dream-skin.ps1 `
  -ScreenshotPath "$env:TEMP\codex-dream-skin.png"

The verification script confirms:

• The CDP endpoint is bound to loopback and belongs to the current official Codex package.
• The current renderer has loaded the expected skin version.
• The native sidebar and composer remain present.
• The decorative skin layer does not intercept pointer events.
• When the current route is home, the themed home structure has loaded.

Next, use the generated screenshot to check horizontal overflow and text contrast. On both the home and normal task routes, manually check the project menu and composer interaction. See references/qa-inventory.md for the complete visual checklist.

Change and save themes

Open Codex Dream Skin - Tray to:

• Import a PNG, JPEG, or WebP background.
• Import an ordinary .zip theme pack into Saved Themes (.dreamskin is not supported).
• Save the active theme and switch through saved themes.
• Pause or resume the skin.
• Reapply the theme or fully restore Codex.

For a reviewed, compatible three-payload theme on DreamSkin.cc, choose Apply in app to open dreamskin://apply?version=.... Windows shows a native confirmation first. After confirmation, the client downloads that exact version only from https://api.dreamskin.cc, checks the reviewed metadata, actual byte count, and SHA-256, then runs the same manifest, image, ZIP, and Safe CSS checks as manual import before switching. If there is no verifiable skin session, the client first starts or restarts Codex and verifies that the on-disk active theme is the one visibly rendered; only then does it write the downloaded theme, so a rollback baseline is always available. Save unfinished input first. The link cannot provide an arbitrary download URL, file path, command, or silent-apply option. Incomplete legacy themes remain rejected by the client.

Import a UI-free wallpaper rather than a preview containing a window, sidebar, composer, text, or buttons. Images may be at most 10 MB, 16384 pixels on either side, and 50 million total pixels.

Every new official Studio ZIP contains manifest.json, non-empty theme.json, non-empty theme.css, and exactly one background.webp|jpg|png, with optional LICENSE.txt and the reserved manifest.sig. Place them at archive root or inside exactly one top-level theme folder. A local simplified ZIP must contain exactly theme.json, theme.css, and its referenced image; because it lacks manifest integrity and compatibility data, use that format only for trusted content. Limits are 32 MiB compressed, 32 entries, and 64 MiB expanded. Traversal, links/reparse entries, nested archives, and unregistered files are rejected. Official packs also verify the platform, minimum client version, and each payload's declared byte length and SHA-256. Safe CSS is locally revalidated on import and every apply, then runs only against the 12 registered parts. Previously saved legacy themes without CSS remain switchable and inject no extra CSS. manifest.sig is reserved and not used for signature verification. Import only adds to Saved Themes; it does not change the active theme. Identical content is not duplicated. A newer pack with the same ID updates the saved copy in place after the stored identity is confirmed; only a legacy -2/-3 suffix directory with an identical semantic fingerprint is consolidated. Names alone never prove a duplicate, so ambiguous entries are preserved and replacement fails closed.

For the manual fallback, choose Open Themes Folder and move in the complete extracted directory whose immediate children are theme.json, theme.css, and its image: %LOCALAPPDATA%\CodexDreamSkin\themes\. Reopen the tray menu afterward; do not add another wrapper directory. Manual placement bypasses archive checks, so use trusted content only.

Restore and remove shortcuts

Restore the stock appearance. If Codex is running, confirm its closure and relaunch:

powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\scripts\restore-dream-skin.ps1 `
  -RestoreBaseTheme -PromptRestart

Add -Uninstall to also remove the shortcuts created by Dream Skin:

powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\scripts\restore-dream-skin.ps1 `
  -RestoreBaseTheme -PromptRestart -Uninstall

-RecoverConfigBackup restores the complete pre-install config.toml backup and saves the current configuration first. Reserve it for a damaged configuration that normal -RestoreBaseTheme recovery cannot resolve.

Files and logs

Purpose	Path
Dream Skin state root	%LOCALAPPDATA%\CodexDreamSkin
Active theme	%LOCALAPPDATA%\CodexDreamSkin\active-theme
Saved themes	%LOCALAPPDATA%\CodexDreamSkin\themes
Imported image archive	%LOCALAPPDATA%\CodexDreamSkin\images
Session state	%LOCALAPPDATA%\CodexDreamSkin\state.json
Injector log	%LOCALAPPDATA%\CodexDreamSkin\injector.log
Injector error log	%LOCALAPPDATA%\CodexDreamSkin\injector-error.log
Verification log	%LOCALAPPDATA%\CodexDreamSkin\verify.log
Codex configuration	%USERPROFILE%\.codex\config.toml

See ../docs/platforms.md for the complete platform path reference.

Troubleshooting

Node.js is missing

Run node --version, confirm that it reports version 22 or newer, and reopen PowerShell so an updated PATH takes effect.

The official Codex package is missing

Run:

Get-AppxPackage -Name OpenAI.Codex

The scripts accept only a registered official Store package. They do not launch Codex from an arbitrary executable path.

The installer asks you to close Codex

Close every Codex window and run the installer again. Installation requires stable app and configuration state.

Antivirus reports the old tray shortcut

Older tray shortcuts combined hidden PowerShell with ExecutionPolicy Bypass, which can trigger behavior-based LNK detections. Do not whitelist the detection blindly. Update the source and rerun the installer so the shortcuts use RemoteSigned. If the updated shortcut is still detected, leave it quarantined and report the antivirus product, version, detection name, and shortcut properties without sharing secrets or private data.

The port is occupied

When -Port is omitted, the launcher searches for a free port beginning at 9335. If another process owns an explicitly requested port, choose a different port rather than stopping an unknown listener.

Verification cannot find a CDP endpoint

Launch Codex through the Codex Dream Skin shortcut, then run verification. A normal Codex launch does not open the debug session used by Dream Skin.

Starting with Codex Store 26.715.10079.0, the owl runtime may convert package-activation arguments into a codex:// path. The launcher detects that behavior and makes one raw-argument fallback attempt against the exact ChatGPT.exe in the same validated Store package; it does not change files or WindowsApps permissions.

Field results in issue #235 now confirm two independent failures: WindowsApps returns access-denied for direct launch on 26.715.10079.0, while 26.721.3404.0 retains the raw CDP arguments but its production runtime still opens no listener. Either result means that Codex/Windows combination cannot enable the skin within the project's safety boundary. The fallback is currently a safe diagnostic and rollback path, not a compatibility guarantee for affected owl builds. Do not take ownership of WindowsApps or patch the official package; keep the complete error and follow issue #235 for upstream compatibility status.

If debug launch or visible renderer verification fails, the launcher first confirms that every Codex process started by this attempt is closed, then restores only this attempt's appearance-key values that are still unchanged. Newer config edits are preserved instead of replacing the whole file from an old backup. A bounded preparing transaction is saved before the marker/config commits; after a forced process termination, the next locked operation recovers by comparing the before, intended, and current values. If Codex cannot be confirmed closed or recovery cannot finish safely, one-click apply preserves the current theme files and exact prior-theme snapshot rather than racing the running app. This mechanism is not evidence that an affected official Codex build has restored CDP support.

The skin stops working after a Codex update

Run the installer and launch shortcut again. The scripts rediscover the currently registered Store package instead of trusting an executable path from an older app version.

Open the repository's new issue page and choose the bug form when reporting a problem. Include the Windows version, Codex source, reproduction steps, and relevant log lines. Remove secrets, auth.json, relay tokens, and private conversation content.

Security boundaries

• CDP binds only to 127.0.0.1, but it has no authentication; another process on the same computer may still connect and inspect or control the renderer.
• Pausing the theme or stopping only the injector does not close the debug port of a running Codex process. Use a full restore with restart, or quit every Codex process and reopen the official app normally, to end the exposure window.
• The tool does not modify the official Codex installation, WindowsApps, app.asar, or signatures.
• It does not write API keys, Base URLs, or model provider settings.
• Restore controls only Codex processes that pass package identity, executable path, and recorded session checks.
• See ../SECURITY.md for the complete threat model and operating guidance.

Maintainer and agent constraints live in SKILL.md. See references/runtime-notes.md for deeper runtime troubleshooting.