How to Install a Codex Theme on macOS

This guide follows the current macOS documentation referenced by the Codex Theme Hub repository. It was last checked on July 17, 2026. The project is third-party software, not an OpenAI product, and this website is not its maintainer. Read the latest upstream instructions and inspect the scripts before running them.

Codex Dream Skin currently uses a local loopback Chrome DevTools Protocol (CDP) connection to place an external visual layer behind the native Codex desktop interface. According to the repository, it does not alter the official .app, app.asar, or code signature. That is a meaningful boundary, but it is not a promise of zero risk: CDP is a powerful debugging interface, and the repository advises restoring the standard setup when you are done.

Before you begin

The current macOS requirements are intentionally short:

• A Mac running macOS.
• The official Codex Desktop app installed.
• Codex launched at least once so ~/.codex/config.toml exists.
• The original Codex Dream Skin source from GitHub.

The project currently says a global Node.js installation is not required on macOS. Its installer validates and uses the signed Node runtime bundled with the official Codex or ChatGPT app. Do not install an unrelated Node package merely because an older third-party guide tells you to.

The same upstream entry point is documented for Apple Silicon and Intel Macs. The installer performs architecture and signed-runtime validation itself. There is no separate command in the current README for the two processor families, so this guide does not invent one. If a future release adds separate requirements, follow that release rather than this snapshot.

Before continuing, close sensitive work and make sure you can reopen the official Codex app normally. Keep the restore instructions on this page available in another browser tab.

Download from the original repository

Open the Codex Theme Hub repository and use its maintained source links. Use GitHub’s Code → Download ZIP option only when the repository instructions direct you to download that repository. Do not download a repackaged archive from a theme gallery, file-sharing service, or unofficial mirror. This site never hosts the installer.

After downloading a ZIP, extract it to a normal user-owned folder. Open the extracted repository and locate the macos directory. The scripts, tests, presets, notices, and README should remain together; moving a single script out of that directory can break relative paths and makes review harder.

Review at least these upstream files before installation:

• macos/README.md for current requirements and behavior.
• macos/scripts/install-dream-skin-macos.sh for the actual install path and checks.
• macos/LICENSE and macos/NOTICE.md for software and asset terms.
• The repository history for changes after July 17, 2026.

Optional pre-install checks

The macOS README provides a test command that uses the installed Codex or ChatGPT bundled Node runtime. In Terminal, change into the repository’s macos folder first, then run:

./tests/run-tests.sh

These tests are optional in the upstream quick start, but they are useful when you downloaded source from a branch or are evaluating a recent change. A failing check deserves investigation before installation. Do not silence a failure by removing validation from the script.

If macOS refuses to execute a file downloaded from the internet, stop and verify that you are using the original repository and that the file contents match what you reviewed. Permission or quarantine behavior can change between macOS versions. Follow the current repository guidance rather than copying a broad xattr or chmod command from an unrelated forum; the upstream README currently does not instruct users to disable Gatekeeper or remove quarantine recursively.

Install the studio to its stable path

From inside the macos directory, the source-checked command is:

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

The --no-launch option installs the studio without immediately launching a theme session. That gives you a clean point to review what was placed on disk. The current project documents these locations:

Purpose	Current documented location
Engine	~/.codex/codex-dream-skin-studio
State, logs, and user images	~/Library/Application Support/CodexDreamSkinStudio
Theme backup	theme-backup.json under the Application Support directory

The installer also creates Desktop launchers for starting or reapplying the skin, customizing the image, verifying the session, and restoring the official appearance. Their visible names are currently Codex Dream Skin.command, Codex Dream Skin - Customize.command, Codex Dream Skin - Verify.command, and Codex Dream Skin - Restore.command.

The project says the installer discovers the official com.openai.codex application, validates its signature, Team ID, architecture, and bundled Node, and then prepares a user-level launchd setup. If those identity checks fail, do not modify the installer to accept an arbitrary Electron application. Confirm that the official app is installed and has been opened at least once.

Apply a theme

A fresh install currently seeds a neutral abstract preset named Midnight Aurora. To switch explicitly to that source-provided preset from Terminal, use the stable installed path:

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

You can also double-click Codex Dream Skin.command to start or reapply the active theme. If you want to import your own pure background, use Codex Dream Skin - Customize.command or run the current customize script from the stable installation:

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

Use a clean background image, not a screenshot of a themed interface. The current upstream macOS image guidance accepts formats readable by macOS, including PNG, JPEG, HEIC, TIFF, and WebP, and recommends a 2560 × 1440 master. Its prepared-file checks currently cap an injected image at 16 MB, 16,384 pixels per side, and 50 megapixels. Confirm these limits again if you are reading this after the last-checked date.

Place the main visual subject away from native controls. The upstream composition guidance currently recommends keeping much of the left side calm and placing a distinct subject toward the right without touching the edge. Our local theme preview can help you test that idea without uploading the file.

Verify the result

Run Codex Dream Skin - Verify.command from the Desktop launchers created by the installer. Then perform a manual check in the official Codex app:

1. Confirm the sidebar, project list, task controls, and prompt composer remain visible.
2. Open a normal task and verify that text contrast remains comfortable.
3. Use keyboard focus to make sure visible focus indicators are not lost in the artwork.
4. Resize the window and check for cropping that hides important image content.
5. Confirm the selected image contains no fake controls, logos, watermarks, or readable text that could be confused with the app.

The repository says the injector only accepts a local debug port when it belongs to Codex or a legitimate child process and injects only into expected app:// renderer targets. Verification still matters because upstream interface changes can alter selectors or visual stacking without changing the install process.

Optional menu bar control

The project currently offers an optional SwiftBar menu-bar flow. From the macos source directory, the documented installer is:

./Install\ Menu\ Bar.command

After setup, the repository says a 🎨 Skin menu can apply, pause, import, and switch themes. This control is optional. You can use the Desktop launchers without adding it.

Restore the official appearance

Use Codex Dream Skin - Restore.command, created on the Desktop by the installer. Allow it to stop the recorded injector and restore the saved base appearance. The current project says restore operations validate the recorded process identity, executable, script path, and start time before stopping a job. It also performs guarded configuration replacement while Codex is closed.

After restoring, reopen Codex through its normal official launcher and check the sidebar, home view, a task, and the prompt composer. If the standard appearance has not returned, do not delete random files under ~/.codex or Application Support. Review the latest upstream restore documentation and use the dedicated restore guide to collect the right evidence.

Troubleshooting

The installer cannot find Codex

Open the official Codex Desktop app normally, complete any first-run setup, close it, and confirm ~/.codex/config.toml exists. Then rerun the unmodified installer. A missing configuration file is one of the current upstream prerequisite checks.

Runtime validation fails

Do not substitute a downloaded Node binary or remove the signature check. Make sure the official Codex or ChatGPT application is intact and current, then compare the error with the latest repository issues.

The theme starts but a control is missing

Restore the default appearance first. Codex interface updates can change layout or stacking. Check the upstream commit history and open issues for a compatibility update before reapplying the theme.

The background is too bright or busy

Choose a calmer source, move the focal point, or increase panel opacity in the theme workflow. Avoid solving every problem with heavy blur; editing the source image usually produces a cleaner result.

You need to report a bug

Use the repository’s issue template and provide the macOS version, Codex version, theme tool commit, installation method, exact error, relevant sanitized logs, and reproducible steps. Never attach API keys, authentication data, private conversations, or an entire unreviewed configuration file. The support guide provides a copyable reporting template.

The most reliable rule is simple: install from the original source, keep the project’s restore launcher available, and treat every Codex or Dream Skin update as a reason to recheck the documentation.

Related guides

Install a theme on Windows →Restore the default appearance →Troubleshoot a Codex theme →