Summary
Claude Code degrades to 256-color mode when the TMUX environment variable is set, even when COLORTERM=truecolor is explicitly configured and the full terminal pipeline supports 24-bit color. This causes custom theme hex colors to be quantized to the nearest 256-color cube entry.
Steps to Reproduce
- Run Ghostty (or any truecolor terminal) with tmux
- Ensure
COLORTERM=truecolor is set in the shell
- Configure a custom Claude Code theme with a muted/dark hex color, e.g.
"userMessageBackground": "#3b4252"
- Launch Claude Code inside a tmux pane — colors render incorrectly (e.g.
#3b4252 → #5f5f8a)
- Launch Claude Code with
TMUX= claude (TMUX unset) in the same pane — colors render correctly
Expected Behavior
Claude Code should respect COLORTERM=truecolor (the standardized signal per https://github.com/termstandard/colors) regardless of whether $TMUX is set.
Actual Behavior
When $TMUX is set, Claude Code falls back to 256-color rendering, ignoring COLORTERM=truecolor. Saturated colors that happen to land exactly on 256-color cube nodes (e.g. #ff0000) appear correct, while off-cube colors are visibly quantized.
Environment
- Claude Code: 2.1.145
- Terminal: Ghostty (
TERM=xterm-ghostty outside tmux, TERM=tmux-256color inside)
- tmux: 3.6a (Oh My Tmux configuration)
- OS: macOS (Darwin 25.4.0, ARM64)
COLORTERM=truecolor ✓tmux-256color terminfo has RGB and Tc capabilities ✓terminal-features includes xterm-ghostty:RGB ✓- Raw
printf '\e[48;2;59;66;82m...\e[0m' truecolor sequences render correctly inside tmux ✓
Workaround
alias claude='TMUX= claude'
Root Cause
Claude Code appears to check $TMUX and unconditionally degrade color depth when inside a tmux session. This predates the now-standard COLORTERM convention and causes false negatives on modern tmux setups with proper truecolor passthrough configured. The fix would be to honor COLORTERM=truecolor/COLORTERM=24bit (and/or FORCE_COLOR=3) as an override even when $TMUX is set.
Summary
Claude Code degrades to 256-color mode when the
TMUXenvironment variable is set, even whenCOLORTERM=truecoloris explicitly configured and the full terminal pipeline supports 24-bit color. This causes custom theme hex colors to be quantized to the nearest 256-color cube entry.Steps to Reproduce
COLORTERM=truecoloris set in the shell"userMessageBackground": "#3b4252"#3b4252→#5f5f8a)TMUX= claude(TMUX unset) in the same pane — colors render correctlyExpected Behavior
Claude Code should respect
COLORTERM=truecolor(the standardized signal per https://github.com/termstandard/colors) regardless of whether$TMUXis set.Actual Behavior
When
$TMUXis set, Claude Code falls back to 256-color rendering, ignoringCOLORTERM=truecolor. Saturated colors that happen to land exactly on 256-color cube nodes (e.g.#ff0000) appear correct, while off-cube colors are visibly quantized.Environment
TERM=xterm-ghosttyoutside tmux,TERM=tmux-256colorinside)COLORTERM=truecolor✓tmux-256colorterminfo hasRGBandTccapabilities ✓terminal-featuresincludesxterm-ghostty:RGB✓printf '\e[48;2;59;66;82m...\e[0m'truecolor sequences render correctly inside tmux ✓Workaround
Root Cause
Claude Code appears to check
$TMUXand unconditionally degrade color depth when inside a tmux session. This predates the now-standardCOLORTERMconvention and causes false negatives on modern tmux setups with proper truecolor passthrough configured. The fix would be to honorCOLORTERM=truecolor/COLORTERM=24bit(and/orFORCE_COLOR=3) as an override even when$TMUXis set.