Make your own agent theme, from scratch

Backgrounds first. The accent can wait.

The rookie move is falling in love with an accent color and forcing everything else around it. Do the opposite. Four of the thirteen tokens are background layers — the window surface, a slightly different panel surface for sidebars and statuslines, a code-block background, and a border — and they decide whether the theme feels solid or muddy before a single character of syntax shows up.

For dark themes, stay off pure black. Ember Shift, our house dark, runs #101012 for the window, #17171a for panels and #0b0b0d behind code: three near-identical grays, yet your eye separates panel from window with no border doing real work. Light themes want warmth more than brightness — Paper Terminal sits on #f7f4ec, closer to book paper than to a lightbox. Whichever direction you go, keep the code background a half-step from the surface, and let the border whisper. If you notice the borders, they are too loud.

Two text colors carry the whole day

text is what you read for hours; textMuted is timestamps, filenames and secondary chrome. Body text against the surface is where the WCAG 4.5:1 contrast ratio genuinely applies — below it, a long session turns into squinting. Muted text should land near 3:1 on purpose. Push it higher and nothing reads as secondary anymore; the hierarchy collapses into one flat voice.

The syntax four: separate by hue, not brightness

string, keyword, func, comment. The classic quartet, and the classic mistake is making them four brightnesses of one hue — it looks disciplined in a screenshot and turns to porridge in a real transcript. Separate them by hue instead. Dracula's green strings, pink keywords and purple accent survived porting to four hundred apps precisely because no two of them live near each other on the wheel.

Two working rules. Comments recede — reusing your muted text value is common and honest. And strings matter more here than in an editor: agent interfaces tend to reuse the string green for diff-added lines (ours does), so this color will mark every line your agent writes into your code. Pick a green you can live with.

Error and warning are load-bearing

In an editor they are squiggles. In an agent window, error is the color of a failed test run and of diff-removed lines, and warning is the color of the prompts that ask before something irreversible — the exact moments you must not misread. Keep error in the red family and warning in the amber family; decades of interfaces trained everyone on that grammar, and a theme is the wrong place to fight it. Check both against the main surface, and keep warning away from your accent, or a caution will dress like a button.

One accent, one job

The accent marks the cursor, your own messages and primary buttons. It is the theme's signature, so it gets the personality — Ember Shift's #ff9e3d ember, Neon Garden's #59e3a7mint. The test is practical: scroll back through a long transcript and your own prompts should pop at arm's length. If you have to hunt for them, the accent is too shy.

Contrast: the folk tests you will actually run

The numbers to remember: 4.5:1 for body-size text, 3:1 for large text and UI chrome. Nobody opens a color-science suite at 11pm, so use the tests that actually get run. One — a free online contrast checker: paste two hexes, read the ratio. Two — the squint test: squint until the screen blurs, and whatever disappears first was below the bar. Three — the grayscale test: macOS and Windows can both render the screen in grayscale from their accessibility settings, and hue cannot rescue you there. Whatever survives in gray is real contrast.

Run the pairs that actually fail: text on surface, comment on the code background, error on surface. Comment-on-code is the one that ambushes people — both values drift dark during tuning, and suddenly every code comment is ghost text.

Iterate in the preview tool

Paste whatever you have into our paste-and-preview tool — raw JSON, loose hex values, a codex-theme-v1:… string. It parses in your browser, uploads nothing, maps what it recognizes onto a full agent-window mock and lets you nudge every token from there. The mock includes a diff block on purpose. Ten rounds takes ten minutes, and the version that passes the squint test in the mock is the version worth installing.

Land it in Codex and Claude Code

Codex app: open the appearance settings and create a custom theme with your thirteen values — or write yourself a short install instruction: paste the hexes, tell the agent to change appearance settings only and to report everything it touched. That reporting line is the whole trick; the reply becomes your undo list. It is how every install prompt on this site is written, and why.

Claude Code: run /theme — from v2.1.118 the flow can create custom themes. On older versions, set your palette at the terminal level and pick the dark-ansi or light-ansipreset, which inherit the terminal's sixteen ANSI colors. Step-by-step walkthroughs of both routes: the Codex guide and the Claude Code guide.

Share it with your team

A finished theme is a paragraph of JSON. Send teammates the thirteen tokens; they paste the blob into the preview tool to see it before touching anything, then apply it with the same install-instruction pattern. No files, no extension store, no versioned artifacts to babysit — one of the quiet advantages of themes this small.