Claude CodeのautoScrollEnabledで全画面の自動スクロールを止める

Claude Codeの全画面表示でスクロールがおかしくなる症状は、大きく2つに分かれます。過去の出力を読んでいるのに画面が最下部へ引き戻される症状と、スクロールした先にメッセージが表示されず空白の領域が出る症状です。前者はautoScrollEnabled、後者はCLAUDE_CODE_DISABLE_VIRTUAL_SCROLLで扱います。原因が違うので、効く設定も別です。

症状で設定を選ぶ

最初に、どちらの症状かを切り分けます。

どちらも、全画面表示(fullscreen rendering)で動いているときの話です。従来のレンダラーで動いているなら、会話は端末自身のスクロールバックに残る仕組みなので、この2つの設定は関係しません。どちらで動いているかの見分け方はClaude CodeのTUI(フルスクリーン)の解説にまとめています。入力欄が、Claudeの作業中も画面下部に固定されていれば全画面表示です。

画面が戻るのは自動追従が働いているから

全画面表示には、新しい出力を追いかけて最下部へ表示を寄せる自動追従があります。上へスクロールすると追従は一時停止し、新しい出力は「Jump to bottom」ボタンと「3 new messages」のような件数で知らされます。ボタンのクリック、Ctrl+End、最下部までのスクロールのいずれかで、追従は再開します。

つまり、既定でも上へスクロールしていれば引き戻されないのが基本です。追従が止まっている間は、応答のストリーミングが終わった時点でも表示位置は動きません。それでも戻されると感じるのは、たとえば次のような場面です。

• 最下部までスクロールした拍子に追従が再開し、そのまま新しい出力へ流される
• MacBookの内蔵キーボードではCtrl+Endに当たるCtrl+Fn+→が届かず、ボタンやホイールで最下部へ戻す操作が増える
• 長いツール出力を遡って読む間、一度も追従を再開したくない

3つ目の用途に向いているのがautoScrollEnabledです。設定のスコープはAny fileで、型はブール値、既定値はtrueです。falseにすると、Claudeが作業を続けても、スクロールした位置に留まります。

{
  "autoScrollEnabled": false
}

置き場所は~/.claude/settings.json(自分の全プロジェクト)、.claude/settings.json(プロジェクトの全員)、.claude/settings.local.json(自分のこのプロジェクトだけ)のいずれかです。個人の好みなので、通常はユーザー設定に置くのが無難です。

設定ファイルを編集しなくても、/configを開いて全画面表示がオンのときに現れる「Auto-scroll」の項目をオフにすれば、同じキーがユーザー設定へ書き込まれます。この項目は全画面表示がオンのときにだけ出ます。出てこないときは、そもそも全画面表示で動いていません。

オフにしても画面に出るもの

autoScrollEnabledをfalseにしても、権限プロンプトのように応答が必要なダイアログは画面内にスクロールされます。許可待ちで止まったまま、見えない位置で待ち続ける事態は避けられます。

オフにしたあとの動き

オフの間は、最下部へ自動では動きません。新しい出力を見たくなったら、自分で最下部へ移動します。

オフのときに最下部へスクロールして追従が戻らないかは、気になる点です。changelogには、v2.1.136で「autoScrollEnabled: falseのときに、最下部へのスクロールで自動追従が再び有効になる不具合を修正」という項目があります。オフに設定していても追従が戻る挙動を見たら、まず手元のバージョンがv2.1.136以降かをclaude --versionで確かめます。

空白が出るのは仮想スクロールの描画が追いつかないとき

もう一方の症状は、追従とは別の話です。全画面表示は、長い会話でもメモリを一定に保つため、表示中のメッセージだけを描画ツリーに保持します。これが仮想スクロールです。スクロールで見える範囲が変わるたびに、必要なメッセージを描き直します。

この方式のスクロール中に、メッセージが表示されるはずの場所が空白になることがあります。環境変数のリファレンスには、全画面表示のスクロールで本来メッセージが出るはずの領域に空白が出るならCLAUDE_CODE_DISABLE_VIRTUAL_SCROLL=1を使う、と書かれています。仮想スクロールを無効にして、トランスクリプトのすべてのメッセージを描画する設定です。

CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL=1 claude

1回だけ試すなら、上のように起動コマンドの前に付けます。効果を確かめて常用するなら、settings.jsonのenvキーに書くと、claudeをどう起動しても有効になります。

{
  "env": {
    "CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL": "1"
  }
}

実行中のセッションは、ファイルの保存で新しい値や変更を環境へ取り込みます。ただし、変数を削除しても実行中のセッションでは解除されず、次の起動から外れます。値は文字列で"1"と書きます。

代償として何が変わるか

全メッセージを描画するので、全画面表示の利点として説明されている「描画するのは表示中のメッセージだけ」という前提から外れます。長い会話ほど描画の負荷は大きくなる側に傾きます。この点は、リファレンスに具体的な数値や影響の説明が載っていないため、手元の端末と会話の長さで確かめるしかありません。空白が出ないことを優先して使い、重さを感じたら外す、という順で試すのが筋です。

空白に見えて別の原因のとき

画面が空白、または一部だけ欠けて見える原因は、仮想スクロール以外にもあります。

• 表示が崩れたり部分的に空白になったりしたら、Ctrl+Lで再描画します。会話と入力中の内容は残ります
• ウィンドウをリサイズするまで前フレームの断片が残るなら、CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1で毎フレーム全セルを再描画します
• 会話ごと消えて見える場合は、スクロールバックが消える問題の切り分けが別にあります。Claude Codeでスクロールバックが消える問題の原因と対処法が扱っています
• Konsoleではスクロール、コピー、再描画に固有の不具合があります。Claude CodeをKonsoleで使うときの不具合にまとまっています

changelogを見ると、全画面表示の空白はこれまでにも個別に修正されてきました。v2.1.259では「数百回のツール呼び出しがある長いターンのあとに、全画面表示で空白の会話が出る」不具合が、v2.1.269では「端末のリサイズ後に、トランスクリプトの上端や下端の行が空白になる」不具合が直っています。空白の症状が出たときは、DISABLE_VIRTUAL_SCROLLを足す前に、最新版へ更新して再現するかを見るのが先です。

2つの設定を併用するとき

2つは独立しているので、両方を設定しても競合しません。たとえば、長いツール出力を遡って読む作業が多く、しかも空白も出る環境なら、次のように書きます。

{
  "autoScrollEnabled": false,
  "env": {
    "CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL": "1"
  }
}

autoScrollEnabledはv2.1.110で追加されたキーです。古いバージョンでは認識されないので、チームで.claude/settings.jsonに入れる場合は、メンバーのバージョンをそろえてからにします。

ほかのスクロール設定との境目

スクロールまわりの設定は複数あり、症状を取り違えると効きません。

CLAUDE_CODE_DISABLE_MOUSE=1は、全画面表示でのマウス追跡を止めます。PgUpとPgDnでのキーボードスクロールは引き続き使えます。ホイールでのスクロールを残しつつクリックやドラッグだけ止めたい場合は、CLAUDE_CODE_DISABLE_MOUSE_CLICKSを使います(v2.1.195以降)。両方を設定した場合はCLAUDE_CODE_DISABLE_MOUSEが優先されます。

設定キー全体の一覧はClaude Code settings.jsonの設定項目一覧にあります。

設定の反映を確かめる

設定を入れたら、次の順に確かめると原因の切り分けになります。

よくある質問

全画面表示をやめれば両方の問題は消えますか

/tui defaultで従来のレンダラーに戻せます。会話は端末のスクロールバックに残り、Cmd+fやtmuxのコピーモードも普通に使えます。ただし、入力欄の固定や描画のちらつきの少なさといった全画面表示の利点も手放します。2つの設定で足りるかを先に試し、足りなければ戻す、という順序になります。