Codex Dream Skin guide

Install Codex Dream Skin on macOS

Install Codex Dream Skin, switch an image-backed theme, verify the real Codex interface, and keep a working restore path.

Short answer

On macOS, Dream Skin installs its app files under ~/.codex and stores themes and logs under Library/Application Support. It opens the official signed Codex app through a connection limited to this computer; it does not change the Codex app bundle or app.asar.

Requirements

The official Codex Desktop app installed and launched at least once, so ~/.codex/config.toml exists.
A complete checkout or release from Fei-Away/Codex-Dream-Skin. Avoid third-party repackaged installers.
No separate Node.js installation is required on macOS; Dream Skin uses the copy included with Codex after checking it.

Download from the project page

Get Codex Dream Skin from the Fei-Away/Codex-Dream-Skin project page. Read the current installation guide, license, and artwork notices before running anything.

Expected:You can identify the project owner, macOS folder, installer, and restore command before installation.

If this fails:Stop if the files came from an unknown mirror or the restore command is missing.

Close Codex and install Dream Skin

From the downloaded project folder, enter macos and run the installer without launching. It creates desktop shortcuts and copies the app files to ~/.codex/codex-dream-skin-studio.

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

Expected:The command reports a successful install and creates Start, Customize, Verify, and Restore shortcuts. Themes and logs are stored at ~/Library/Application Support/CodexDreamSkinStudio.

If this fails:If the official app, signature, included Node.js, configuration, or required-file checks fail, do not bypass them. Confirm the official Codex app is installed and has been opened once.

Select a saved theme

Built-in and downloaded packs live under ~/Library/Application Support/CodexDreamSkinStudio/themes/<theme-id>. A pack folder must keep theme.json and its referenced image together. Switch by folder ID; do not point the command at an arbitrary path.

~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh \
  --id <theme-id>

Expected:The selected pack is staged as the active theme, Codex starts or restarts with consent, and the same artwork continues behind native controls.

If this fails:If the theme is rejected, check that theme.json is valid, its image path is relative, the image stays inside the pack, and it meets the limits in the Codex Dream Skin documentation.

Test the real Codex interface

Run the included check and save a screenshot. It confirms that Dream Skin is connected to Codex, the native sidebar and composer are present, and the decorative layer does not block clicks. Manually test Home and one ordinary task afterward.

~/.codex/codex-dream-skin-studio/scripts/verify-dream-skin-macos.sh \
  --reload --screenshot "$HOME/Desktop/codex-dream-skin-verify.png"

Expected:The check completes successfully. Sidebar, menus, scrolling, composer input, Diff colors, focus, and resize remain usable; no horizontal overflow appears.

If this fails:A visible wallpaper is not a pass. Restore first, review the error logs in ~/Library/Application Support/CodexDreamSkinStudio, and retry only after normal Codex works.

Keep recovery one command away

Use the installed restore command when finished, before a Codex update, or when the theme check fails. It restores the previous appearance, closes Dream Skin, and reopens Codex normally.

~/.codex/codex-dream-skin-studio/scripts/restore-dream-skin-macos.sh \
  --restore-base-theme --restart-codex

Expected:Codex reopens with its normal appearance and Dream Skin is no longer active.

If this fails:If restore refuses to continue, preserve the local files and logs. Do not delete backup files or stop an unidentified process; use the troubleshooting guide and report the exact error on the GitHub project.

Project references

Ready to choose a theme?

Preview artwork and readability before applying anything locally.

Browse free themes