# Codex Dream Skin for Windows

<p align="center">
  <a href="./README.md">中文</a> · <strong>English</strong>
</p>

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](https://github.com/Fei-Away/Codex-Dream-Skin/releases) and
follow [`docs/install-windows.md`](../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
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
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
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\scripts\start-dream-skin.ps1 -PromptRestart
```

Run verification after launch:

```powershell
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`](./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. Codex may restart when it is open without a
usable skin session, so 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
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
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`](../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:

```powershell
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.

### 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](https://github.com/Fei-Away/Codex-Dream-Skin/issues/new/choose) 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`. Avoid untrusted local software while the skin is active.
- 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.

Maintainer and agent constraints live in [`SKILL.md`](./SKILL.md). See [`references/runtime-notes.md`](./references/runtime-notes.md) for deeper runtime troubleshooting.