ブログ • Claude Code

Claude Code の端末で 20 万 token を超える会話が約 54 分アイドルになったあと、設定 JSON で自動圧縮をどう切るか？

Claude Code 2.1.299 の更新説明は具体的だ。端末で 20 万 token を超える会話が約 54 分アイドルだと、1 時間のプロンプトキャッシュが切れる前に圧縮され、次のメッセージが履歴全体を再処理しなくて済む。圧縮はメッセージ履歴を要約に置き換える。この置き換えを止めるのは settings.json であり、もう一つのプロンプトではない。

Messages API の compaction ブロックに残す項目はその API の記事。セッション、権限、JSON の作業手順はClaude Code の作業手順の記事。本記事は端末のアイドル圧縮だけを書く。いつ履歴を置き換えるか、settings.json のどの二つの項目で切るか、または下限を上げるか。

• 対象は端末セッションで、そのとき 1 時間のプロンプトキャッシュを使っていること。
• 下限は約 20 万 token、アイドルは約 54 分。CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS が変えるのはこの token 下限だけだ。
• 原文を残すなら idleCompaction は真偽値の false にする。文字列の false は形が違う。
• 切ったあとでも、1 時間のキャッシュは期限が来る。次のメッセージは履歴全体を再処理し得る。残るのは、要約に置き換わらない履歴だ。

どの条件で履歴は置き換わるか？

2.1.299 の更新説明は範囲を端末に限る。20 万 token を超える会話が約 54 分アイドルだと、1 時間のプロンプトキャッシュが切れる前に圧縮される。同じ説明に、切る方法と token 下限を変える環境変数があり、どちらも 2.1.290 以上が要ると書いてある。2.1.302 は /config に Idle compaction の一行を足し、圧縮後の案内も切り方を示す。原文はClaude Code の更新説明。

プロンプトキャッシュの文書は同じ出来事をこう書く。端末セッションが 1 時間の TTL 上にあり、長くアイドルだと、Claude Code はキャッシュ期限の少し前に圧縮できる。サブスクリプションのプラン内にある主会話は、既定で 1 時間だ。利用クレジット、API key、クラウド事業者では、主会話の既定は 5 分だ。その文書のアイドル圧縮は、1 時間の場合を指す。切る設定名は idleCompaction、値は false、版はやはり 2.1.290 以上。文書はプロンプトキャッシュの文書。

settings.json にはどの二つを書くか？

一つの項目がオンとオフを決め、もう一つは token 下限だけを変える。env の値は文字列だ。Claude Code は設定ファイルの環境変数を文字列として置く。200000 を数値にすると形が違う。

{
  "idleCompaction": false,
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "200000"
  }
}

圧縮を減らしたいだけで切りたくないなら、その文字列の数字を上げる。更新説明は、この変数が変えるのは 20 万 token の下限だと言い、約 54 分を変えるとは書いていない。2.1.302 以降は /config でも切り替えられ、ファイルを手で直さなくてよい。手で直すときは、やはり真偽値であり、文字列ではない。

この JSON の形はどの Schema で止めるか？

JSON Schema で型を止める。idleCompaction は真偽値でなければならない。env の下限は文字列でなければならない。Schema は切るべきことまでは証明しない。true の形は合法だ。履歴を残すのはアプリの規則で、true を false に戻す。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["idleCompaction"],
  "properties": {
    "idleCompaction": { "type": "boolean" },
    "env": {
      "type": "object",
      "properties": {
        "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": { "type": "string" }
      },
      "required": ["CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS"]
    }
  }
}

圧縮のあと、何が残り、何が置き換わったか？

文書はこう書く。圧縮はメッセージ履歴を要約に置き換えるので、会話層のキャッシュ接頭辞は同じではなくなる。システムプロンプトの層は再利用される。ただし、この再開が、もともと変わるシステムプロンプトを保っている場合は別だ。プロジェクトの文脈はディスクから読み直す。CLAUDE.md とメモリがセッション開始から変わっていなければ、その層はキャッシュに当たる。これは Messages API の記事にある compaction ブロックではない。

/recap は同じ置き換えではない。要約をコマンド出力として足すので、メッセージ履歴もキャッシュ接頭辞も残る。/rewind はより早いターンへ切り戻すのであって、要約を書くのではない。履歴を要約に置き換えるのはアイドル圧縮だ。

Messages API の圧縮記事と何が違うか？

JSONNote でこの設定をどう確認するか？

1. 1
   操作を選ぶ

   JSON Schema を開く。操作する を Schemaで確認してください にする。1つ目の欄に設定、2つ目の欄に上の Schema を貼る。idleCompaction は真偽値だけ。下限を書くなら文字列だけ。

2. 2
   壊れたデータを四つぶつける

   idleCompaction を文字列 false にする、idleCompaction を消す、下限を数値 200000 にする、または env を残して中の下限を消す。この四つは失敗する。上の false の設定は通る。通過は形が正しいことだけを意味する。

3. 3
   false と true を比べる

   JSON 比較Diff。1つ目の欄に idleCompaction が false の設定を貼る。2つ目の欄は idleCompaction だけを true にする。下限の文字列は同じでよい。両方とも Schema は通る。履歴の自動置き換えを止めるのは false であり、この形の確認ではない。

よくある質問

手動の /compact と同じ一度か？

同じ一度ではない。/compact は作業の切れ目に自分で走らせる。アイドル圧縮は、新しいメッセージが約 54 分なく、セッションが約 20 万 token を超え、1 時間キャッシュ上にあるとき、端末が自分で要約へ置き換える。どちらも履歴を置き換える。settings.json の idleCompaction で切れるのはアイドルのほうだけだ。

API key のセッションも 54 分後に圧縮されるか？

文書はアイドル圧縮を、1 時間 TTL の端末セッションに置いている。利用クレジット、API key、クラウド事業者の主会話は、既定の TTL が 5 分であり、1 時間ではない。更新説明の約 54 分は、1 時間キャッシュが切れる前に走るものだ。5 分の枠にこの 54 分を当てはめない。

切ったあと、次の発言はまだ遅いか？

遅くなる。更新説明がこの機能を置く理由は、次のメッセージが履歴全体を再処理しないためだ。切ることは、要約が履歴を置き換えるのを止めるだけだ。キャッシュ期限のあと、次のメッセージは圧縮されていない履歴を再処理し得る。残るのは原文だ。

9 月の Conversation Compaction の記事と同じか？

同じ記事ではない。あちらは Messages API が圧縮の前後でそのまま保存する項目を書き、session を戻す。こちらは Claude Code の端末がアイドル後に履歴を置き換えることと、settings.json で切る方法を書く。どちらも圧縮と呼ばれる。保存する JSON は同じ文書ではない。

ツール引数は圧縮要約に残るか？

2.1.304 が書いているのは、転写ビューの圧縮要約に、以前に呼んだツールの名前が付くことだ。ショートカットは Ctrl+O。引数 JSON 全体が要約に残るとは書いていない。引数がまだ要るなら、圧縮前に自分で写しを保存し、その写しを Schema で確認する。

まとめ

端末で約 20 万 token を超えるセッションが、1 時間キャッシュ上で約 54 分アイドルだと、履歴は要約に置き換わる。CLAUDE.md はディスクから読み直される。ツール名は 2.1.304 から転写要約に出ることがある。引数 JSON は自分で保存する。

結論：履歴を残すなら idleCompaction を真偽値 false にする。下限を変えるなら文字列にする。切ってもキャッシュ期限は止まらない。/recap も /rewind も、このアイドル置き換えではない。

ブログへ戻る