claude-code - 💡(How to fix) Fix Color theme renders in 256-color mode inside tmux despite COLORTERM=truecolor

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

1. Run Ghostty (or any truecolor terminal) with tmux
2. Ensure COLORTERM=truecolor is set in the shell
3. Configure a custom Claude Code theme with a muted/dark hex color, e.g. "userMessageBackground": "#3b4252"
4. Launch Claude Code inside a tmux pane — colors render incorrectly (e.g. #3b4252 → #5f5f8a)
5. 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.