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

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

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

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

tmuxを使わなければ、多くのターミナルでShift+Enterが設定なしで動きます。Ghostty・Kitty・iTerm2・WezTerm・Warp・Apple Terminal・Windows Terminalが該当します。foot、Alacritty 0.16以降のようにkitty keyboard protocolに対応したターミナルも設定不要です(Claude Code v2.1.269以降)。VS Code・Cursor・Devin Desktop・Zed、0.16より前のAlacrittyは/terminal-setupを1回実行すれば有効になります。

gnome-terminalとJetBrains系のIDE(PyCharm・Android Studioなど)はShift+Enter自体に対応していません。tmuxの有無に関係なくCtrl+Jか\のあとEnterを使います。この2つはどんなターミナルでも設定なしで通ります。既定のキー操作はClaude Codeショートカット一覧で確認できます。

~/.tmux.confに3行を追記して反映する

手順は3つだけです。設定ファイルを編集しただけでは稼働中のtmuxサーバーに反映されないため、2番目を飛ばすと「設定したのに変わらない」状態になります。

追記する内容は次の3行です。

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が飲み込まずに外側のターミナルへ通す設定です。これがオフのままだと、通知に対応したターミナルを使っていても、tmuxの中にいる限り通知は届きません。2〜3行目はtmuxにShift+EnterとプレーンなEnterを区別させるための設定で、この2つが揃って初めてtmuxの外と同じ入力体験になります。

進捗バーが出るのは、ConEmu、Ghostty 1.2.0以降、iTerm2 3.6.6以降のように対応したターミナルだけです。出したくない場合は、terminalProgressBarEnabledをfalseにして非表示にできます。通知の経路はpreferredNotifChannelで選びます。既定は"auto"で、iTerm2・Ghostty・Kittyではデスクトップ通知、Terminal.appでは音声ベルがオフのときだけベルを鳴らし、それ以外のターミナルでは何も起きません。"terminal_bell"はどのターミナルでもベル文字を鳴らします。

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

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

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

tmux -CCのセッションでは、Claude Codeがフルスクリーンの既定を使わず従来のレンダラーに倒す仕様です。保存したtui設定よりtmux -CCの判定が先に効くので、CLAUDE_CODE_NO_FLICKER=1で明示的に有効にしない限り、この組み合わせを踏むことはありません。マウス操作の不調に当たるのは、CLAUDE_CODE_NO_FLICKER=1を付けて起動した人が中心です。公式はtmux -CCのセッションでフルスクリーンを有効にしないよう書いており、/tui fullscreenで切り替えた場合の挙動は明記されていません。

もうひとつの制約は同期出力です。tmux 3.6系までは同期出力(synchronized output)に対応していないため、直接ターミナルで動かすより画面のチラつきが増えることがあります。Claude Codeは起動時に端末へ対応状況を問い合わせ、対応が返れば自動で使います。

ここでCLAUDE_CODE_FORCE_SYNC_OUTPUT=1を試したくなりますが、環境変数の説明に「tmuxの下では効果がない」と明記されています。対応済みなのに自動検出されないEmacs eatのようなエミュレーター向けの変数だからです。チラつきが気になるなら、tmuxを新しい版に上げるか、そのペインだけtmuxの外のタブでClaude Codeを動かします。

tmux 3.4以降の変更履歴も1点だけ補っておきます。v2.1.200のリリースノートで「tmux 3.4以降で同期出力を有効にした」と書かれた件は、v2.1.212の更新で「3.6系までは同期出力に対応していない」と訂正されています。「3.4から効く」という情報を見かけたら、訂正前の記述です。

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

Claude Codeがマウスイベントを捕捉している間は、ターミナル本来のクリック&ドラッグによる選択がコピーに使えません。ドラッグした範囲はClaude Codeの内部にあり、ターミナル側の選択バッファには存在しないためです。tmuxのコピーモードやKittyのヒント機能からも、その範囲は見えません。公式ドキュメントも、マウス捕捉はSSH越しやtmuxの中で特に問題になりやすいと述べています。

Claude Codeは選択テキストをシステムクリップボードへ書き込みます。tmuxの中ではそれに加えてtmuxのペーストバッファにも書き込み、SSH越しではOSC 52エスケープシーケンスにフォールバックします。コピーのたびにトーストで経路が表示されます。v2.1.176では、tmuxにSSHで入った状態の/copyとマウス選択がクリップボードに届かない問題と、3.2より前のtmuxでペーストバッファが読み込まれない問題が直されています。

ターミナル本来の選択に戻すには、ドラッグ中に修飾キーを押します。キーはターミナルで違い、Terminal.appはFn、iTerm2はOption、そのほか多くのターミナルはShiftです。VS Code・Cursor・Devin DesktopもShiftで、macOSではterminal.integrated.macOptionClickForcesSelectionを有効にするとOptionも使えます。tmuxやSSHを挟むと接続元のターミナルを特定できないため、ヒントには候補キーが複数並びます。

フルスクリーンの検索まわりにも違いがあります。フルスクリーンでは会話が代替スクリーンバッファにあるので、Cmd+fもtmuxの検索も会話の中身を見られません。Ctrl+oでトランスクリプトモードに入り、[を押すと会話全体がターミナルのネイティブなスクロールバックに書き出され、tmuxのコピーモードで検索・選択できるようになります。Escかqでフルスクリーンに戻ります。

マウス捕捉そのものを止める環境変数は3つあり、効き方が違います。

三つ目はCLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1で、フルスクリーンをやめて従来のレンダラーに戻します。会話が端末のネイティブスクロールバックに残るので、Cmd+fもtmuxのコピーモードも普段どおり使えます。tui設定とCLAUDE_CODE_NO_FLICKERのどちらよりも優先されます。tmuxの操作に慣れた人が、チラつきよりスクロールバックの扱いやすさを取りたいときの逃げ道です。

tmuxとClaude Codeの組み合わせで出てくるその他の機能

ターミナル設定以外にも、tmuxが絡む機能がいくつかあります。

claude --tmuxは、ワークツリー用のtmuxセッションを作るフラグです。v2.1.287のclaude --helpでは、この行で説明されています。

--tmux  Create a tmux session for the worktree (requires --worktree). Uses iTerm2 native panes when available; use --tmux=classic for traditional tmux.

--worktreeと一緒に指定する必要があり、iTerm2では既定でネイティブペインを使います。従来のtmuxにしたいときは--tmux=classicと書きます。使用例は次のとおりです。

claude -w feature-auth --tmux

エージェントチームの分割ペイン表示にもtmuxが使えます。teammateModeを"auto"にすると、すでにtmuxの中にいるとき、またはit2 CLIを入れたiTerm2のときに分割ペインになり、それ以外は同じ画面内の表示に戻ります。iTerm2のtmux -CCはtmuxへの入口として勧められていますが、フルスクリーンレンダリングとは併用できないので、前節の制約に当たります。"tmux"なら分割ペインを明示でき、tmuxかiTerm2かは端末から自動判定されます。公式ドキュメントは、tmuxはOSによって既知の制限があり、macOSで最も安定して動くと注意しています。VS Codeの統合ターミナル、Windows Terminal、Ghosttyでは分割ペインは使えません。チームのセッションが終了後にtmuxに残ったときは、tmux lsで一覧し、tmux kill-session -t <名前>で片付けます。

ほかに、CLAUDE_CODE_NONBLOCKING_STDOUT=1(v2.1.261以降)があります。tmuxのコントロールモードで一時停止したペインのように、端末が出力の読み取りを止めても、Claude Codeが固まらないようにする変数です。通常のtmux利用では不要で、フリーズが再現するときの手段として知っておくと足ります。

よくあるつまずき

SSHでつないだ先のサーバーでtmuxを起動している場合、パススルー設定は各tmuxサーバーが個別に保持します。Claude Codeが動いているサーバーの~/.tmux.confを編集しているか確認してください。

/terminal-setupはtmuxやGNU screenの中ではなく、ホストのターミナルで直接実行します。ホスト側のターミナルの設定ファイルに書き込む処理だからです。例外としてiTerm2では、tmuxの中から実行してもiTerm2を検出し、クリップボードアクセスの許可設定を有効にします。反映にはiTerm2の再起動が必要です。

通知が届かないときは、まずOSの通知許可を確認します。そのうえでtmuxのallow-passthroughを確かめます。対応していないターミナルではベルへの切り替えがあり、その手順はClaude Code通知の設定にあります。preferredNotifChannelをterminal_bellにする方法と、Notification hookで音を鳴らす方法の両方を扱っています。

よくある質問

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

3行の設定はtmux専用の構文で、screenやzellijにはそのまま適用できません。公式ドキュメントが設定方法を示しているのはtmuxだけです。screenについては、フルスクリーンのコピー処理で、v2.1.219より前は約570文字を超える選択をコピーするとbase64の文字列が画面に出る不具合があったと記されています。それ以降は修正されています。

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

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

まとめ

3行の追記とリロードで、tmuxの中でもShift+Enterと通知が働きます。フルスクリーンを併用するなら、マウスモードの有効化が前提で、iTerm2のtmux -CCは避けます。チラつきは設定では消せず、tmuxを更新するか、そのペインだけtmuxの外で動かす判断になります。