fix(terminal): let Claude use truecolor so its themed backgrounds render

[irisitymichaelgrundberg]

Summary

Claude draws the user's own messages as a block of background color. Inside a Codeman pane that block is invisible, and no Claude theme can change that. This exports COLORTERM=truecolor for Claude, which is what the other seven CLIs already do.

The problem

Two things combine. tmux hands each pane TERM=screen, which supports-color reads as 16 colors, and Claude's registry entry deleted COLORTERM on top of that. Claude then quantizes every RGB color its theme asks for down to the basic palette.

Measured with the chalk version Claude bundles, at 16 colors:

theme color	16-color output	result
rgb(55, 55, 55) (built-in dark)	ESC[40m	the terminal's own black
rgb(28, 48, 84) (a custom theme)	ESC[40m	the terminal's own black
rgb(240, 240, 240) (built-in light)	ESC[47m	white

Every dark background lands on ESC[40m, so the block is emitted and paints the terminal's background over itself. Claude's *-ansi themes work, because they name colors like ansi:blackBright and skip the conversion entirely.

Detected levels, same library:

TERM	COLORTERM	level
screen	unset	1 — 16 colors
screen	truecolor	3 — 24-bit

Why this reverses #3

#3 added unset COLORTERM in February, reporting that truecolor caused "gray/white backgrounds appearing where they shouldn't" in xterm.js, and citing xtermjs/xterm.js#484. Three things have changed or were already true:

• xterm.js closed #484 on 2019-04-07, seven years before fix: unset COLORTERM to fix xterm.js rendering issues #3 cited it.
• Codeman now depends on @xterm/xterm ^6.0.0, which renders 24-bit color.
• TmuxManager sets terminal-overrides ",*:Tc" on its own tmux server (src/tmux-manager.ts), so 24-bit color already reaches the browser for the CLIs that ask for it.

I want to flag one reading honestly, because I cannot prove it. Suppressing truecolor makes Claude's dark block collapse into the terminal background and disappear. If that is what the reporter saw go away, then the symptom was Claude's user-message block working as designed, not an xterm.js defect.

Changes

• src/config/cli-registry/stock.ts — Claude's entry exports COLORTERM=truecolor. CLAUDECODE stays unset.
• src/session-cli-builder.ts — buildClaudeEnv(), the direct-PTY fallback taken when mux creation fails, now reads the same registry entry as the tmux pane and its attach client. It previously deleted COLORTERM from a hand-maintained list of its own, which would have left the fallback contradicting the entry.
• docs/architecture-invariants.md — a Terminal colour env paragraph under Session launch modes, where a reader looking up Claude will find it. The sentence it replaces sat under a heading listing only the non-Claude CLIs.
• test/tmux-manager.test.ts — pins the new behaviour beside the existing OpenCode assertion.
• A changeset.

Claude does not unset NO_COLOR, unlike the other seven truecolor CLIs. The bug does not need it, and unsetting it would override a preference the user set deliberately. The inconsistency is intentional and the entry's comment says so.

An SSH-remote pane is not covered. buildRemoteLaunchCommand() carries no env exports at all, so a remote Claude session keeps the old rendering. That predates this change, and the invariants doc now states it rather than implying every pane is covered. Docker panes take COLORTERM=truecolor from the hardcoded envCreate/execEnv, which apply to every mode including the two the registry says must unset it — also pre-existing, also now documented.

Verification

• npm test — 6870 passed, 12 skipped, 0 failed.
• npm run typecheck, npm run lint, npm run format:check, npm run check:frontend-syntax all clean.
• The new test bites: reverting the registry entry fails it with expected [...] to include 'export COLORTERM=truecolor'.
• Called buildClaudeEnv() with NO_COLOR=1 and CLAUDECODE=1 in the parent env: returns COLORTERM=truecolor, no CLAUDECODE, and NO_COLOR preserved.
• Called the real buildEnvExports against a build: a Claude pane emits unset CLAUDECODE, export COLORTERM=truecolor. OpenCode still emits unset COLORTERM, unchanged.
• Ran it for a day on a live install, then opened a fresh session on the stock dark theme. The user-message block renders as the intended grey, and nothing shows gray or white where it should not.

🤖 Generated with Claude Code

[Ark0N]

Merged, thank you, and thank you for flagging the reading you could not prove rather than quietly leaving it out. That paragraph is the reason I went and measured instead of taking the table on trust.

I verified your colour maths by replicating ansi-styles' rgbToAnsi256 and ansi256ToAnsi. At level 1 your table is exactly right: rgb(55,55,55) and rgb(28,48,84) both land on ESC[40m, and rgb(240,240,240) on ESC[47m.

But the premise does not hold on tmux 3.2 or newer, and that changes the framing rather than the change. Measured on this box: tmux 3.4, default-terminal sitting at its compiled default of tmux-256color, and a live claude pane reporting TERM=tmux-256color. That is supports-color level 2, where those same colours become 48;5;237 and 48;5;60: visible greys and blues, not the terminal background. The invisible block needs TERM to resolve to a 16-colour entry, so tmux older than 3.2, or a ~/.tmux.conf setting default-terminal screen. Codeman passes tmux no -f, so it does read the user's conf, and that is presumably how you are hitting it. Worth confirming with a tmux -V on the install you tested, because it would be useful to have the real trigger written down.

The other half is that PR #3's own body says its goal was to "fall back to standard 256-color mode which xterm.js fully supports", which is what actually happens on a modern tmux. So this does not so much reverse #3 as make it obsolete.

None of that argues against the change. It argues for a different headline, and since the changeset becomes the changelog I rewrote it in c2114615 rather than ship "invisible on every install" into CHANGELOG.md. It now leads on the argument that survives every tmux version: claude was one of two entries (with shell and opencode) not asking for truecolor while twelve do, so the block rendered as an approximation of the theme colour at best, and the collapse-to-black case is called out as TERM-dependent with the two triggers named. The invariants paragraph got the same correction, plus a note to pair a future report here with the reporter's tmux -V and their pane's real TERM.

One real fix, in the same commit. buildClaudeEnv() applied the registry's unset/exports after the whole env object was built. unset is config (a ~/.codeman/clis.json entry replaces the array wholesale), so an entry naming CODEMAN_HOOK_SECRET_FILE or PATH would strip it on the direct-PTY path, while buildEnvExports() structurally cannot do that because it emits ...cliEnv ahead of export CODEMAN_MUX=1. The block now runs first and Codeman's own keys are assigned on top, so the two paths agree. Latent today, since nothing writes clis.json this release, but the whole point of the refactor was that the fallback cannot drift from the pane.

Not changed, your call if you want a follow-up: the engine-value resolver is now in two places with different coverage (2 of 7 sources here, 3 of 7 in tmux-manager), and neither evaluates when. Correct today because claude declares a literal. A plain env.COLORTERM = 'truecolor' would have avoided it, at the cost of the drift property you were buying. I left your version.

Unrelated and pre-existing, in case it interests you: the live server has ten duplicate *:Tc entries in terminal-overrides, because set-option -sa appends on every call.