You searched for "codex theme" and landed in a confusing place. Half the results talk about a terminal command, the other half show screenshots of a polished desktop app, and none of them explain the difference. Here is the reason: "Codex" is three different products, and each one themes differently. This guide sorts them out in one minute, then shows what is actually possible in each — with links to the official docs and the GitHub issues where the limits come from.
Full disclosure up front: this article is published by the GptSkin team. GptSkin themes the Codex desktop app only — not the CLI — and we will be explicit about that line throughout, because installing the wrong tool helps nobody.
One Minute: Which Codex Are You Running?
- Codex CLI — the agent that runs in your terminal as a text-based UI (TUI). You launch it with
codexin a shell, and everything happens inside the terminal window. - Codex desktop app — the standalone graphical app for macOS and Windows, with chat panels, settings windows, and a mouse.
- Codex VS Code extension — Codex living inside VS Code as an extension panel.
If someone tells you to "just run /theme" and you cannot find a command line anywhere, you are on the desktop app. If a blog shows a beautiful image background and you live in the terminal, that screenshot was not taken in the CLI. Same brand, different products, zero overlap in how theming works.
Codex CLI Themes: Syntax Highlighting, Nothing More
In the CLI, the official story is narrow and precise. The /theme slash command is documented with exactly one job: "Choose a syntax-highlighting theme." It changes how Markdown code blocks and diffs are colored in the transcript — not the interface around them.
Customizing CLI syntax highlighting with .tmTheme
You can go beyond the built-in options with TextMate theme files, per the CLI customization docs:
- Get a
.tmThemefile — thousands exist in the TextMate and VS Code ecosystem. - Drop it into
$CODEX_HOME/themes(on most setups,~/.codex/themes). - Pick it with
/theme, or set it persistently via thetui.themefield in your config file (see the config reference).
That is the full extent of official CLI theming.
What the CLI cannot theme: its own interface
The TUI's own colors — the prompt, the borders, the status line, the background — are not officially customizable. And this is not an obscure gap; it is one of the most-discussed limitations in the Codex issue tracker:
- Issue #1618 asks for TUI color control and has drawn 31 comments.
- Issue #2020 reports the prompt is nearly invisible on light terminal backgrounds.
- Issue #6531 requests high-contrast presets, and issue #21130 asks for semantic colors.
If recoloring the CLI interface is what you want, the honest answer today is: watch those issues, and be skeptical of any tool claiming it can do it cleanly. GptSkin does not theme the CLI — we only work on the desktop app, and we would rather tell you that plainly than have you install the wrong thing.
Codex Desktop Themes: Real Interface Theming (and One Gap)
The desktop app is where theming gets real. Since March 12, 2026, the official app ships native theming under Settings → Appearance, per the official changelog:
- a base theme to start from,
- independent accent, background, and foreground colors,
- font selection,
- theme sharing, so a setup can be exported and imported.
For solid-color, font-level customization, the native settings genuinely cover it — zero installs, officially supported.
The one thing Settings → Appearance does not do is put an actual image behind your workspace. That gap is where third-party tools live. The most-starred open-source option is Dream Skin, and there is GptSkin — ours — which applies image themes locally through an open-source Skill:
- 6 free presets, no account needed — for example Dark Void for late-night work or Minimal Light for bright rooms. After a one-time Skill install (see the installation guide, macOS and Windows, Node.js 20+), applying one is a single command:
node ~/.codex/skills/gptskin-theme/scripts/apply-theme.mjs --preset dark-void- Custom image themes: your own photo or artwork becomes the backdrop, 20 Credits per new theme (one-time Credit packages, not a subscription); reapplying a saved theme is free.
- One-command restore: say
Restore the default Codex themeand every injection is removed.
What About the VS Code Extension?
Short answer: the Codex VS Code extension follows VS Code's own theme mechanism. If that is your setup, change themes the VS Code way — it is not what this article (or GptSkin) is about.
The Decision Table: What You Want → Where to Go
| What you actually want | Where to go |
|---|---|
| Prettier code blocks and diffs in the terminal | CLI: /theme, or a .tmTheme in $CODEX_HOME/themes |
| Recolor the CLI's own interface (prompt, borders, background) | Not officially possible — follow issue #1618 |
| Solid colors and fonts in the desktop app | Built-in: Settings → Appearance |
| An image background in the desktop app | Third-party: GptSkin (showcases) or Dream Skin |
| Theme Codex inside VS Code | VS Code's own theme settings |
FAQ
Can /theme change the CLI's interface colors?
No. /theme only chooses a syntax-highlighting theme for Markdown code blocks and diffs — that is the literal extent of its official documentation. The TUI's own colors are not officially customizable; community demand for that is tracked in issue #1618.
Do CLI themes and desktop themes work interchangeably?
No. They are separate mechanisms in separate products. A .tmTheme file only affects syntax highlighting in the CLI; the desktop app's Settings → Appearance and image themes like GptSkin's apply only to the desktop interface.
How do I use a .tmTheme file in Codex CLI?
Place the file in $CODEX_HOME/themes (usually ~/.codex/themes), then either select it with the /theme command or set the tui.theme field in your config — both covered in the customization docs and the config reference. Remember: it changes syntax highlighting only, not the TUI itself.
Can the Codex desktop app use my own image as a background?
Not natively — Settings → Appearance covers colors and fonts, not images. Third-party tools fill the gap: GptSkin builds a theme from your image for 20 Credits (and 6 presets are free), applied locally by an open-source Skill with a one-command restore. Setup steps are in the installation guide.
Does GptSkin work in the CLI or the VS Code extension?
No — GptSkin themes the Codex desktop app on macOS and Windows only. It does not touch the CLI's TUI or the VS Code extension. If those are your environment, the decision table above points to the right options.
The Bottom Line
"Codex theme" is an ambiguous search because Codex is three products with three theming stories: the CLI highlights syntax, the desktop app restyles its interface natively, and image backgrounds are a third-party job. If the desktop app is your home and you want a backdrop nobody else has, start with a free preset — then browse the showcases to see what other Codex users are running.
GptSkin is an independent product and is not affiliated with, endorsed by, or officially connected to OpenAI. "ChatGPT" and "Codex" are trademarks of OpenAI, used only to describe compatibility.
