FAQ
Codex Theme FAQ
Answers to common questions about installing, applying, restoring and update breakage.
How do I install a Codex theme?
Use the open-source Codex Dream Skin. On macOS, double-click Install Codex Dream Skin.command in the repo (or run ./scripts/install-dream-skin-macos.sh); the engine installs to ~/.codex/codex-dream-skin-studio/ and creates four desktop launchers. Note: macOS needs no separate Node — it reuses the signed Node bundled in Codex.app. On Windows, install Node.js 22+ first, then run scripts/install-dream-skin.ps1. See the tutorial on this site.
Can I change the Codex theme on Mac?
Yes, and macOS has the fullest customization. The Codex desktop app is an Electron app, and on macOS you can pick your own background image and customize colors (via the Customize command), then theme it through local CDP injection. Windows currently only ships a fixed pink-purple skin and can't yet customize the image.
What should I do if the Codex theme isn't applied?
Codex must launch with the debug flags (the script adds --remote-debugging-port=9341 automatically). Fully quit Codex (don't just minimize), then double-click Start Codex Dream Skin.command to relaunch and inject; confirm port 9341 is free (it auto-scans up to 9441 on collision). If some text is unreadable, re-run Customize and adjust the --accent/--secondary/--highlight colors.
The skin broke after a Codex update — what now?
A Codex version update may briefly break the skin, since the engine depends on the app's interface structure, which can change. Double-click Restore Codex Dream Skin.command to revert to the default UI in one click, or Install + Start again to re-apply; the engine re-detects the official Codex bundle on every launch, supports updates, and won't interfere with Codex's normal updates.
Does theming modify Codex's official bundle on my machine?
No. Theming only injects CSS/JS over the local loopback address 127.0.0.1 to overlay decoration on the interface — it never modifies Codex's official .app bundle or code signature, so it won't affect future official updates and never touches your code or project files.
Is Codex theming safe?
Theming stays entirely on your machine's local loopback — no external network calls, no uploaded data, just a visual layer over the interface. One caveat: CDP is unauthenticated on loopback, so don't run untrusted local software while the theme is active, and use Restore to close the debug port when done. Please follow Codex's terms of service and prefer open-source, auditable scripts.
How do I restore Codex's default UI?
On macOS, double-click Restore Codex Dream Skin.command on your desktop (it runs restore-dream-skin-macos.sh --restore-base-theme --restart-codex) to clear the injection and return to the default UI in one command without affecting future updates. On Windows, run powershell -File windows/scripts/restore-dream-skin.ps1 -RestoreBaseTheme. Use it before upgrading Codex or whenever a theme misbehaves.
Are the Codex themes on this site free?
The theme palettes showcased here are free to reference and use — color and text config aren't copyrightable, so you can generate them yourself from the palette and tutorial. If you'd rather not source images and tune colors yourself, our commission service can generate a bespoke theme pack end to end.
How can I make my own Codex theme?
On macOS, run the Customize command: pick a background image, enter a name and three colors (--accent/--secondary/--highlight), and the script writes theme.json and auto-applies it. For Miku, for example: customize-theme-macos.sh --image miku.png --name "Hatsune Miku" --accent "#39C5BB" --secondary "#FF61C7" --highlight "#00B4DC". Tweak colors and re-run, or hand-edit theme.json, until you're happy.
Where can I download Codex theme packs?
A key fact first: the open-source project has no theme store and no 'import theme' command. A theme is simply a folder containing a theme.json (colors + text config) and a background image. So there are two ways to get one: ① generate it yourself with the Customize command (pick image + colors); ② get someone's theme.json + image folder, drop it into ~/Library/Application Support/CodexDreamSkinStudio/themes/<name>/, then switch with switch-theme-macos.sh --id. This site provides each theme's palette so you can fill it in directly.
Which operating systems does Codex theming support?
macOS and Windows are supported (the Codex desktop app is an Electron app; there's no Linux build). They differ: macOS lets you customize the background image and colors (reusing Codex's bundled Node, no extra install); Windows currently ships a fixed pink-purple skin, needs Node.js 22+ installed, and can't yet customize the image.
Can I customize the Codex desktop pet too?
Yes — the Codex desktop pet is also customizable. You can pair the pet with a theme for a coordinated look. We'll gather pet-related resources here later, so watch the gallery and resources page for updates.