iTerm2 + tmux 環境で Claude Code の Shift+Enter が効かない問題の解決方法
はじめに
Claude Code を iTerm2 + tmux 環境で使っていると、Shift+Enter で改行できず、そのまま送信されてしまう問題に遭遇しました。
本記事では、原因の特定から解決までの過程を共有します。
また、原因を調査する上で類似の問題についての記事を発見したのですが、本記事ではより直接的な解決策だと思います。
環境
- macOS (Darwin 25.3.0)
- iTerm2 3.6.6
- tmux 3.6a
- Claude Code（CLI版）
症状
- tmux を介さず直接 iTerm2 で Claude Code を起動すると Shift+Enter で改行できる
- tmux 内で起動すると Shift+Enter が通常の Enter と同じ動作になり、入力が即送信される
原因
調査の結果、2つの原因が重なっていました。
原因1: TERM_PROGRAM 環境変数の上書き
tmux はセッション内の TERM_PROGRAM を tmux に上書きします。
# tmux 外
TERM_PROGRAM=iTerm.app # ← Claude Code が iTerm2 を認識できる
# tmux 内
TERM_PROGRAM=tmux # ← Claude Code が iTerm2 を認識できない
Claude Code は TERM_PROGRAM を参照してターミナルの種類を判別しており、tmux だと iTerm2 のネイティブな Shift+Enter サポートを利用しません。
原因2: tmux の extended-keys-format のミスマッチ
tmux の拡張キー転送にはエスケープシーケンスのフォーマットが 2種類 あります。
| フォーマット | エスケープシーケンス | 用途 |
|---|---|---|
xterm（デフォルト） |
\033[27;2;13~ |
古い xterm 互換形式 |
csi-u |
\033[13;2u |
モダンな CSI u 形式 |
Claude Code は CSI u 形式 を期待していますが、tmux のデフォルトは xterm 形式 です。フォーマットが合っていないと、エスケープシーケンスが生テキスト（[27;2;13~）として表示されます。
解決方法
Step 1: .tmux.conf に拡張キー設定を追加
# 拡張キーを常にアプリケーションに転送する
set -s extended-keys always
# フォーマットを CSI u に指定（これが重要！）
set -s extended-keys-format csi-u
# ターミナルの拡張キーサポートを明示的に有効化
set -as terminal-features 'xterm*:extkeys'
各設定の解説
extended-keys always — on だとアプリが \033[>4;1m を送ってリクエストした場合のみ転送されます。Claude Code がリクエストしない場合があるため always が確実です。
extended-keys-format csi-u — デフォルトの xterm ではなく csi-u を指定し、モダンなアプリが理解できる形式でキーを送信します。
Step 2: iTerm2 で CSI u モードを有効化
- iTerm2 → Settings (⌘ + ,)
- Profiles → Keys
- 「Report modifiers using CSI u」 にチェック
Step 3: Claude Code に iTerm2 を認識させる
.zshrc に alias を追加します。
alias claude='TERM_PROGRAM=iTerm.app claude'
Step 4: 反映
source ~/.zshrc
tmux kill-server # リロードでは -s オプションが反映されない場合がある
tmux
claude
トラブルシューティング
エスケープシーケンスの確認方法
tmux 内で cat -v を実行し、Shift+Enter を押して Ctrl+C で止めます。
| 表示 | 意味 |
|---|---|
^[[13;2u |
CSI u 形式で正しく届いている |
^[[27;2;13~ |
xterm 形式（extended-keys-format csi-u が未反映） |
空行 or ^M
|
拡張キーが転送されていない |
設定の即時反映
tmux kill-server ができない場合は直接設定できます。
tmux set -s extended-keys always
tmux set -s extended-keys-format csi-u
補足: CSI u とは
CSI u は libtermkey 由来のキーエンコーディング規格で、\033[codepoint;modifiers u の形式で修飾キー付きの入力を曖昧さなく表現します。Kitty keyboard protocol もこれがベースで、近年のモダンなターミナルアプリで広く採用されています。tmux 3.2+ でサポートされましたが、後方互換性のためデフォルトは xterm 形式のままです。