macOS · manual and Codex-assisted paths

Install Codex Dream Skin on macOS

Before you start

Confirm the local prerequisites

Official Codex Desktop installed and launched at least once
~/.codex/config.toml exists
No global Node.js installation is required

RecommendedUse Codex to install

Copy a safety-scoped macOS prompt

The prompt uses the official repository, protects unrelated configuration, makes verification optional, and requires a restore handoff.

Review the full prompt before copying

Help me install Codex Dream Skin from the official repository https://github.com/Fei-Away/Codex-Dream-Skin.

No specific theme was selected. After installation, show me the bundled themes and ask before applying one.

Safety requirements:
- Explain each action before running it.
- Use only the official repository scripts and current repository documentation. Do not modify the official app bundle, app.asar, WindowsApps, code signatures, or system security settings.
- Do not read, print, replace, or upload API keys, Base URLs, authentication data, private project paths, images, or unrelated configuration.
- If config.toml is complex or multiline, changes during the operation, or a script refuses it, stop and explain. Never delete or rebuild it.
- If a command no longer matches the current repository documentation, stop and report the mismatch instead of improvising.
- Verification is optional, but offer it after launch and explain what evidence it creates.
- Finish by giving me the exact restore command and log/state location.

macOS workflow:
1. Confirm this is macOS and read README.md, macos/README.md, and the relevant scripts.
2. Confirm official Codex Desktop has launched at least once and ~/.codex/config.toml exists. No global Node.js install is required.
3. Clone the repository using:
git clone https://github.com/Fei-Away/Codex-Dream-Skin.git
cd Codex-Dream-Skin
4. Install using:
cd macos
./scripts/install-dream-skin-macos.sh --no-launch
5. After installation, list the bundled presets and ask which one to apply.
6. Start or customize only through the installed Dream Skin launchers/scripts.
7. Offer the optional verification command:
~/.codex/codex-dream-skin-studio/scripts/verify-dream-skin-macos.sh --reload --screenshot ~/Desktop/dream-skin-verify.png
8. Explain engine path ~/.codex/codex-dream-skin-studio, state/log path ~/Library/Application Support/CodexDreamSkinStudio, and restore with:
~/.codex/codex-dream-skin-studio/scripts/restore-dream-skin-macos.sh --restore-base-theme --restart-codex

Read every proposed action in Codex before approving it.

Alternative · Manual terminal path

Six clear steps from clone to restore

Run commands as your normal user. The checkout is used only to install; the engine is copied to a stable path under your account.

Clone the official repository

Clone the official GitHub project and enter the repository. The installer step below moves into the macOS directory.

macOS

Clone the engine source

Use the official project URL and keep the checkout available until installation finishes.

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

Run only after reading the platform guide.

Run the installer

The installer validates Codex’s signed bundled Node, installs the engine at ~/.codex/codex-dream-skin-studio, and creates Desktop launchers. --no-launch keeps launch as a separate, visible decision.

macOS

Install without launching

Run from the cloned repository root. This installs the default theme without launching Codex.

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

Run only after reading the platform guide.

Want a different bundled theme?

The installer starts with the default theme. Choose any bundled preset below and copy its switch command after installation.

Bundled theme

macOS

Switch to Midnight Aurora

Run this installed script after the installer finishes. You can return and copy another preset command at any time.

~/.codex/codex-dream-skin-studio/scripts/switch-theme-macos.sh \
  --id preset-midnight-aurora

Run only after reading the platform guide.

Choose a preset or your own image

A fresh install seeds bundled presets. To import an image, use a UI-free 16:9 JPG, PNG, HEIC, TIFF, or WebP. The recommended master is 2560 × 1440; keep the prepared file within the upstream limits.

macOS

Open local customization

Image analysis stays in the local Codex renderer and tunes focus, safe area, and palette without uploading the image.

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

Run only after reading the platform guide.

Start themed Codex

Open Codex Dream Skin.command from the Desktop. The installer also creates Customize, Verify, and Restore launchers. SwiftBar controls are optional and are not required for a complete installation.

Native sidebar, composer, and controls should remain interactive.

Use only a pure background, never a screenshot containing Codex UI.

Verify and retain evidence

Optional

Verification is not required to use Dream Skin. Run it when you want to confirm injection state and save a screenshot for troubleshooting or a verification record.

macOS

Optional

Optional verification

Reload the injection and save a screenshot to your Desktop. Review it before sharing and remove sensitive content.

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

Optional: use this when you want retained verification evidence.

Restore the original appearance

Use the Desktop Restore launcher or run the restore command. Restoration closes the active skin workflow and returns to the saved base appearance.

macOS

Restore and restart Codex

Keep this command available before you start installation.

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

Run only after reading the platform guide.

Troubleshooting Review the safety boundary