DexThemesMake Codex yours Open DexThemes

Guides · DexThemes

Codex App Themes vs CLI Themes

DexThemes codex-theme-v1 strings target Codex desktop Appearance, while the Codex CLI uses the /theme picker and optional .tmTheme files for terminal syntax highlighting.

Written by Daeshawn Ballard Updated 837 words
Open DexThemes Read as Markdown

Codex desktop themes and Codex CLI themes are separate customization systems. A DexThemes codex-theme-v1: string changes the desktop app's Appearance after you import it. The CLI /theme command changes syntax highlighting in the terminal UI and can load a TextMate .tmTheme file.

Do not paste one format into the other. DexThemes is community-built and is not affiliated with OpenAI.

Codex desktop Appearance themes

A DexThemes app import carries a small appearance payload:

  • A dark or light variant.
  • Main surface and foreground colors.
  • An accent color.
  • Added, removed, and skill semantic colors.
  • A contrast parameter.
  • UI and code font names or null.
  • A registered code-theme family ID.
  • An opaque-windows preference.

The copied value begins with codex-theme-v1:. To use it, open Codex Settings, choose Appearance, choose Import theme, paste, review, and approve. The official desktop settings documentation says Appearance can change the base theme, accent, background, foreground, and UI and code fonts, and can share a custom theme.

This theme affects the graphical Codex workspace. DexThemes can prepare and copy the payload, but it does not claim a verified public route that silently applies it.

Codex CLI syntax themes

The CLI theme controls syntax highlighting for fenced Markdown code blocks and file diffs in the terminal UI. According to OpenAI's official CLI customization guide:

  1. Run /theme in an interactive Codex CLI session.
  2. Preview a theme in the picker.
  3. Confirm it to save the selection to tui.theme in $CODEX_HOME/config.toml.

For a custom CLI theme, place a .tmTheme file in $CODEX_HOME/themes, then choose it from /theme.

A .tmTheme file is a TextMate-style syntax-highlighting definition. It can describe many token scopes and editor colors. It is not a codex-theme-v1 string, and the CLI customization documentation does not describe the desktop Appearance import as a CLI theme source.

Why direct conversion is incomplete

The two formats express different things.

The desktop import has broad application colors plus a codeThemeId that chooses an existing syntax-theme family. It carries only three named semantic colors beyond the main surface, foreground, and accent.

A .tmTheme can assign colors to many token scopes, such as comments, strings, keywords, types, and functions. It does not inherently describe every piece of graphical app chrome represented by a desktop custom theme.

As a result:

  • Converting a desktop import to .tmTheme requires designing or mapping token scopes that are absent from the source payload.
  • Converting a .tmTheme to a desktop import requires selecting a small set of representative app colors and a code-theme family.
  • A mechanical conversion may preserve a general mood but cannot guarantee visual equivalence.

If you build a companion theme, treat it as a coordinated design pair and test each surface independently.

Choose the right workflow

Use a DexThemes app import when you want to change the graphical Codex workspace, including its main surface, foreground, accent, semantic colors, and optional fonts.

Use /theme when you want to change syntax highlighting in the Codex CLI without redesigning the desktop app.

Use a custom .tmTheme when the CLI picker does not provide the token palette you need and you are comfortable authoring TextMate scopes.

Use both systems when you work in both the app and CLI. Choose visually related palettes, but save and move their artifacts separately.

Common mistakes

Putting the import string in the CLI themes folder

The CLI looks for .tmTheme files there. A plain codex-theme-v1: string is not that format. Keep the string in a text note or import it through desktop Appearance.

Pasting a .tmTheme file into Appearance

The Appearance importer expects the Codex theme import contract, not an XML or property-list TextMate document. Select the .tmTheme through the CLI /theme picker instead.

Assuming settings automatically mirror

The official CLI guide says its choice persists to tui.theme. The desktop guide describes Appearance controls. These are different settings surfaces. Verify each after moving computers, changing $CODEX_HOME, or updating Codex.

Treating a codeThemeId as a .tmTheme filename

The app import's codeThemeId is a registered family ID. It is not necessarily the filename of a bundled syntax definition. Use a DexThemes-generated string or a canonical ID from the format reference.

Keep a portable pair

For a theme you use in both surfaces, archive:

  • One desktop import string for each app variant.
  • The custom CLI .tmTheme file, if you created one.
  • A short note naming the CLI picker selection when you use a built-in theme.
  • Screenshots or color notes only as supporting references, not as installable artifacts.

Never include account tokens, private paths, repository details, or other secrets in the theme files or sharing notes.