Claude Codeのtmuxでtruecolorを使う — CLAUDE_CODE_TMUX_TRUECOLOR

tmuxの中で起動したClaude Codeは、既定で色を256色に丸めます。24bitのtruecolorで表示したいときは、~/.tmux.confにset -ga terminal-overrides ',*:Tc'を足し、そのうえで環境変数CLAUDE_CODE_TMUX_TRUECOLORに空でない値を入れます。

この変数には落とし穴があります。0やfalseを入れても、truecolorは有効のままです。多くのon/off変数とは逆なので、無効にしたつもりで有効のまま使い続けやすい変数です。

なぜtmuxの中だけ256色になるのか

$TMUXが設定されている、つまりtmuxの内側でClaude Codeを起動すると、Claude Codeは出力を256色に抑えます。tmuxは、設定しない限りtruecolorのエスケープシーケンスを外側の端末へ通さないためです。

どちらか片方だけでは足りません。変数を立てても、tmuxがTcを宣言していなければ、24bitの指定は外側の端末まで届きません。逆にtmux側だけ直しても、Claude Codeが丸めたままです。

設定手順は2段階

1. tmux側にTcを足す

~/.tmux.confに次の1行を追記します。

echo "set -ga terminal-overrides ',*:Tc'" >> ~/.tmux.conf

すでにShift+Enterや通知のための設定が入っている場合は、同じファイルに続けて足せば十分です。その3行はClaude Codeをtmuxで使う設定にまとめています。Tcの行は、それとは独立した4行目という位置づけです。

追記したら、起動中のtmuxに反映します。

tmux source-file ~/.tmux.conf

tmux.confの完成形

Shift+Enterと通知の3行にTcの行を加えると、~/.tmux.confは次の4行になります。

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
set -ga terminal-overrides ',*:Tc'

allow-passthroughは通知や進捗表示を外側の端末へ通す設定、extended-keysの2行はShift+Enterと通常のEnterを区別させる設定です。Tcの行だけが色の話で、ほかの3行を入れなくてもtruecolorの設定としては成立します。

2. 環境変数を立てる

シェルで立てる場合は、claudeを起動する前にexportします。シェルの環境変数は起動時に読まれるので、立てたあとにclaudeを起動し直します。

export CLAUDE_CODE_TMUX_TRUECOLOR=1
claude

毎回の起動で有効にするなら、~/.zshrcなどのexport行にするか、settings.jsonのenvに書きます。

{
  "env": {
    "CLAUDE_CODE_TMUX_TRUECOLOR": "1"
  }
}

~/.claude/settings.jsonに書けば、すべてのプロジェクトに効きます。.claude/settings.jsonに書くとプロジェクトの全員に、.claude/settings.local.jsonに書くと自分のそのプロジェクトだけに効きます。tmuxの使い方は人によって違うので、個人の設定として~/.claude/settings.jsonに置くのが素直です。

0やfalseでも有効になる落とし穴

環境変数ページの注記では、on/offを切り替える変数の多くは1・true・yes・onで有効、0・false・no・offで無効になります。大文字小文字は区別されません。

CLAUDE_CODE_TMUX_TRUECOLORはこのルールに従わない変数です。設定されているかどうかだけを見るため、空でない値ならなんでも有効になります。

たとえば、tmuxで色が合わないので試しにオフへ戻そうと、~/.zshrcの行をexport CLAUDE_CODE_TMUX_TRUECOLOR=0に書き換えたとします。新しいシェルを開いてclaudeを起動しても、変数は設定されたままなので、truecolorは有効のままです。オフに戻す操作としては、行を書き換えるのではなく、行ごと消します。

無効に戻すには、変数を未設定にします。シェルならunsetです。

unset CLAUDE_CODE_TMUX_TRUECOLOR

settings.jsonのenvから行を消した場合は、実行中のセッションでは変数が外れません。次にclaudeを起動したときに外れます。この挙動はenvブロック全般のものとして書かれています。

同じ読み方をする変数は、公式の一覧に6つ載っています。

DISABLE_TELEMETRY=0のように書いて「テレメトリを止めない」つもりでも、実際には止まります。この一覧に挙がる変数を書くときは、無効にしたい場面では値を0にせず、変数ごと外します。なお、FORCE_HYPERLINKは数値として読まれ、0だけが無効を意味します。false・no・offを入れると、無効ではなく有効になります。これらの6つとも、通常のon/off変数とも別の扱いです。

反映されたかを確かめる

設定が効いたかは、24bitの色指定を直接出すと見分けられます。tmuxのペイン内で次を実行します。

printf '\033[38;2;255;100;0mTRUECOLOR\033[0m\n'

文字がオレンジに見えれば、tmuxを通して24bitの色が届いています。これはtmuxと外側の端末の確認で、Claude Codeの変数の確認ではありません。Claude Code側は、まず変数がClaude Codeを起動するシェルに見えているかを確かめます。

echo $TMUX
echo $CLAUDE_CODE_TMUX_TRUECOLOR

1行目が空なら、そのシェルはtmuxの外にあり、256色への丸めはもともと起きません。2行目が空なら変数は未設定で、丸めが続きます。0と表示されても、設定されている以上は有効です。そのうえでclaudeを起動し直し、グラデーションや配色の段差が以前より滑らかに出るかを見ます。

つまずいたときの切り分けは、次の順に見ます。

シェルのexportとsettings.jsonの両方に書いたとき

環境変数ページには、同じ変数をシェルとsettings.jsonのenvの両方に書いた場合、多くのセッションでは設定ファイルの値が適用されると書かれています。envの各項目がプロセスの環境変数に書き込まれ、シェルから引き継いだ値を置き換えるためです。ただし、シェルの値が残るセッションもあり、その条件は設定リファレンスの「How env values interact with your shell」に載っています。

この変数は空でなければ値の中身を見ないので、どちらか一方に書いてあれば有効です。外すときは、両方から消す必要があります。

• ~/.zshrcなどのexport行を消しても、settings.jsonのenvに残っていれば有効のままです
• settings.jsonの行を消した場合、実行中のセッションでは外れず、次の起動で外れます
• 実行中のシェルにexportした値は、unsetするか新しいシェルを開くまで残ります

SSH先でtmuxを動かす場合は、terminal-overridesの行も変数も、tmuxとClaude Codeが動いているSSH先の側に置きます。手元のマシンの~/.tmux.confを直しても、SSH先のtmuxには効きません。

隣接する変数:SSH越しで取り消し線が出ない

同じ「端末の判定が効かない」系の変数に、CLAUDE_CODE_FORCE_STRIKETHROUGHがあります。Claudeの返答にある~~text~~を取り消し線として描く変数です。

端末が取り消し線に対応していても、Claude Codeが自動判定できない場合があります。たとえば、SSH越しでTERM_PROGRAMが転送されていない場合です。判定できないと、~~の記号がそのまま画面に出ます。

こちらは1で有効にする通常のon/off変数です。必要なバージョンはv2.1.186以降です。

export CLAUDE_CODE_FORCE_STRIKETHROUGH=1
claude

SSH越しで自動判定が外れる例は、リンクにもあります。FORCE_HYPERLINKは、端末が対応していても検出されないときに1でクリックできるリンクを有効にします。フッターのPRバッジは、検出できないSSH越しでもリンクとして描かれるため、プレーンな表示に戻したいときは0を入れます。

端末の自動判定を上書きする変数は、ほかに同期出力用のCLAUDE_CODE_FORCE_SYNC_OUTPUTなどがあります。ただし同期出力の変数は、tmuxの中では効果がないと説明されています。tmuxの中でどの表示機能が外側の端末へ届くかは、tmuxペインタイトルと画像表示の記事で症状別に扱っています。

使い分けの早見表