Codex Theme Format Reference

The current DexThemes import format is the literal prefix codex-theme-v1: followed by one JSON object. That object contains a registered codeThemeId, one normalized theme object, and one variant set to dark or light.

This page documents the DexThemes contract verified against the Codex build named in testedWith. It is not a public compatibility guarantee from OpenAI. Codex owns the importer and can change accepted values or rendering in later builds.

DexThemes is community-built and is not affiliated with OpenAI.

Canonical example

codex-theme-v1:{"codeThemeId":"codex","theme":{"accent":"#0169cc","contrast":60,"fonts":{"code":null,"ui":null},"ink":"#fcfcfc","opaqueWindows":true,"semanticColors":{"diffAdded":"#00a240","diffRemoved":"#e02e2a","skill":"#b06dff"},"surface":"#111111"},"variant":"dark"}

Everything before the first { is the format prefix. Everything from { through the final } is JSON.

DexThemes emits compact JSON without decorative whitespace. JSON object key order should not be used as identity; field names and values define the payload.

Top-level object

The JSON object has three fields.

codeThemeId

codeThemeId is a string naming a registered Codex code-theme family that supports the selected variant.

"codeThemeId":"codex"

It is not a DexThemes catalog ID, display name, theme filename, or arbitrary path. A gallery theme named “GitHub Dark,” for example, can serialize the canonical family ID github.

The final import payload always contains one string. DexThemes source data can choose different family IDs for dark and light, but the serializer resolves the active variant before emitting the payload.

theme

theme is the normalized appearance object. It contains the active accent, contrast parameter, fonts, foreground, opacity preference, semantic colors, and surface.

variant

variant is exactly:

"variant":"dark"

or:

"variant":"light"

One import string carries one variant. A complete pair requires two strings and two imports.

Theme object fields

accent

accent is a six-digit hex color:

"accent":"#0169cc"

DexThemes source themes can offer an accents array with up to ten choices. The serializer resolves the selected accent and emits only that one color.

contrast

contrast is an integer from 0 through 100, inclusive:

"contrast":60

This is a Codex theme parameter carried by DexThemes. It is not a WCAG contrast ratio. Measure actual foreground and background colors independently.

fonts

fonts is an object with code and ui:

"fonts":{"code":null,"ui":null}

Each value is either a string of at most 100 characters or null.

"fonts":{"code":"Example Mono","ui":"Example Sans"}

Font strings name fonts; they do not embed files, grant licenses, or guarantee availability. null means the payload does not name that font. Codex and the operating system determine the effective fallback behavior.

The current DexThemes builder does not expose font fields and therefore emits null values. Some catalog themes can include explicit names.

ink

ink is the primary foreground color as six-digit hex:

"ink":"#fcfcfc"

Test it against surface for body text and small labels. A valid hex value is not automatically readable.

opaqueWindows

opaqueWindows is a boolean:

"opaqueWindows":true

When the source variant does not set this value, the current DexThemes serializer emits true. The import payload itself contains the resolved boolean.

Do not substitute quoted strings such as "true" or integers such as 1.

semanticColors

semanticColors contains three required six-digit hex values:

"semanticColors":{"diffAdded":"#00a240","diffRemoved":"#e02e2a","skill":"#b06dff"}

diffAdded colors addition-related content.
diffRemoved colors removal-related content.
skill colors skill or function-related content.

Codex decides where and how these values are rendered. Theme authors should keep the roles distinguishable and avoid relying on hue alone.

surface

surface is the main background color as six-digit hex:

"surface":"#111111"

It forms the primary contrast relationship with ink.

Hex color rules

Every color emitted by the current DexThemes validator must match:

#[0-9A-Fa-f]{6}

Valid examples include:

#111111
#A1B2C3
#00a240

The current contract does not accept three-digit shorthand, eight-digit alpha colors, named CSS colors, gradients, or CSS variables.

Current registered code theme families

The DexThemes contract currently recognizes these family and variant combinations.

Dark and light

absolutely
catppuccin
codex
everforest
github
gruvbox
linear
notion
one
raycast
rose-pine
solarized
vercel
vscode-plus
xcode

Dark only

ayu
dracula
lobster
material
matrix
monokai
night-owl
nord
oscurange
sentry
temple
tokyo-night

Light only

proof

This list is versioned evidence from the current DexThemes contract, not a promise that every Codex release has the same registry. Recheck after an app update if a formerly valid family is rejected.

Canonical legacy mappings

Older DexThemes entries used several internal syntax-theme filenames. The current source validator recognizes only these known aliases and emits the registered family:

github-dark-default maps to github for dark.
github-light-default maps to github for light.
gruvbox-dark-hard maps to gruvbox for dark.
one-dark-pro maps to one for dark.

New import strings should use the canonical emitted value. Do not infer new aliases from application bundle filenames.

DexThemes source data versus import data

A theme as stored or edited by DexThemes can contain more information than the Codex import:

Catalog id, name, summary, category, attribution, and dates.
Separate dark and light variant objects.
An array of selectable accents.
Sidebar and code-background preview colors.
Copy counts or community publication metadata.
A code-theme family selection for each variant.

The serializer selects one variant and emits only the supported import fields. In particular:

Theme name and author are not in the import payload.
sidebar is not a separate import field.
codeBg is not a separate import field.
The accents array becomes one accent.
Community or catalog metadata is not included.

Do not paste a DexThemes contribution file or API response directly into Codex Appearance unless it already contains the complete importString.

Current DexThemes validation behavior

Before producing a string, the shared contract checks:

Variant is dark or light.
The selected variant exists.
An accents value, when present in source data, is an array with no more than ten entries.
Every accent and required theme color is a six-digit hex value.
Contrast is an integer from 0 through 100.
Fonts are an object when present.
Font values are strings no longer than 100 characters or null.
opaqueWindows, when present in source data, is a boolean.
The code-theme family exists and supports the selected variant.

If validation fails, DexThemes returns no import string. Duplicate validation messages are collapsed in the current result.

That is DexThemes validation. Successful import and persistence in the installed Codex app remain separate evidence.

Safe inspection and editing

Prefer regenerating a string from DexThemes over editing compact JSON. If you must inspect it:

Verify the exact prefix.
Copy everything after the prefix into a JSON-aware editor.
Check the three top-level fields.
Check every theme color and type.
Use a canonical code-theme family.
Reassemble the prefix and complete JSON without adding outer quotes.
Import through Codex Settings, Appearance, and Import theme.
Verify the result in the installed app.

Do not add commands, URLs, secrets, repository data, or arbitrary keys. DexThemes does not emit them, and this reference does not claim how Codex handles unknown fields.

What this format does not configure

The app import format does not configure the Codex CLI syntax theme. The CLI uses /theme, persists tui.theme, and can load custom .tmTheme files from $CODEX_HOME/themes, according to OpenAI's official CLI customization documentation.

The import also does not:

Install font files.
Carry a theme display name or author.
Publish a theme to DexThemes.
Prove OpenAI endorsement.
Apply without user approval.
Guarantee matching rendering across machines.

OpenAI's official desktop settings documentation confirms the broader Appearance controls, including base theme, colors, UI and code fonts, and sharing. The codex-theme-v1 serialization details on this page are grounded in the current DexThemes source contract.