claude-code - 💡(How to fix) Fix Docs: document CLAUDE_CODE_TMUX_TRUECOLOR in env-vars reference [1 participants]

Summary

CLAUDE_CODE_TMUX_TRUECOLOR=1 is a real, functional escape hatch inside src/ink/colorize.ts (function clampChalkLevelForTmux, lines ~47–57). When set, it disables the defensive chalk.level = 2 clamp that Claude Code applies whenever $TMUX is present, restoring full 24-bit truecolor rendering inside tmux panes.

It is currently undocumented.

Where it's missing

Checked and not mentioned on any of:

• https://code.claude.com/docs/en/env-vars
• https://code.claude.com/docs/en/terminal-config
• https://code.claude.com/docs/en/settings
• README.md in anthropics/claude-code
• CHANGELOG.md in anthropics/claude-code

The only public mention on the entire internet is a user comment in #36785.

Why it matters

The underlying truecolor-clamp regression is tracked in #36785 and is visually observable in #37215 (Claude mascot rendering as pink/salmon instead of terracotta), #35148, #37770, #35806, and #32365. Until that underlying bug is fixed, CLAUDE_CODE_TMUX_TRUECOLOR is the only user-facing workaround that actually restores correct colors for users with truecolor-capable terminals (Ghostty, Alacritty, iTerm2, kitty, WezTerm) running inside properly-configured tmux. Without documentation, users must either read the bundled source or get lucky finding a stale comment thread.

Ask

Add a short entry to https://code.claude.com/docs/en/env-vars (and ideally cross-link from the terminal-config page) with roughly this content:

CLAUDE_CODE_TMUX_TRUECOLOR — When set to any truthy value, disables the defensive 256-color clamp that Claude Code applies inside tmux. Use this if your tmux is already configured for truecolor passthrough (terminal-features ',<term>:RGB') and you are seeing washed-out colors in the TUI. Must be exported from the shell (e.g. in ~/.zshrc / ~/.bashrc / ~/.config/fish/config.fish), not settings.json, because the clamp is evaluated at module load before settings env injection. See #36785 for context on the underlying issue.

Not a duplicate of #36785

This issue is scoped specifically to documentation. #36785 tracks the underlying clamp logic and whether it should be relaxed. Even if the clamp is eventually fixed, CLAUDE_CODE_TMUX_TRUECOLOR should still be documented as the interim workaround for users on older versions.

Environment

Not strictly required for a docs issue, but for completeness: macOS 15 (Darwin 25.4.0), Ghostty, tmux 3.6a, Claude Code 2.1.100.