Claude Code tmuxで画面がちらつく・スクロールできない時の直し方
Claude Codeをtmux内で使うと画面がちらつく、スクロールが効かない問題への対処法。CLAUDE_CODE_NO_FLICKERとフルスクリーンモード、tmux.conf設定を公式ドキュメントを基に解説する。
エンジニアのゆとです。
Claude Codeをtmuxの中で動かし始めた人が最初にぶつかる壁は、並列実行のやり方より前に「画面がちらつく」「マウスホイールでスクロールしても入力欄が動くだけで会話が読めない」という表示まわりの不具合だったりする。自分もそうだった。tmux + Claude Codeで検索すると出てくる記事のほとんどは並列開発の活用術で、この2つの症状をピンポイントで直す情報が日本語ではまとまっていなかったので、公式ドキュメントとGitHub Issueを突き合わせて整理した。
結論 — 症状別の対処法早見表
| 症状 | まず試すこと | 効かない場合 |
|---|---|---|
| 画面がちらつく・カーソルが飛ぶ | CLAUDE_CODE_NO_FLICKER=1 で起動するか /tui fullscreen を実行 | 対応端末なのに直らないなら CLAUDE_CODE_FORCE_SYNC_OUTPUT=1。tmuxを3.6系以前で使っているならアップグレード |
| マウスホイールでスクロールできない・入力欄が動く | ~/.tmux.conf に set -g mouse on を追加してリロード | スクロール量が合わないなら CLAUDE_CODE_SCROLL_SPEED か /scroll-speed で調整 |
| tmuxのコピーモードで会話を検索できない | Ctrl+O でtranscriptモードに入り / で検索 | ネイティブのスクロールバックに戻したいなら [ キー |
| 通知やプログレスバーが外に届かない | ~/.tmux.conf に allow-passthrough と extended-keys を追加 | 詳細は後述の関連記事を参照 |
自分の症状がどれに近いか、まずここで当たりをつけてから該当する見出しに進んでほしい。
なぜtmux上だとClaude Codeの画面が壊れやすいのか
原因は単純で、Claude CodeのCLI描画がデフォルトでは「代替画面バッファ」を使わず、通常のターミナルバッファに直接書き込む方式になっているからだ。vimやhtopのような全画面アプリは代替画面バッファに切り替えて描画するため、tmuxのペイン内でも表示が安定する。一方Claude Codeの従来レンダラーは、応答が流れてくるたびに画面を再描画し続けるので、tmuxのペインという「もう1枚挟まった描画レイヤー」を通ると再描画のタイミングがずれて、ちらつきやカーソルジャンプとして見えてしまう。
これは自分の環境だけの問題ではなく、公式リポジトリでも継続的に報告されている既知の挙動だ。tmux内でスピナー表示が代替画面バッファではなくメインバッファに描画されてしまい表示が跳ねる報告(Issue #51868)や、ストリーミング出力中にTUIがちらつく・カーソルが飛ぶ報告(Issue #37283)など、同種の報告が複数上がっている。Anthropic側もこれを認識していて、後述するフルスクリーンレンダリングという別の描画方式を研究プレビューとして用意している。
症状1: 画面がちらつく・カーソルが飛ぶ場合の直し方
まず CLAUDE_CODE_NO_FLICKER=1 か /tui fullscreen を試す
一番手っ取り早い直し方は、Claude Codeを起動する前に環境変数を1つ足すことだ。
CLAUDE_CODE_NO_FLICKER=1 claudeすでに会話を始めてしまっている場合は、途中からでもコマンドで切り替えられる。
/tui fullscreenこのコマンドを実行すると、Claude Codeは今の会話をそのまま引き継いだ状態でフルスクリーンレンダリング(研究プレビュー機能)に切り替わる。フルスクリーンレンダリングはvimと同じように代替画面バッファに描画する方式で、公式ドキュメントでも「tmux、VS Code統合ターミナル、iTerm2などレンダリングのスループットがボトルネックになりやすい環境で効果が大きい」と明記されている。毎回CLAUDE_CODE_NO_FLICKER=1を打つのが面倒なら、~/.claude/settings.jsonに書いておく方法もある。
{
"env": {
"CLAUDE_CODE_NO_FLICKER": "1"
}
}一度/tui fullscreenを実行すると、その設定(tui設定)が保存されて次回以降のセッションも自動的にフルスクリーンで起動するようになる。元のクラシックな描画方式に戻したくなったら/tui defaultでいつでも切り替えられる。
フルスクリーンにしてもちらつきが残る場合
フルスクリーンレンダリングは「同期出力(DECSET 2026)」という、画面更新を1フレームにまとめて反映する仕組みを使ってちらつきを抑えている。ただしこれは端末側の対応が前提の機能で、Claude Code起動時に端末が同期出力に対応しているかを自動判定している。判定が働かない環境、例えばEmacsのeatのような一部の端末では、対応しているのに自動検出されずちらつきが残ることがある。その場合は以下の環境変数で明示的に同期出力を有効化できる。
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1 claudeもう1つ見落としやすいのがtmux自体のバージョンだ。tmuxは3.6系までのリリースでは同期出力を実装していない。つまりどれだけClaude Code側の設定を詰めても、tmuxが対応していなければフルスクリーンレンダリングでも再描画時のちらつきが直接ターミナルで動かすときより多く出る。tmuxのバージョンをtmux -Vで確認し、古ければアップグレードするか、どうしても直らない場合はそのセッションだけtmuxの外(別タブなど)でClaude Codeを動かすほうが早い。
tmux.conf側でも再描画を減らせる
Claude Code側の設定とは別に、tmux自体の設定で無駄な再描画を減らす方法もコミュニティで共有されている。~/.tmux.confに以下を足しておくと、Escapeキー入力の遅延や小さいペインでの過剰なリサイズ描画が減る。
set -s escape-time 0
set -g aggressive-resize offescape-time 0はEscapeキーを押してから確定するまでの待ち時間をゼロにする設定で、矢印キーなどのエスケープシーケンスを使う操作全般のもたつきを減らす。aggressive-resize offは、ペインを小さくしたときにtmuxが積極的に再描画しようとする挙動を抑える設定だ。どちらもClaude Code専用の設定ではなくtmux全般のチューニングだが、フルスクリーンレンダリングと組み合わせると体感の改善が大きい。
症状2: マウスホイールでスクロールできない・入力欄が動いてしまう場合
原因はtmuxのマウスモードとの競合
フルスクリーンレンダリングに切り替えると、スクロールの主導権がターミナルのネイティブスクロールバックからClaude Code自身に移る。マウスホイールでの操作もClaude Codeが直接受け取って処理する方式に変わるが、これはターミナルがマウスイベントをアプリケーション側に転送してくれることが前提になっている。tmuxの場合、この転送は「マウスモード」がオンになっていないと行われない。
公式ドキュメントでもこの点は明記されていて、~/.tmux.confにマウスモードが有効化されていないと、ホイールイベントはClaude Codeではなくtmux自身に渡ってしまう。設定が入っていない状態でtmux内のClaude Codeを起動すると、起動時に一度だけヒントが表示される仕様になっているので、見覚えがあれば該当するということだ。
対処: set -g mouse on を1行追加する
直し方はシンプルで、~/.tmux.confに1行足してリロードするだけで済む。
set -g mouse ontmux source-file ~/.tmux.confこれでマウスホイールのスクロールがtmuxではなくClaude Code側に渡るようになる。キーボードでのPgUp/PgDnによるスクロールは、マウスモードの設定に関係なくどちらでも動く。
この症状は自分の環境固有のバグではなく、公式リポジトリで継続的に報告されている既知の挙動でもある。マウスホイールを回すと会話ではなく入力欄の履歴が動いてしまう報告や、tmux配下でマウスイベントが正しく渡らずスクロールバック自体が使い物にならなくなる報告など、同種のIssueが複数件オープンになっている時期もあった。「自分の設定がおかしいのでは」と延々調べる前に、まずこの1行を疑ってみる価値はある。
スクロール量が合わない・速すぎる/遅すぎる場合
マウスモードを有効にしても、スクロール1回分の移動量が体感と合わないことがある。特にVS Code統合ターミナルのように、1ノッチごとに1イベントしか送らない端末では遅く感じやすい。その場合は倍率を環境変数で調整できる。
export CLAUDE_CODE_SCROLL_SPEED=33はvimなど他アプリのデフォルトと同じ倍率で、0.25のような小数値も指定できる。設定ファイルに書き込みたくない、その場で感触を確かめながら調整したいという場合は/scroll-speedコマンドを使うと、実際にスクロールしながら←/→キーで倍率を変えられるダイアログが開く。rでリセット、Enterで保存できる。
症状3: tmuxのコピーモードで会話を検索できなくなった場合
フルスクリーンレンダリングでは会話が代替画面バッファの中で管理されるようになるため、tmuxのネイティブなコピーモード(Ctrl+b [)やmacOSのCmd+Fは会話の中身を見つけられなくなる。これは不具合ではなく、会話がターミナルの通常のスクロールバックではなくClaude Code内部の領域に描画されるようになったことの副作用だ。
代わりに用意されているのがCtrl+Oで入るtranscriptモードで、ここではlessに近いキー操作ができる。
| キー | 動作 |
|---|---|
/ | 検索を開く |
n / N | 次/前の一致箇所へ移動 |
j/k または ↑/↓ | 1行スクロール |
g/G | 先頭/末尾へジャンプ |
Ctrl+O、Esc、q | transcriptモードを抜けてプロンプトに戻る |
どうしてもtmuxのコピーモードやCmd+Fを使いたい場合は、transcriptモードに入ってから[キーを押す。これで会話全体(ツール出力も展開された状態)がターミナルのネイティブなスクロールバックに書き出され、tmuxのコピーモードや他の検索ツールからも見えるようになる。この状態はtranscriptモードを抜けるまでの一時的なもので、次にCtrl+Oを押すとまた最新の状態から始まる。
症状4: 通知やプログレスバーがtmuxの外に届かない場合
これはここまでのちらつき・スクロールの話とは別の原因で起きる不具合で、Shift+Enterの改行問題とセットで語られることが多い。tmux配下ではallow-passthroughという設定が入っていないと、デスクトップ通知やプログレスバーの表示がtmuxに吸収されて外側のターミナルまで届かない。この設定と、Shift+Enterをtmux内で使うためのextended-keys設定はセットでまとめて記事にしてあるので、こちらを参照してほしい。
iTerm2の tmux -CC 統合モードを使っている人への注意
iTerm2にはtmux -CCで入る「統合モード」があり、tmuxの各ペインをiTerm2のネイティブな分割ペインとして描画してくれる。ここまで紹介したフルスクリーンレンダリングは、この統合モードとは相性が悪い。統合モードではtmuxが画面に直接描画しない分、代替画面バッファやマウストラッキングが正しく機能せず、マウスホイールが反応しない、ダブルクリックで表示が崩れるといった症状が出る。
普段tmux -CCで運用している場合、Claude Codeはこの組み合わせを検知してデフォルトでクラシックレンダラーのまま起動するようになっている。もし手動でCLAUDE_CODE_NO_FLICKER=1を設定していて統合モードに入っているなら、フルスクリーンレンダリングは切っておいたほうが無難だ。tmux -CCを使わない通常のtmux(iTerm2の中で普通にtmuxを起動するだけの使い方)であれば、ここまでの内容がそのまま当てはまる。
症状別にまとめた tmux.conf
ここまで出てきた設定を1つのファイルにまとめると、以下のようになる。上2行がShift+Enterと通知用、下2行が今回のちらつき・スクロール対策だ。
# Shift+Enterと通知をtmuxの外に届かせる
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
# マウスホイールでのスクロールを有効化
set -g mouse on
# 再描画のもたつきを減らす
set -s escape-time 0
set -g aggressive-resize off編集したらtmux source-file ~/.tmux.confで反映すれば、既存のtmuxサーバーにも適用される。設定を書いた後は一度tmuxセッションから抜けて入り直すか、新しいウィンドウで挙動を確認するとわかりやすい。
FAQ
tmuxを使うのをやめれば全部解決するか
する。今回挙げた症状はどれもtmuxという「もう1枚のレイヤー」があることに起因しているので、tmuxなしで直接ターミナルでClaude Codeを動かせば発生しない。ただしtmuxにはセッションの永続化やペイン分割といった利点があるので、症状を消すためだけにtmux自体をやめるより、この記事の設定で共存させるほうが実務では現実的なことが多い。
フルスクリーンレンダリングとクラシックレンダラー、どちらを使うべきか
tmuxやVS Code統合ターミナルでちらつき・スクロール崩れに困っているなら、フルスクリーンレンダリングを試す価値がある。逆に今の環境で特に困っていないなら、無理に切り替える必要はない。研究プレビュー機能なので、稀に起動に失敗すると自動的にクラシックレンダラーへフォールバックする仕組みも用意されている。
CLAUDE_CODE_NO_FLICKERを設定してもフルスクリーンで起動しないことがあるのはなぜか
同じマシンでフルスクリーンの起動が2回連続で失敗すると、Claude Codeはそれ以降そのマシンではクラシックレンダラーに固定される仕組みになっている。/tuiを引数なしで実行すると、今の描画方式と「起動失敗が理由でクラシックになっている」かどうかが表示されるので、まずそこで状況を確認すると切り分けが早い。
WindowsやWSL環境でも同じ設定でいいか
tmux自体の設定(mouse onやescape-time)はOSに関係なく共通で使える。ただしWindows上でClaude Codeを動かしていて、そこにSSH接続している場合はフルスクリーンレンダリングの対象外になり、自動的にクラシックレンダラーで起動する仕様になっている点は覚えておくといい。
まとめ
tmux上でのちらつき・スクロール不良は、Claude Codeの不具合というより「tmuxという描画レイヤーが1枚増えたことで従来の描画方式が破綻しやすくなる」という構造的な話だ。困ったらまずCLAUDE_CODE_NO_FLICKER=1かフルスクリーンレンダリング、それでもマウスホイールが効かないなら~/.tmux.confにmouse onを足す、この2つを覚えておけばほとんどのケースは片付く。tmuxでの並列開発そのものに興味がある場合は、Git worktreeと組み合わせた運用方法も記事にしてあるので、あわせて読んでみてほしい。
