Claude Codeのidle compactionを止める・しきい値を変える

席を離れて戻ったら、会話の先頭に Compacted while idle, before the prompt cache expired と出ていて、細かいやり取りが要約に置き換わっていた。そんなときに触るのが idleCompaction と CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS です。

結論から言うと、完全に止めるならsettings.jsonに "idleCompaction": false、対象を絞るなら CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS で下限を上げます。どちらもClaude Code v2.1.290以降が前提です。仕組みの解説はv2.1.299のリリースノートにあるので、ここでは設定の選び方に絞ります。

圧縮が走る5つの条件を先に確認する

idle compactionは、次の5つがすべて揃った会話にだけ働きます。

1つでも欠ければ圧縮は走りません。つまり「止める」手段は設定キーだけではなく、条件を崩す形でも成立します。ただし、条件を崩す手段は他の挙動も巻き込みます。副作用の小さい順に見ていきます。

idleCompactionをfalseにして完全に止める

いちばん手軽なのは専用キーです。idleCompaction は設定ファイルならどのスコープにも書けます。自分だけ止めたいなら ~/.claude/settings.json、リポジトリ単位で止めたいなら .claude/settings.json です。

{
  "idleCompaction": false
}

既定値は true です。false にすると、放置中の会話は圧縮されません。通常の自動圧縮(コンテキスト上限が近づいたときの圧縮)はそのまま動きます。

ここで押さえたいのは、止めた代償です。放置が1時間を超えると、プロンプトキャッシュが切れた状態で次のメッセージが会話全体を読み直します。長い会話ほど、戻った最初の1通が遅く、トークンも多く消費されます。細部を引き継ぎたい会話と、再処理コストのどちらを優先するかの選択です。

しきい値だけを変えて対象を絞る

「止めるほどではないが、圧縮されすぎる」ときは、環境変数でサイズの下限を動かします。settings.jsonの env に書くと、起動のたびに有効になります。

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "400000"
  }
}

決まりは3つです。

• 既定は 200000
• 正の整数だけが有効で、それ以外の値は無視される
• 100000 未満は 100000 に引き上げられる。下限は10万トークン

上の例では、コンテキストが40万トークンに達した会話だけが対象になります。1Mコンテキストのモデルで長く作業する人が、20万トークン台の会話を要約から守りたいときの調整です。

逆向きの使い方もできます。公式の設定リファレンスには、200Kのコンテキストウィンドウの会話は既定のままでは200,000トークンに届く前に自動圧縮されるため、しきい値を150,000にすると対象になる、という例があります。放置後の再処理を避けたいなら、下げる方向が効きます。

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

値は文字列で書きます。"150000" と引用符で囲む形が、公式の例と同じです。

条件を崩して止める方法と副作用

専用キーを使わなくても、次の設定で結果的に止まります。意図せず止まっていた、という逆引きにも使えます。

通常の自動圧縮まで切る必要がないなら、autoCompactEnabled を切るのは過剰です。idle compactionだけを避けたいときは idleCompaction に任せるのが、巻き込みの少ない選び方です。

v2.1.290より前のバージョンは idleCompaction キーを無視します。その場合に限り、公式は autoCompactEnabled をオフにする方法を案内しています。

効いていない原因を切り分ける

「設定していないのに圧縮されない」「止めたのに圧縮された」を切り分ける順番です。

特に見落としやすいのは、2番目の「1時間TTL」です。Claude Codeは、Claudeサブスクリプションのプラン内使用量の範囲で、メインの会話に1時間のTTLを要求します。APIキー、クラウドプロバイダー、使用量クレジット利用中の既定は5分です。プラン上限を超えてクレジットを使い始めると、メインの会話は5分TTLに落ちます。この場合、放置してもidle compactionは条件を満たしません。

使っているTTLは、次のコマンドで確かめられます。結果の usage.cache_creation に、1時間分の書き込みが ephemeral_1h_input_tokens、5分分が ephemeral_5m_input_tokens として出ます。

claude -p "hello" --output-format json

常時の確認にはstatuslineを使う方法もあります。やり方はprompt cache warmの確認法にあります。TTLが突然5分になった事例はキャッシュTTLの短縮問題で扱っています。

1時間TTLを自分で選ぶと、idle compactionの対象になる

APIキー利用者は、メインの会話に1時間TTLを自分で指定できます。promptCacheTtl を "1h" にする方法です。

{
  "promptCacheTtl": "1h"
}

この指定はidle compactionの条件の1つ(1時間TTL)を満たす方向に働きます。つまり、5分TTLで動いていた会話が、設定によって圧縮の対象に変わりえます。1時間TTLはキャッシュの書き込みが高い料金で課金されるため、長い休憩の多い使い方では得になり、短い作業の連続では割高になります。

優先順位は、FORCE_PROMPT_CACHING_5M が最優先、次に CLAUDE_CODE_PROMPT_CACHE_TTL、次に promptCacheTtl、最後に ENABLE_PROMPT_CACHING_1H です。5分を強制すると、メインの会話は1時間TTLの条件から外れます。

利用形態別に、既定でどう動くか

キャッシュTTLの既定は課金の形で変わります。そのため、idle compactionが既定で働くかどうかも、使い方で分かれます。TTLの表と、5つの条件から組み立てた早見表です。

APIキーで1時間TTLを選ぶと、放置後の再処理が減る代わりにidle compactionの対象にもなります。この2つはセットで考えます。逆に言えば、「要約を挟みたくないが、キャッシュは長く持たせたい」場合は、promptCacheTtl: "1h" と idleCompaction: false を併用する組み合わせになります。

{
  "promptCacheTtl": "1h",
  "idleCompaction": false
}

この構成では、1時間以内に戻ればキャッシュが効きます。1時間を超えて戻ると、要約なしで会話全体が再処理されます。

54分という数字の意味

設定リファレンスは、圧縮のタイミングを「プロンプトキャッシュが切れる直前」と説明しています。1時間のTTLに対して約54分なので、期限の約6分手前です。この間に圧縮を済ませれば、戻って送る最初のメッセージが運ぶのは全文ではなく要約になります。

54分に届く前に戻れば、キャッシュがまだ効いており、圧縮は起きません。54分から1時間の間は、戻っても要約済みの状態になります。席を外す時間が50分前後の人は、境目をまたぐことになるため、切るかどうかを一度決めておくと挙動が読みやすくなります。

書き込み先とバージョンの確認

設定キーの対象スコープは「どの設定ファイルでも可」です。個人の好みならuserの ~/.claude/settings.json、リポジトリ単位で揃えたいならprojectの .claude/settings.json、チームに配りたくない手元だけの調整なら .claude/settings.local.json に置き分けられます。しきい値の環境変数は env ブロックに書けば同じ置き場所で扱えます。

もう1つ、バージョンの食い違いに注意が要ります。設定リファレンスと環境変数の一覧は、キーも変数も「v2.1.290以降」と書いています。一方で更新履歴は、idle compactionをv2.1.299の「追加」に載せ、同じ行に「どちらもv2.1.290以降が必要」と添えています。設定が効かないときは、まず claude --version で手元のバージョンを見て、v2.1.290以降かどうかを確かめます。

claude --version

設定を入れた後は、放置して戻ったときの表示で効き目を判断できます。Compacted while idle, before the prompt cache expired が出なくなれば、止まっています。

設定の選び方の目安

圧縮の挙動そのものはコンテキスト圧縮の解説に、通常の自動圧縮の調整はautocompactの設定にまとめています。

よくある質問

idle compactionが走ったあと、元の会話に戻せますか

この仕様について、設定リファレンスに復元の記載はありません。細部を残したい会話は、放置する前に自分で要約させるか、idleCompaction を切ってから離席する運用が確実です。

会社のネットワークで通信を絞っていると動きませんか

動かない場合があります。条件の1つが「Anthropicからフィーチャーフラグを取得できること」です。DISABLE_GROWTHBOOK、DISABLE_TELEMETRY、DO_NOT_TRACK、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC のいずれかを設定した環境や、Bedrockなどのサードパーティプロバイダーの環境ではフラグ取得が行われません。

自動圧縮を切ると手動の /compactも使えなくなりますか

使えます。設定リファレンスは、自動圧縮をオフにしても手動の /compact は動き続けると説明しています。idle compactionを避けたい人が、離席前に自分で /compact を打って要約の内容を確かめてから席を立つ、という使い方も成り立ちます。ただし DISABLE_COMPACT=1 は自動と手動の両方の圧縮を止める変数なので、手動の圧縮を残したいときは選びません。