Claude Code tmux設定 — パススルーとフルスクリーンの注意点

Claude Codeをtmux内で使うと何が壊れるか

tmuxの中でClaude Codeを動かすと、既定設定のままでは2つの動作が壊れます。Shift+Enterが改行でなく送信として扱われること。デスクトップ通知とプログレスバーが外側のターミナルまで届かず、tmuxに飲み込まれてしまうことです。

原因はtmuxがエスケープシーケンスを仲介する構造にあります。Shift+Enterと通常のEnterを区別するには、ターミナルが送ってくる拡張キー情報をtmuxがそのまま素通りさせる必要があります。同様に、デスクトップ通知や進捗バーの表示もエスケープシーケンス経由で外側のターミナルに渡されるため、tmuxが仲介する時点で止まります。

tmuxを使わない通常のターミナルでは、Ghostty・Kitty・iTerm2・WezTerm・Warp・Apple Terminal・Windows Terminalの7つはShift+Enterが設定なしでそのまま動きます。VS Code・Cursor・Devin Desktop・Alacritty・Zedは/terminal-setupを1回実行すれば有効になります。gnome-terminalとJetBrains系のIDE(PyCharm・Android Studioなど)はShift+Enter自体に対応しておらず、tmuxの有無に関係なくCtrl+Jか\のあとEnterを使います。既定のキー操作をひととおり確認したい場合はClaude Codeショートカット一覧も参考になります。この前提を踏まえたうえで、tmux特有の設定を見ていきます。

~/.tmux.confに3行を追記する

~/.tmux.confに次の3行を追加し、tmux source-file ~/.tmux.confで稼働中のtmuxサーバーに反映します。設定ファイルを編集しただけでは反映されないので、このコマンドの実行を忘れないようにします。

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

tmux source-file ~/.tmux.conf

1行目のallow-passthroughは、通知や進捗バーの更新をtmuxが飲み込まずに外側のターミナルへ通す設定です。これがオフのままだと、Ghostty・Kitty・iTerm2のような対応ターミナルを使っていても、tmuxの中にいる限り通知は届きません。2〜3行目のextended-keys関連の設定は、tmuxにShift+EnterとプレーンなEnterを区別させるためのものです。この2つが揃って初めて、tmuxの外で動かしたときと同じ入力体験になります。

新しいtmuxセッションだけでなく、すでに起動しているセッションにもsource-fileコマンドで即座に反映されます。セッションを作り直す必要はありません。

フルスクリーンレンダリングをtmuxで使うときの注意点

Claude CodeのTUI(フルスクリーンレンダリング)はtmux内でも動作しますが、3つの制約があります。フルスクリーン自体の仕組みはClaude CodeのTUI(フルスクリーン)とはで扱っているので、ここではtmux特有の注意点に絞ります。

マウスホイールでのスクロールには、tmux側のマウスモードが必要です。~/.tmux.confにまだset -g mouse onが無ければ追加してください。無効なままだとホイールイベントはtmuxに取られ、Claude Code側には届きません。PgUp・PgDnによるキーボードスクロールはマウスモードの有無に関わらず動きます。マウスモードがオフの状態でtmuxを検出すると、Claude Codeは起動時に一度だけヒントを表示します。

iTerm2のtmux -CC(統合モード)ではフルスクリーンレンダリングを有効にしないでください。統合モードはtmuxの各ペインをiTerm2のネイティブな分割ウィンドウとして描画する仕組みで、フルスクリーンが前提とする代替スクリーンバッファやマウストラッキングが正しく機能しません。マウスホイールが反応しなくなったり、ダブルクリックで画面が崩れたりします。-CCを付けない通常のtmuxをiTerm2内で使う分には問題ありません。

tmux 3.6系までのリリースは同期出力(synchronized output)に対応していません。このため、tmux経由で使うと直接ターミナルで動かすときよりチラつきが増えることがあります。Claude Codeは起動時にターミナルの対応状況を確認し、対応していれば自動的に同期出力を使います。チラつきが気になる場合は、tmuxを最新版に上げるか、そのペインだけClaude Codeをtmuxの外で動かす方法があります。

tmux内でのマウス選択とコピーの扱い

Claude Codeがマウスイベントを捕捉している間は、ターミナル本来のクリック&ドラッグによるコピーが使えなくなります。この摩擦はSSH経由やtmuxの中で特に起きやすいと公式ドキュメントも明記しています。tmuxのコピーモードやKittyのヒント機能のようなツールは、Claude Code側で選択した範囲を認識できません。

Claude Codeは選択したテキストをシステムクリップボードへ書き込みますが、tmuxの中ではそれに加えてtmuxのペーストバッファにも書き込みます。SSH越しに使っている場合はOSC 52エスケープシーケンスにフォールバックします。コピー後にトーストで、どの経路を使ったかが表示されるので、意図した場所に貼り付けできているか確認できます。

ターミナル本来の選択に戻したい場合は、選択したい範囲をドラッグする際にキーを押しながら操作します。多くのターミナルではShift、iTerm2ではOptionを押しながらのドラッグでネイティブ選択に切り替わります。SSH越しやtmuxの中では接続元のターミナルをClaude Codeが特定できないことがあり、その場合はヒントに候補キーが複数表示されます。

マウス捕捉自体を常時オフにしたいなら、CLAUDE_CODE_DISABLE_MOUSE=1を設定します。クリックでのカーソル移動やツール出力の展開、URLクリック、ホイールでのスクロールは失いますが、PgUp・PgDn・Ctrl+Home・Ctrl+Endによるキーボードスクロールはそのまま使え、ターミナル側のネイティブ選択も常に有効になります。ホイールスクロールだけは残したい場合は、代わりにCLAUDE_CODE_DISABLE_MOUSE_CLICKS=1(v2.1.195以降)を使うと、クリック・ドラッグ・ホバーだけを無効化できます。

環境ごとの対応状況

△の環境での通知の直し方はClaude Code通知の設定にまとめてあります。preferredNotifChannelをterminal_bellにする方法とNotification hookで音を鳴らす方法の両方を扱っています。

よくあるつまずき

3行を追記したのにtmux source-fileを実行し忘れて「設定したのに変わらない」と感じるケースが一番多いつまずきです。編集後は必ずリロードコマンドを実行するか、いったんtmuxサーバーごと再起動してください。

SSH先のサーバーでさらにtmuxを起動する、いわゆるネストしたtmux構成では、外側と内側のどちらのtmuxサーバーで動いているClaude Codeなのかによって、設定を反映させる~/.tmux.confが変わります。パススルー設定は各tmuxサーバーが個別に保持する値なので、意図した側のサーバーの設定ファイルを編集しているか確認してください。

iTerm2でtmux -CCを常用している人が、他の解説を見てフルスクリーンレンダリングを有効化し、マウス操作ができなくなるケースもあります。統合モードを使っているかどうかは、ペインがiTerm2のネイティブウィンドウとして分割表示されているかで判断できます。分割表示されていれば-CCモードです。

tmuxのバージョンをすぐ上げられない環境では、同期出力非対応によるチラつきをClaude Code側の設定だけでは解消できません。作業中のペインだけでも構わないので、tmuxの外の素のターミナルタブでClaude Codeを動かす方が確実です。

よくある質問

/terminal-setupはtmuxの中で実行してもいい?

いいえ。/terminal-setupはホスト側のターミナルアプリケーションの設定ファイルに書き込む処理なので、tmuxやGNU screenの中ではなく、ホストのターミナルで直接実行する必要があります。tmux越しに実行すると、書き込み先を正しく判定できません。

Ghostty・Kitty・iTerm2以外のターミナルでtmux越しに通知を受け取るには?

3行のパススルー設定を入れたうえで、preferredNotifChannelを"terminal_bell"に切り替えます。デスクトップ通知に対応していないターミナルでも、ベル文字による通知はtmux経由でも鳴らせます。設定項目の全体は先ほど紹介した通知の記事で扱っています。

GNU screenやzellijでも同じ3行の設定は使える?

公式ドキュメントが明示しているのはtmux向けの設定だけです。GNU screenやzellijなど他のターミナルマルチプレクサに同じ設定を適用できるとは案内されていないので、それらを使う場合は個別に動作を確認してください。

gnome-terminalやJetBrains IDEのターミナルでは、tmux側を設定してもShift+Enterは使える?

使えません。これらのターミナルはtmuxの有無に関わらずShift+Enter自体に対応しておらず、代わりにCtrl+Jか\のあとEnterで改行を入力します。tmuxのパススルー設定はエスケープシーケンスの通り道を作るだけなので、ターミナル側が対応していない挙動までは補えません。

まとめ

tmuxの中でClaude Codeを違和感なく使うには、~/.tmux.confへの3行追記とリロードだけで完了します。フルスクリーンレンダリングまで使う場合は、マウスモードの有効化と、iTerm2のtmux -CC統合モードを避けることの2点を追加で意識してください。設定してもなお通知が届かない場合は、preferredNotifChannelかNotification hookでの補完が次のステップになります。