Install Codex Dream Skin on macOS

Support and requirements

• Apple Silicon or Intel Mac
• The official Codex Desktop app installed and launched at least once
• A local ~/.codex/config.toml
• No separate global Node.js installation is required

Get the third-party tool

Open the macos directory in the original repository, review the source, and follow the upstream download instructions shown there. Avoid unofficial download mirrors.

Install Dream Skin

In Finder, double-click Install Codex Dream Skin.command. The source workflow below performs the same installation without launching immediately.

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

Start and customize

Use Codex Dream Skin.command to launch or reapply the theme. Use Codex Dream Skin - Customize.command to choose an image through Finder.

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

Verify the result

Double-click Codex Dream Skin - Verify.command. Inspect both the home screen and a normal task so the native sidebar, project picker, composer, and task content remain usable.

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

Background image guidance

• Supported source formats: PNG, JPEG, HEIC, TIFF, and WebP
• Source file limit: 50 MB
• Prepared file limit: 16 MB
• A wide image at least 2000px across is recommended
• Keep the left side relatively calm for native home titles

Restore Codex

Double-click Codex Dream Skin - Restore.command. Restore stops only the recorded theme helper and matching themed Codex session, then reopens the official app.

./scripts/restore-dream-skin-macos.sh

Optional menu bar

SwiftBar users can install the optional menu bar commands for apply, pause, and image changes.

./Install\ Menu\ Bar.command

Editorial review context

This guide translates the repository layout into a cautious user journey. It is not a signed package, download service, or promise that a particular Codex release remains compatible. Start by confirming that the official Codex application opens normally. Then review the current repository files and their history. The .command launchers are convenience entry points to scripts, so inspect the script each launcher invokes rather than assuming a Finder icon makes it trustworthy.

Apple Silicon, Intel, and permission checks

Apple Silicon and Intel Macs use different processor architectures, while shell launchers can inherit different PATH values depending on whether they are opened from Finder or Terminal. Use current upstream instructions for your architecture and do not substitute an unrelated binary when a command fails. The documented workflow says a separate global Node.js installation is not required; a prompt telling you to install a random runtime from another domain therefore deserves additional scrutiny. Confirm the official app location and launch it once so its normal configuration exists before running the helper.

macOS may quarantine files downloaded through a browser. Inspect the source, repository owner, and file contents before choosing any system-provided Open Anyway action. Prefer narrow, file-specific approval over weakening Gatekeeper or granting broad Full Disk Access. The visual workflow needs access only to paths and processes described by its source. If a prompt requests unrelated folders, contacts, photos, microphone, accessibility control, or administrator credentials without a documented reason, cancel and investigate.

Review the macOS lifecycle before installation

• Read the install script and identify the user-level destination before double-clicking Install Codex Dream Skin.command.
• Follow Codex Dream Skin.command to the script it invokes and confirm local connection and target selection match the explanation.
• Review Codex Dream Skin - Customize.command and the image-preparation script before selecting a personal photo.
• Read Codex Dream Skin - Verify.command, doctor-macos.sh, and Codex Dream Skin - Restore.command before launch.
• Check recent issues for architecture, permission, and current Codex compatibility reports; do not infer support from an old screenshot.

Keep the downloaded source folder until you have verified both launch and restore because it gives you a stable reference for the exact scripts used. If you later update the repository, review changes before mixing a new launcher with old installed state. A reproducible setup has a known source commit, known official-app state, and saved diagnostic output; it is not defined merely by a successful double-click.

Verify the Mac result beyond the wallpaper

Run the documented doctor or Verify launcher after applying the theme, then inspect the interface yourself. Check the home screen, project picker, a long task, code blocks, links, menus, composer, window resizing, and the base appearances you actually use. A background that looks attractive behind an empty window can make dense task history difficult to read. Use the composition guide to reserve quiet space and avoid critical details near the bottom input region.

• Confirm official Codex identity and ordinary launch still work independently of the helper.
• Confirm keyboard navigation, selection, copy, scrolling, links, and composer controls remain available.
• Check the Finder-selected image in both the ultrawide home crop and task-page crop.
• Save doctor output without publishing task text, usernames, home-directory paths, tokens, or account details.
• Exercise Codex Dream Skin - Restore.command and verify that normal appearance returns before treating setup as complete.

Troubleshoot permissions, updates, and stale state

When a launcher opens and closes immediately, run the corresponding reviewed script from Terminal so you can read its output instead of repeatedly double-clicking. Distinguish a shell permission error from Gatekeeper quarantine, a missing official app, an unsupported image, a local-port conflict, and a renderer compatibility change. Those causes require different responses. Do not solve all of them by adding execute permission recursively or removing quarantine attributes from an entire directory tree.

After a Codex update, first restore and confirm the official application is healthy. Compare upstream changes, rerun only the documented installation or launch stage, and verify again. If the theme shows on one surface only, record which page, window size, and base appearance were active. If image preparation fails, test a copy of a modest PNG or JPEG rather than altering the original photo. This separates format and size problems from runtime styling.

• Include Mac model family, processor architecture, macOS version, exact launcher, source commit, and sanitized doctor output.
• Describe whether the official app launches after restore and whether the problem began after a Codex, macOS, or project update.
• Do not upload personal backgrounds or screenshots containing private task content unless essential and safely redacted.
• Send documentation corrections to CodexSkin and runtime behavior reports to the upstream repository.