How to Install Codex Dream Skin on macOS – Step-by-Step Guide

Overview

Codex Dream Skin applies a custom visual theme to your official Codex Desktop app through local loopback CDP (Chrome DevTools Protocol). It does not modify the official .app, app.asar, or code signature, keeping your installation safe and reversible.

All native functionality remains intact: sidebar, suggestion cards, project picker, composer, and menus stay fully interactive. Only the banner and background layers are customized.

Prerequisites

• macOS (any recent version)
• Official Codex Desktop app installed and launched at least once (so ~/.codex/config.toml exists)
• No global Node.js installation required (uses Codex's bundled Node after validation)
• Git installed (to clone the repository)

Step-by-Step Installation

1. Download the Dream Skin repository

Open Terminal and clone the repository:

git clone https://github.com/Fei-Away/Codex-Dream-Skin.git
cd Codex-Dream-Skin/macos

2. Run the install script

Install to the stable path and create Desktop launchers:

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

This script will:

• Copy the skin engine to ~/.codex/codex-dream-skin-studio
• Create .command launcher files on your Desktop
• Set up state storage in ~/Library/Application Support/CodexDreamSkinStudio

3. Customize your theme

Run the customization script (it will open a Finder picker if you don't specify an image):

~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh

Or specify an image directly:

~/.codex/codex-dream-skin-studio/scripts/customize-theme-macos.sh \
  --image "/path/to/your/image.png" \
  --name "My Theme" \
  --accent "#7cff46"

Image guidelines:

• Supported formats: PNG, JPEG, HEIC, TIFF, WebP
• Source ≤ 50 MB; prepared file ≤ 16 MB
• Wide images work best (width ≥ 2000 px recommended)
• Keep the left side calm for native home titles

4. Start the skin

Double-click Codex Dream Skin.command on your Desktop, or run:

~/.codex/codex-dream-skin-studio/scripts/start-dream-skin-macos.sh

The script will:

• Validate the Codex app signature and Team ID
• Launch Codex with CDP bound to 127.0.0.1 only
• Inject the custom theme into the renderer

How to Verify It's Working

After launching, check for these signs:

1. Custom banner: Your chosen image appears at the top of the home screen
2. Themed background: The task view shows your custom background
3. Native controls preserved: Sidebar, project picker, and composer buttons still work normally

You can also use the verification script:

~/.codex/codex-dream-skin-studio/scripts/verify-dream-skin-macos.sh

How to Restore the Official Appearance

Double-click Codex Dream Skin - Restore.command on your Desktop, or run:

~/.codex/codex-dream-skin-studio/scripts/restore-dream-skin-macos.sh

This will:

• Stop the CDP injector process
• Restore the original theme settings from backup
• Relaunch Codex normally without the skin

Your configuration and chat history remain untouched.

Troubleshooting

Codex doesn't launch or crashes immediately

• Check Codex is installed correctly: Launch the official app once without the skin
• Verify config exists: Run cat ~/.codex/config.toml to confirm it's present
• Check logs: Look in ~/Library/Application Support/CodexDreamSkinStudio/logs/ for error messages

The theme doesn't appear after launching

• Confirm injection: Check that the CDP injector process is running with ps aux | grep injector
• Try re-applying: Run the start script again
• Check image size: If your image is too large, try a smaller one (under 16 MB processed size)

After a Codex update, the skin stops working

This is expected. Codex updates may change internal renderer targets. To fix:

1. Pull the latest version of the Dream Skin repository: cd ~/path/to/Codex-Dream-Skin && git pull
2. Re-run the install script: ./macos/scripts/install-dream-skin-macos.sh --no-launch
3. Start the skin again

If it still doesn't work, check this gallery for compatibility status updates or wait for upstream adaptation.

Permission denied errors

The scripts need execute permissions. If you see permission errors, run:

chmod +x ./scripts/*.sh

Resources:

• Official Dream Skin Repository
• Back to Gallery
• Need help? Check the repository issues or open a new one.