Inside tmux: Claude Code downsamples colors despite COLORTERM=truecolor

Summary

When Claude Code runs inside a tmux session, its rendered colors are noticeably dimmer/banded than the same Claude Code instance running directly in the host terminal — even with COLORTERM=truecolor propagated and tmux's truecolor passthrough verified working. Both Claude Code's UI elements and captured tool output appear affected.

Environment

• Claude Code: 2.1.143
• Host terminal: iTerm2 3.6.9 (macOS)
• tmux: 3.6a (homebrew)
• TERM outside tmux: xterm-256color
• TERM inside tmux: tmux-256color
• COLORTERM=truecolor propagated into the tmux session and visible on the claude process env (ps eww)

Repro

Run this truecolor gradient via Bash inside Claude Code, once in a Claude session started directly in iTerm2 and once started inside tmux:

\\\sh
awk 'BEGIN{for(i=0;i<77;i++){r=int(255-(i*255/76));g=int(i*510/76);if(g>255)g=510-g;b=int(i*255/76);printf "\033[48;2;%d;%d;%dm ",r,g,b}print "\033[0m"}'
\\\

• Direct claude (no tmux): 77 smooth color steps.
• Inside tmux: visibly banded, ~16–20 distinct color blocks.
• Plain tmux + zsh, no Claude Code: identical smooth 77-step gradient → tmux is passing truecolor through correctly.

So the downsampling is inside Claude Code's rendering, not tmux.

What I tried (no effect on Claude Code inside tmux)

• Adding \set -as terminal-features ',tmux-256color:RGB'\ to tmux.conf (the inside-terminal counterpart of the existing \xterm-256color:RGB\ feature). tmux loaded it (\show-options -g terminal-features\ confirms entries), but Claude Code still bands.
• Installing a user-local terminfo for \tmux-256color\ with \RGB\ capability added, verified via \infocmp\ and \tput RGB\.
• Setting \FORCE_COLOR=3\ in the Claude Code process environment (verified via \ps eww\).

Notes

\xterm-256color\ (used outside tmux on macOS) doesn't have \RGB\ in its terminfo entry either — but Claude Code clearly renders truecolor there. So the inside-tmux path looks like a special case that doesn't consult \COLORTERM\ or \FORCE_COLOR\. Likely \TERM=tmux-256color\ (or \TERM_PROGRAM=tmux\) is triggering a 256-color branch in the rendering library.