auto-compactとは？Claude Codeの自動コンテキスト圧縮の発動点・/autocompact・無効化の設定

auto-compactは、AIコーディングエージェントの会話がコンテキストウィンドウの上限に近づいたとき、それまでの履歴を要約に置き換えて作業を続けさせる機能です。Claude Codeでは既定で有効で、発動点は「上限の何%」という固定値ではなく、使っているモデルとコンテキスト長で決まります。本記事ではClaude Code 2.1.302（日本時間2026年10月17日公開）の公式ドキュメントと変更履歴をもとに、発動するタイミング、/autocompactでの調整と無効化、席を外している間に走るidle compaction、手動の/compactの使い方、圧縮後に残る情報と消える情報を整理し、Codex CLI・GitHub Copilot・Cline・Gemini CLIの閾値もソースコードで比べます。

まとめ：auto-compactの発動点と設定の要点

• 何をするか：古い会話を要約1本に置き換え、上限でセッションが止まるのを防ぐ。プロジェクト直下のCLAUDE.md・自動メモリ・計画ファイルはディスクから読み直される。
• いつ走るか：既定はモデルのコンテキスト上限に達した時点。1Mトークン窓のモデル（Fable・Sonnet 5以降・Haiku 5.5・Opus 4.7以降）は約967Kで先に走る。「95%で発動」は現行の説明ではない。
• 早めに走らせる：/autocompact 500kで発動点を10万〜100万トークンの範囲で指定する。2.1.288以降は値がモデルごとに保存される。
• 止める：/configの「Auto-compact」をオフ（設定キーautoCompactEnabled: false）。手動の/compactは使い続けられる。
• 放置中の圧縮：20万トークン以上の会話を約54分放置すると、プロンプトキャッシュが切れる前にidle compactionが走る（2.1.299で追加）。止めるなら"idleCompaction": false。
• 手動で圧縮する：/compact 認証まわりの修正方針を残してのように残す内容を指示する。関係ない作業に移るなら/clear。
• 他ツール：Codex CLIは枠の90%以下、Clineは入力予算の90%、GitHub Copilot CLIは約80%、Gemini CLIは50%が既定の発動点（分母はツールごとに異なる）。

auto-compactの仕組み：会話履歴を要約に置き換えるコンテキスト圧縮

LLMは1回のリクエストで読めるトークン数に上限があり、エージェントはその枠にシステムプロンプト・CLAUDE.md・読んだファイル・コマンド出力・会話履歴をすべて詰めて送ります。作業が長引くほど枠は埋まり、上限を超えるとAPIが「Prompt is too long」でリクエストを拒否します。auto-compactはその手前で会話履歴を要約させ、要約と直近の状態だけを持って会話を続ける仕組みです。

要約のリクエストは2.1.198以降、セッションの拡張思考（extended thinking）の設定を引き継ぎます。2.1.284からは、圧縮後のリクエストがまだ長すぎる場合にもう一度、直近の会話をさらに削って圧縮し直すようになりました（Claude Codeの変更履歴）。枠の大きさそのものはコンテキストウィンドウとは？トークン上限の数え方と有効長・溢れ対策を実装者向けに解説で扱っています。

名前の似たAuto Memoryは、学んだことをMEMORY.mdに書き残して次のセッションでも読む機能で、会話を縮めるものではありません（Claude Code Auto Memoryとは？MEMORY.mdの保存場所・読み込み上限と無効化の設定）。

Claude Codeで自動圧縮が走るタイミングとモデル別の既定値

モデルとコンテキスト長で決まる既定の発動点

公式ドキュメントのModel configuration「Default auto-compact thresholds」は、発動点を指定していない場合「会話がモデルのコンテキスト上限に達したときに圧縮する」と定めたうえで、次の例外を挙げています。

検索すると「使用率95%で発動」「64〜75%で発動」という説明が見つかりますが、どちらも現行ドキュメントの記述ではありません。発動点は版ごとに調整されており、2.1.247ではSonnet 5の既定が約934Kから約967Kへ変わっています。社内手順に書くなら、/autocompactで自分で決めた値を書くほうが古くなりません。

ANTHROPIC_BASE_URLでLLMゲートウェイを通している場合、2.1.285からは認識できるモデルにAnthropic API上と同じ1M窓を割り当てます。ゲートウェイ側が200Kで止めるなら/autocompact 200kで発動点を戻します。独自のモデルIDで「isn’t recognized · context assumed to be 200k tokens」と警告が出るときは、modelOverridesで既知のモデルに対応付けるか、CLAUDE_CODE_MAX_CONTEXT_TOKENSで実際の枠を指定します。

残量表示「% until auto-compact」の読み方

入力欄の下に出る「N% until auto-compact」は、発動点までの残りを示す表示です。分母はモデルの最大枠ではなく発動点で、ステータスライン用のused_percentageはモデルの最大枠に対する割合なので、/autocompactで発動点を下げると両者の数字はずれます。何がトークンを食っているかは/contextでカテゴリ別に確認できます。

/autocompactと設定で発動点を変える・無効化する方法

/autocompact・起動フラグ・環境変数・設定キーの優先順位

発動点（公式の用語では auto-compact window）は4か所で指定でき、下の表の上ほど優先されます（Set the auto-compact window）。

2.1.288で/autocompactの保存先が変わりました。それまでは全モデル共通のautoCompactWindowに1つ書いていましたが、現在はユーザー設定のmodelSettingsの下に、そのとき使っているモデルの値として保存します。Opusで/autocompact 300kにしてもFableに切り替えれば元の窓に戻り、/autocompact autoで戻るのも今のモデルの値だけです。同じ設定ファイル内では、モデル別の値がトップレベルのautoCompactWindowより優先されます。

{
  "autoCompactWindow": 500000,
  "modelSettings": {
    "claude-opus-5-5": { "autoCompactWindow": 300000 }
  }
}

上の~/.claude/settings.jsonなら、Opus 5.5は30万トークン、それ以外のモデルは50万トークンで圧縮します。管理設定など上位のスコープが窓を決めている場合、/autocompactは値を保存しても今のセッションには効かず、その旨を表示します。起動フラグ--autocompactだけは上位スコープにも負けません。

指定できる範囲は10万〜100万トークンで、モデルの最大枠を超える値は最大枠に切り詰められます。100〜1000の素の数字は千トークン単位と解釈されるので、200は20万トークンです。範囲外を渡すと起動フラグはその場でエラーになり、2.1.302でclaude --autocompact 50を実行すると次の表示で止まりました（2000k・1.5Mも同じ文面）。

error: option '--autocompact <auto|tokens>' argument '50' is invalid. It must be 'auto', or between 100k and 1M (e.g. 500k, 200000, or 200 as shorthand)

環境変数だけは整数しか受け付けず、500kと書くと500と読まれて下限の10万に丸められます。設定している間は/autocompactで変えられなくなり、コマンドは環境変数が効いていることを表示するだけです。

もう一つの環境変数CLAUDE_AUTOCOMPACT_PCT_OVERRIDEは、auto-compact windowに対する割合（1〜100）で圧縮を前倒しします。モデルの上限より前に圧縮するセッションにだけ適用され、既定より大きい値は無視されるため、発動を遅らせる用途には使えません（Environment variables）。

サブエージェントだけ早めに圧縮する設定

2.1.296から、サブエージェントの定義ファイルのfrontmatterにautoCompactWindowを書けます。長いログを読む調査役だけを20万トークンで圧縮させ、メインの会話は1M窓のまま使う、といった分け方ができます。

---
name: log-reader
description: 長いログファイルを読んで原因箇所を要約する
autoCompactWindow: 200000
---

ここでは必ず整数で書きます。公式ドキュメント（Subagents）によると、frontmatterでは200kが200と読まれて範囲外になり、エラーも出ずに値が無視されます。メインの会話が継ぐ窓より小さい値でないと効かず、--agentでセッション全体をそのサブエージェントとして動かす場合も効きません。無視されたかどうかはclaude --debugのログで確かめられます。サブエージェントの作り方はClaude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】にまとめています。

auto-compactを無効化する設定と、無効にした後の挙動

止め方は3通りあり、手動の/compactまで止めるかどうかで使い分けます。

• /configの「Auto-compact」をオフ：ユーザー設定に"autoCompactEnabled": falseが書かれる。既定はtrue。idle compactionも一緒に止まる。
• DISABLE_AUTO_COMPACT=1：そのセッションだけ自動圧縮とidle compactionを止める。設定と環境変数のどちらかがオフにしていれば、もう一方でオンに戻すことはできない。
• DISABLE_COMPACT=1：自動・手動の両方を止める。

無効にすると、会話は上限まで伸びたところで止まり、対話画面には次の行が出ます。/configで戻せる状態のときだけ、末尾にオフになっている旨が付きます（Error reference「Prompt is too long」）。

Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on

idle compaction：放置中に走る圧縮とプロンプトキャッシュ

2.1.299で、上限とは無関係に走る圧縮が加わりました。長い会話を置いたまま席を外すと、1時間のプロンプトキャッシュが切れる直前に会話を要約しておき、戻ってきて送る次のメッセージで会話全体を読み直させないための機能です。戻ると会話に「Compacted while idle, before the prompt cache expired」と表示されます。公式のSettings reference「idleCompaction」が挙げる発動条件は次の5つで、すべてを満たしたときだけ走ります。

しきい値は環境変数CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENSで変えられ、10万未満の値は10万に引き上げられます。止めるなら設定に"idleCompaction": falseを書くか、2.1.302で加わった/configの「Idle compaction」をオフにします。設定キーは2.1.290以降の版で効き、それより古い版ではautoCompactEnabledを切るしかありません。

ここで判断が分かれます。昼休み後も同じ不具合を追い、必要な途中経過をファイルに残してあるなら、idle compactionを有効に保つことで再開時の入力負荷を抑えられます。20万トークンを超える会話でキャッシュが切れると、戻った最初のメッセージで全履歴を書き込み直す料金がかかるからです。止めるべきなのは、圧縮されると困る途中経過（試して効かなかった手順やエラーの全文）を会話にだけ持っていて、離席前に書き出させる余裕がないときです。キャッシュと料金の関係はClaude Codeの料金プラン比較｜Pro・Max・Team・APIの損益分岐と支出上限の設定【2026年9月】で扱っています。

手動の/compactの使い方と/clearとの使い分け

/compactはその時点までの会話を要約して枠を空けるコマンドで、引数に要約の焦点を書けます。手動圧縮では、その場で残したい内容を引数に指定できます。自動圧縮を含む継続的な要約方針は、プロジェクト直下のCLAUDE.mdにも記述できます。

/compact 認証APIの修正方針と未解決のテスト失敗だけを残して
/compact keep only the plan and the diff

毎回同じ観点で要約させたいなら、プロジェクト直下のCLAUDE.mdに「Compact instructions」の見出しを設けて書いておきます（Manage costs effectivelyの例）。

# Compact instructions
When you are using compact, please focus on test output and code changes

会話の一部だけを縮めたいときは/rewindでメッセージを選び、「Summarize from here」か「Summarize up to here」を選びます。1往復しかない会話で/compactを打つと、要約する履歴がないため「Not enough messages to compact.」と返ります。

判断に迷うのは/clearとの使い分けです。/compactは要約のために会話全体を読ませるので、会話が大きいほど重いリクエストになります。公式のコスト解説は、続きが不要なら/clearは費用がかからないと説明しています。

/clearの前に決定事項をファイルへ書き出させ、新しい会話でそのファイルを読ませる運用なら、再開時に読む情報を自分の目で確認できます。/clearで消した会話も/resumeで呼び戻せます。

圧縮後に残る情報と消える情報

公式ドキュメントContext window「What survives compaction」の対応表を要約すると次のとおりです。

圧縮後も守らせたい規則は、会話で伝えずにプロジェクト直下のCLAUDE.mdへ書きます。paths:付きのルールは圧縮で一度消えるので、必ず効かせたいならpaths:を外すか直下のCLAUDE.mdへ移します。再読込されるファイルも5,000トークンを超えると中身ではなく「Referenced file」としてパスだけが戻ります。大きなスキルは先頭を残して末尾が切り詰められるため、重要な指示はSKILL.mdの冒頭に置きます。バックグラウンドで動かしている開発サーバーなどは圧縮後も止まらず、動いているものがClaudeに知らされるため、同じサーバーを重ねて起動しにくくなっています。CLAUDE.mdの置き方はClaude Codeの使い方｜導入から権限とCLAUDE.md設定まで実務手順にまとめています。

フックで圧縮の前後を制御する：PreCompact・PostCompact・SessionStart

Claude Codeのフックには圧縮専用のイベントが2つあり、マッチャーのmanual（/compact）とautoで対象を絞れます。autoは上限による自動圧縮とidle compactionの両方に当たります（Hooks reference）。

• PreCompact：圧縮の直前に走る。終了コード2か{"decision":"block"}で圧縮を止められる。上限の手前で走る自動圧縮を止めると会話は圧縮されずに続き、APIが上限エラーを返した後の復旧目的の圧縮を止めると、そのリクエストはエラーで失敗する。
• PostCompact：圧縮の完了後に走り、生成された要約がcompact_summaryで渡される。判定には使えず、記録や外部状態の更新向け。
• SessionStart（マッチャーcompact）：圧縮後に走り、標準出力が圧縮後の文脈に追加される。

次の.claude/settings.jsonは、フラグファイルがある間だけ自動圧縮を止め、圧縮のたびに要約をファイルへ追記し、圧縮後に直近のコミットを読み直させる例です。POSIX互換シェルで動くコマンドを使い、要約の保存にはjq、コミットの取得にはGitとコミット履歴のあるリポジトリが必要です。

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "test -f \"$CLAUDE_PROJECT_DIR/.claude/no-auto-compact\" && { echo 'auto-compact paused' >&2; exit 2; }; exit 0"
          }
        ]
      }
    ],
    "PostCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"## \" + .trigger + \" \" + (now|todate) + \"\\n\" + .compact_summary' >> \"$CLAUDE_PROJECT_DIR/.claude/compact-log.md\""
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "git log --oneline -5" }
        ]
      }
    ]
  }
}

PreCompactのコマンドがフラグファイルの有無で終了コード0と2を返すこと、PostCompactのjqが「## auto 2026-10-17T17:30:02Z」の見出しに続けて要約を追記することは、shとjq 1.7.1で確認済みです。autoで止めると放置中のidle compactionも止まるので、長い調査の間だけtouch .claude/no-auto-compactで止め、終わったら消す使い方に限ります。止めたまま上限に達すれば上限エラーになります。イベント全体の書き方はClaude Code Hooksの設定方法｜全33イベント一覧とsettings.jsonの書き方【2026年9月版】を参照してください。

自動圧縮のトラブルと対処：thrashingエラーと指示の消失

「Autocompact is thrashing」の停止条件と対処

圧縮した直後に巨大なファイルやコマンド出力が再び枠を埋めると、圧縮が空回りします。2.1.89以降のClaude Codeは、直前の圧縮から3ターン以内に上限まで埋まることが3回続くと、再試行をやめて「Autocompact is thrashing: the context refilled to the limit…」というエラーで止まります。公式のTroubleshootingが示す対処は次の4つです。

1. 巨大なファイルは行範囲や関数単位で分けて読ませる
2. /compact keep only the plan and the diffのように大きな出力を捨てる焦点で手動圧縮する
3. 大きなファイルを扱う作業をサブエージェントに移し、別の枠で処理させる
4. それまでの会話が不要なら/clearする

/clearの後も同じエラーが出るなら/contextで内訳を見ます。Messagesの行が最大なら上の1〜3をやり直し、それ以外の行（システムプロンプト・ツール定義・メモリファイル）の合計が大きいなら、起動時に読み込む量を減らします。2.1.286以降、モデルのフォールバックで窓が1Mから200Kに落ちたことが原因のときは、エラー文にその旨が出ます。

圧縮後の指示消失と読み込み元の確認

圧縮後に指示が消える場合、置き場所は「会話の中だけ」「未読のサブディレクトリのCLAUDE.md」「まだ該当ファイルに触れていないpaths指定ルール」のどれかで、どれも直下のCLAUDE.mdへ移せば再注入されます。スキルに書いた指示なら、1件5,000トークンを超えた末尾の切り詰めか、合計25,000トークンを超えて古いスキルから外れたことを疑います。スキルの一覧ごと消えたときは/reload-skillsで送り直せます（2.1.299の変更履歴が、圧縮後にスキルを戻す方法として案内しています）。

Codex CLI・GitHub Copilot・Cline・Gemini CLIの自動圧縮との違い

自動圧縮はClaude Code固有の機能ではありませんが、発動点と止め方はツールごとに違います。下の表は2026年10月18日時点の最新タグのソースと公式ドキュメントから既定値を拾ったもので、Codex・Cline・Gemini CLIの値は9月に確認した版から変わっていません。

• Codex CLI：openai_models.rs（rust-v0.163.0）で、発動点を「コンテキスト長×9÷10」と閾値指定（config.tomlのmodel_auto_compact_token_limit、なければモデル情報側の値）の小さい方にしている。既定の集計方法（Total）ではこの値で判定するため、指定しても90%より遅くはならない（既定ではないBodyAfterPrefixという集計方法を選ぶと、設定値がそのまま使われる）。Codex全体の設定はCodex CLIのプロキシ設定・承認モード・オプション一覧｜導入とアンインストール【2026年9月】へ。
• GitHub Copilot：VS Codeのチャットは閾値の数値を公開しておらず、github.copilot.chat.summarizeAgentConversationHistory.enabledをfalseにすると自動圧縮が止まる（VS Code「Manage agent sessions」）。ただしVS Code 1.142.0のagentIntent.tsでは、Responses API側の圧縮管理が有効なモデルにはこの設定が効かず、API側の処理に任される。Copilot CLIは枠の約80%で背景圧縮を始め、残り約20%をその間のツール呼び出しに使い、完了前に約95%まで埋まると一時停止する。システムメッセージとツール定義だけで枠の約75%以上を占める場合は、圧縮しても空く量が少ないため約90%まで待つ（GitHub Docs「Using GitHub Copilot CLI」）。圧縮のたびに要約を番号付きのチェックポイントファイルとしてセッションのワークスペースに残す（GitHub Docs「Managing context in GitHub Copilot CLI」）。Claude Codeで要約を残すなら、前掲のPostCompactフックを使う。
• Cline：compaction-shared.ts（v4.1.25）の定数で、入力予算（モデルが入力上限を報告しない場合は枠×0.9）の90%に達すると発動し、発動点の70%を目標に縮める。agentic compactionの既定設定では、直近履歴の保持予算は20,000トークンで、実際の保持量は設定や要約後の目標量にも制限される。/smolと/newtaskはどちらも/compactの別名。計画機能との関係はClineの/deep-planningとは？Plan/Actとの違いとFocus Chain廃止後の使い方で扱っている。
• Gemini CLI：chatCompressionService.ts（v0.64.0）の既定しきい値が0.5で、設定model.compressionThresholdで変えられる。/compressは履歴の末尾約30%を残す分割点を探し、それより前だけを要約する。

比べると、何を要約せずに残すかの決め方が違います。Claude Codeは最近触ったファイルを最大5件ディスクから読み直し、Clineは直近最大2万トークンの履歴を残し、Gemini CLIは履歴の末尾約30%を残します。ツールを乗り換えたときに「前より忘れっぽい」と感じたら、モデルの差を疑う前に発動点と残し方の違いを確かめてください。

auto-compactを止めるべき場面・任せるべき場面

既定のまま任せてよいのは、機能追加やリファクタリングのように作業の単位が明確で、決定事項がコミットや計画ファイルに残るケースです。圧縮で落ちても、ディスクから読み直される情報で作業を再開できます。

手動に切り替えるべきなのは、途中経過そのものが成果物になる作業です。原因不明の不具合を追うデバッグでは、「試して効かなかった手順」や「一度だけ出たエラーの全文」が要約で落ちると、同じ試行を繰り返させることになります。この種の作業では、節目ごとに/compactへ残す内容を明示するか、PreCompactフックで一時的に止めます。

自動圧縮を恒常的に切る運用は勧めません。無効にした会話は上限（1Mモデルなら1Mトークン）まで伸びてエラーで止まり、そこまでの毎回のリクエストで巨大な履歴を送り続けます。会話を短く保ちたいなら、無効化より/autocompactで発動点を下げるほうが、止まらずに済むぶん安全です。

auto-compactに関するよくある質問

Claude Codeのauto-compactは何%で発動しますか？

固定の割合はありません。2.1.302では、指定がなければモデルの上限到達時が既定で、1M窓のモデルは約967Kトークン、200K枠で動かすモデルは200Kの境界で圧縮します。/autocompactで10万〜100万トークンの範囲に変えられます。

auto-compactをオフにするには？

/configで「Auto-compact」をオフにします。設定ファイルでは"autoCompactEnabled": false、1回のセッションだけなら環境変数DISABLE_AUTO_COMPACT=1です。手動の/compactは引き続き使えます。

/autocompactと/compactの違いは？

/autocompactは自動圧縮が走る発動点を設定するコマンドで、2.1.288以降は値がユーザー設定のmodelSettingsに今のモデルの分として保存されます。/compactはその場で会話を要約するコマンドです。

autoCompactWindowはどこに書きますか？

全モデル共通なら~/.claude/settings.jsonのトップレベルに"autoCompactWindow": 500000のように整数で書きます。特定のモデルだけ変えるならmodelSettingsの下、特定のサブエージェントだけならその定義ファイルのfrontmatterに書きます。

席を外している間に会話が圧縮されたのはなぜですか？

idle compactionです。20万トークン以上の会話を約54分放置すると、プロンプトキャッシュが切れる前に圧縮されます。不要なら"idleCompaction": falseを設定するか、/configの「Idle compaction」をオフにします。

関連記事

• コンテキストエンジニアリングとは？プロンプトエンジニアリングとの違いと4つの実装手法
• コンテキストウィンドウとは？トークン上限の数え方と有効長・溢れ対策を実装者向けに解説
• Claude Code Auto Memoryとは？MEMORY.mdの保存場所・読み込み上限と無効化の設定
• Claude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】
• CodexとClaude Codeの違い｜料金・使用量・設定と併用の判断【2026年版】