Skip to content
CodexTheme.dev logoCodexTheme.dev
All posts
Tutorial2026/07/17

How to Import a Custom Theme in the Codex Desktop App

A version-aware checklist for importing a native Codex theme, checking readability, and restoring the previous appearance.

A precise lime theme swatch moving into an obsidian frame

Quick answer

Open Codex Settings, go to Appearance, use the custom theme import control, paste the complete codex-theme-v1: share string, review the preview, and apply it. The exact control label may change between app builds.

These steps were reviewed with Codex App 26.707.72221 on macOS on July 17, 2026.

Before you import

Confirm that the item is a native theme, not an external Skin installer. A native theme string is plain appearance data. It should not ask you to run shell commands, enable a debugging port, or download an executable.

Check the source, verified date, tested platform, and Codex build on the theme page. Save the name of your current built-in theme so you have a simple return point.

Import and verify

  1. Open a published theme page in the theme catalog.
  2. Use Copy theme on the theme page to copy the share string.
  3. In Codex, open Settings > Appearance.
  4. Paste the complete share string into the import field.
  5. Do not trim or edit the prefix or JSON payload.
  6. Review the light or dark variant before applying.

After applying, inspect headings, body text, muted labels, buttons, selected states, diff additions, diff removals, skills, and fenced code. Restart the app and verify that the theme persists.

Common failures

An invalid-string error usually means the prefix or JSON was changed. A variant mismatch means the share string and active light/dark import target differ. A code-theme mismatch means the referenced highlighting family is unavailable in that app version. A clipboard failure can be bypassed by selecting the returned string and copying it manually.

If the result is unreadable, choose a built-in Codex theme immediately. Native appearance changes do not require an external cleanup script. For broader troubleshooting, read how to reset or remove a theme.

All posts