Codex Dream Skin guide

Codex skin not working: troubleshooting guide

Diagnose installation, launch, verification, readability, update, and recovery failures in a safe order.

Short answer

First restore and prove that normal Codex works. Then decide whether the problem is installation, launch, theme files, readability, an app update, or recovery. Change only the part that actually failed.

Normal Codex also fails

Restore Dream Skin and launch the official app normally. If Home, a task, or the composer still fails, the problem is not the theme settings.

Expected:Normal Codex works before you try the theme again.

If this fails:Do not keep editing theme.json or Dream Skin files while the official app itself is broken.

Installer cannot find a requirement

On macOS, confirm the official app was opened once and ~/.codex/config.toml exists. On Windows, confirm Node 22+ and the current-user Microsoft Store app.

# macOS
test -f "$HOME/.codex/config.toml" && echo "Codex config found"

# Windows PowerShell
node --version
Get-AppxPackage -Name OpenAI.Codex

Expected:The platform requirements are present without bypassing the checks for the official app and required software.

If this fails:Use the official Codex app and a supported Node.js version; never point the commands at an arbitrary executable.

Skin launches but verification fails

Use the included check instead of guessing from appearance. Review the log named by the error. Restore before retrying if Dream Skin cannot confirm the current Codex process or theme files.

Expected:The check confirms the theme is attached to Codex, native controls remain present, and decoration does not block clicks.

If this fails:If the open process cannot be identified, choose a different port or close only the process you recognize.

Wallpaper appears but content is unreadable

This is usually a composition or theme-setting problem. Increase surface opacity or dimming, move the image focus away from reading columns, and test both Home and task pages before changing the Dream Skin app.

Expected:Text, warnings, Diff colors, menus, focus rings, and composer controls remain legible over the image.

If this fails:Do not hide native controls or disable clicks to make the artwork look cleaner.

A Codex update breaks the skin

Restore the normal Codex appearance, verify the official update, update Codex Dream Skin from its GitHub project, rerun the installer, and verify again. Application updates can change where themes attach.

Expected:Codex Dream Skin verifies against the current official app version.

If this fails:Do not copy an old modified app or executable over the updated official installation.

Restore does not complete

Preserve local files, logs, and the appearance backup. Capture the exact error, platform, Codex version, and reproduction steps. Remove API keys, tokens, auth.json, and private conversation data before opening a GitHub issue.

Expected:The issue report contains reproducible evidence without secrets and without destroying recovery data.

If this fails:Do not delete the app data, configuration backup, or an unidentified process as a first response.

Project references

Ready to choose a theme?

Preview artwork and readability before applying anything locally.

Browse free themes