Agent theme troubleshooting: the six usual breakages

1. The importer rejected my theme string

Theme importers validate structure strictly, and a string that traveled through a chat app has usually been chewed on the way: line-wrapped, truncated at a length limit, or had its straight quotes "smartened" into curly ones. One missing field can fail the whole import, sometimes without a useful message.

Fix in escalating order. Re-copy the entire string from the source, in one piece, no hand edits. Paste it into our preview tool first — it parses loosely (full strings, raw JSON, even scattered hex values) and shows which tokens it recognized, which tells you whether the string or the importer is at fault. If the importer still refuses a string the preview reads fine, stop arguing with it: the install-prompt route from the Codex guide applies colors through appearance settings and bypasses import validation entirely.

2. Dark and light got crossed

Symptoms: pale text on a pale ground, or one black rectangle in an otherwise light interface. Cause: the theme defines one polarity and the app is rendering the other — most shared themes ship a single variant. Flip the app's appearance mode to match the theme, or pull the sibling variant from the gallery; the browse pages filter by dark and light for exactly this errand.

The sneaky version: everything looks wrong only in the evening. That is usually the operating system switching appearance modes at sunset underneath a single-variant theme — check whether your app follows the system setting. Pin the app to the theme's polarity, or install both variants of one family and let the handoff happen in matching colors.

3. I can't read diffs anymore

Diff colors are not independent paint. Agent interfaces typically derive diff-added from the string green and diff-removed from the error red — ours does, and most do. Tune either token toward your background (a tasteful desaturation, say) and review views quietly collapse. Added lines invisible? Suspect string. Removals gone? Suspect error.

The test is a squint: blur your eyes at a diff and both stripes should still be obvious. If not, push those two tokens' luminance away from the surface until body-text contrast (the 4.5:1 neighborhood) comes back, or copy the values from any stock palette in the gallery. Our theme-building guide has the folk contrast tests, and the preview tool's mock diff exists for exactly this rehearsal — paste, look, fix, before anything touches the app.

4. Take me back to default

Shorter than you fear. Codex app: appearance settings always keep the built-in presets — select one and you are stock. Claude Code: run /themeand pick a built-in. If an install prompt made the changes, the agent's report of what it touched is your undo list; or skip the list and tell the agent to restore the default appearance — it is one sentence. Color-token theming keeps no hidden state anywhere else, which is the whole reason it sits on the green tier of the safety ladder.

One catch: reset the layer you actually themed. If a window's look came from a terminal profile feeding the ANSI presets, resetting the app changes nothing — the colors live in the terminal, and the terminal will keep serving them. Reset order for the thoroughly lost: app preset first, terminal profile second, injection engine (if any) last.

5. Terminal ANSI vs app theme: who wins where

A desktop agent app owns its whole window; your terminal has no vote there. Claude Code is the opposite — it renders inside a terminal, so the stack matters. Its regular themes paint their own colors on top. The dark-ansi and light-ansipresets instead inherit the terminal's sixteen-color ANSI palette. And the window background always belongs to the terminal, whatever the preset.

Which explains the classic mess: a light terminal profile under a dark Claude Code preset, or the reverse — half the interface assuming a polarity the other half refuses. Align the two layers by hand, or commit fully: put your palette in the terminal profile and run the ANSI presets, so one layer decides everything.

6. Where do these settings actually live?

The rough map. The Codex app's appearance lives in the app's own settings. Claude Code's theme choice persists in its user-level settings. Terminal palettes live in each terminal's profile. And injection skins keep their configuration in their own engine, outside every appearance setting — which is why removing one is the engine's job, not a settings toggle; the safety page covers that tier. Exact file names and paths move between versions, so treat your version's settings UI as the source of truth over any blog post — including, cheerfully, this one.