Claude Media
CLAUDE_CODE_TRANSCRIPT_LOCAL_GCで-pの履歴肥大を抑える
Claude CodeAgent SDKTips

CLAUDE_CODE_TRANSCRIPT_LOCAL_GCで-pの履歴肥大を抑える

-pやAgent SDKの長いセッションで膨らむtranscriptを、コンパクション後に5MB超なら前の履歴を削って抑える環境変数です。起動環境でしか指定できない点と、resumeで会話が変わらない点を扱います。

読了目安 約9分

CLAUDE_CODE_TRANSCRIPT_LOCAL_GCは、-pやAgent SDKで動かす長いセッションのtranscriptファイルが大きくなり続けるのを抑える環境変数です。1にすると、コンパクションのたびにファイルサイズを見て、5MBを超えていれば、そのコンパクションより前の履歴を削ります。v2.1.287以降で使えます。

指定できる場所に制約があります。設定ファイルのenvブロックでは有効になりません。claudeを起動する環境で指定します。

どんなtranscriptが膨らむのか

Claude Codeは会話を、既定で~/.claude/projects/<project>/<session-id>.jsonlにJSONLで保存します。1行がメッセージ、ツール呼び出し、メタデータのどれかに当たります。<project>は作業ディレクトリのパスから英数字以外を-に置き換えた名前です。

対話セッションは人が区切ることが多く、ファイルは大きくなりにくい傾向があります。一方、-pやAgent SDKで長時間回し続けるエージェントは、1つのセッションIDのまま何度もコンパクションを挟んで走り続けられます。ファイルが大きくなるほど、保存先の容量や再開時の読み込みが気になってきます。

変数名のLOCAL_GCが示すとおり、対象はローカルに置かれたtranscriptファイルです。モデルに送る文脈の量を変える設定ではありません。

何が起きるのか

動作は次の3段階です。

手順

この変数が働く流れ

  1. 1

    コンパクションが起きる

    セッションの文脈が埋まり、履歴が要約に置き換わります。

  2. 2

    ファイルサイズを見る

    transcriptファイルが5MBを超えているかを判定します。

  3. 3

    前の履歴を削る

    超えていれば、そのコンパクションより前の履歴をファイルから取り除きます。

判定はコンパクションのあとにだけ走ります。コンパクションが一度も起きないセッションでは、ファイルが5MBを超えても何も削られません。短い-pの1回実行には効かない変数だと分かります。

5MBという値を変えるキーは、env-varsのこの変数の行に載っていません。しきい値に合わせた運用を組むなら、5MBを前提に考えます。

コンパクションはいつ起きるのか

削る処理の入口はコンパクションなので、いつ起きるかが効き方を決めます。env-varsの表には、コンパクションまわりの変数が並んでいます。

変数働き
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE働き自動コンパクションが働く割合(1〜100)を指定する。50のように下げて早めに起こせるが、既定の割合より上げる指定は無視される
CLAUDE_CODE_AUTO_COMPACT_WINDOW働き自動コンパクションの対象ウィンドウをトークン数(100000〜1000000)で指定する。500kのような書き方は受け付けず、整数で渡す
DISABLE_AUTO_COMPACT働き1で自動コンパクションを止める。手動の/compactは使える
DISABLE_COMPACT働き1で自動・手動のコンパクションをすべて止める

DISABLE_COMPACTを付けたジョブでは、コンパクションが起きないので、CLAUDE_CODE_TRANSCRIPT_LOCAL_GCを付けても削る処理に到達しません。この2つは同じ起動環境に置いても噛み合いません。

反対に、CLAUDE_AUTOCOMPACT_PCT_OVERRIDEで割合を下げると、コンパクションの回数が増えます。判定の機会が増えるぶん、ファイルが5MBを超えた時点で刈り取られやすくなります。env-varsとsessionsのページには、手動の/compactのあとにも5MBの判定が走るかどうかの記述がありません。自動コンパクションだけで長いジョブが回るなら迷いませんが、手動に頼る運用では、挙動を実際のファイルサイズで確かめる必要があります。

resumeしても会話は変わるのか

削ったかどうかにかかわらず、セッションをresumeすれば同じ会話が復元されます。ファイルが軽くなることで、再開時に別の文脈になることはありません。

ここで押さえたいのは、削られた履歴はそのファイルから消えるという点です。会話の続きには影響しませんが、コンパクション前のやり取りをtranscriptから後で読み返したい運用とは相性が悪くなります。

  • 後から全ログを監査したい、または/exportなどで全文を取り出したい運用では、この変数を有効にする前にバックアップの手段を決めておきます
  • env-varsの当該行にもAgent SDKのセッション管理ページにも、外部ストアへミラーするアダプタとの組み合わせは載っていません。Agent SDKのSessionStoreを使う構成では、検証用のジョブで挙動を確かめてから本番に載せる構成が取れます

SDKで別ホストからresumeするときの注意

Agent SDKのセッション管理ページによると、セッションファイルはそれを作ったマシンのローカルにあります。CIワーカー、短命なコンテナ、サーバーレスのように実行ホストが変わる環境では、次の3つから選びます。

  • sessionStore(Pythonではsession_store)のアダプタを渡し、transcriptを自前のバックエンドにミラーして、別ホストから再開する
  • ~/.claude/projects/<encoded-cwd>/<session-id>.jsonlを最初の実行後に保存し、新しいホストの~/.claude/projects/配下に戻してからresumeする
  • resumeに頼らず、分析結果や決定事項などをアプリ側の状態として持ち、新しいセッションのプロンプトに渡す

2つ目の「ファイルを持ち回る」方式は、この変数と相性が良い構成です。持ち回るファイルが小さくなり、保存先やコピー時間の負担が減ります。resume自体は、削った後でも同じ会話を復元します。

resumeにはセッションIDが要ります。IDは、結果メッセージのsession_idフィールドから読めます。成功でもエラーでも付いてくる項目なので、長いジョブの終了処理でIDを記録しておけば、次回のresumeで渡せます。ジョブが上限(error_max_turnsなど)で止まったときも、IDを残していればそこから再開できます。

指定できる場所と、できない場所

env-varsの当該行に明記されているとおり、設定ファイルのenvブロックでは有効にできません。多くの環境変数はsettings.jsonのenvに書けますが、この変数はそうではありません。

指定場所有効か
claude -pを起動するシェルの環境有効か有効
CIジョブやコンテナの環境変数有効か有効(起動環境に当たる)
settings.jsonのenvブロック有効か無効

Agent SDKでは、TypeScript版のenvオプションが、起動するサブプロセスの環境を決めます。TypeScript SDKのリファレンスによると、このオプションを渡すとprocess.envにマージされず置き換えになります。PATHなどを残すため、{ ...process.env, 変数: '値' }の形で渡す案内があります。SDKからこの変数を有効にするなら、このオプションが起動環境の入口になります。

// 例えば次のような形になります(envオプションの説明に沿った書き方)
const options = {
  env: { ...process.env, CLAUDE_CODE_TRANSCRIPT_LOCAL_GC: "1" },
};

シェルから-pを回すなら、変数を前置きして起動します。

CLAUDE_CODE_TRANSCRIPT_LOCAL_GC=1 \
  claude -p "リポジトリ全体のテスト失敗を順に直して"

設定ファイルに書いても動かないので、settings.jsonで環境変数を配る運用の組織は注意が要ります。ジョブのランチャーやコンテナ定義の側に置きます。

効いているかを確かめる

効果は、transcriptファイルのサイズで見られます。保存先は既定で~/.claude/projects/<project>/です。CLAUDE_CONFIG_DIRを変えている場合は、その配下のprojects/を見ます。

ls -lh ~/.claude/projects/*/*.jsonl | sort -k5 -h | tail

有効にしたセッションでは、コンパクションのあとにコンパクション前の履歴が取り除かれるので、有効にしていないセッションとサイズの伸び方が変わります。変数を付けた実行と付けない実行を同じ負荷で2本回し、コンパクション回数が揃ったところで見比べると差がはっきりします。

似た設定との使い分け

transcriptまわりの変数は役割が違います。sessionsのページにある表から、目的別に並べ直します。

やりたいこと使うもの
長い-p・SDKセッションのファイルサイズを抑える使うものCLAUDE_CODE_TRANSCRIPT_LOCAL_GC
古いセッションを日数で削除する使うものcleanupPeriodDays(settings.json)
プロジェクト単位でtranscriptと関連状態をすぐ消す使うものclaude purge <パス>
transcriptを一切書かない(全モード)使うものCLAUDE_CODE_SKIP_PROMPT_HISTORY
-pの1回だけ書かない使うもの--no-session-persistence
保存先を~/.claudeの外へ移す使うものCLAUDE_CONFIG_DIR

見分けるときの軸は「セッションの中身を削るか、セッションごと消すか」です。cleanupPeriodDaysは古いセッションをまとめて消す日数の設定で、1つのセッションの内側は触りません。この変数は、生きているセッションの内側にある古い履歴を削ります。保持日数の細部はcleanupPeriodDaysの記事にあります。

日数による削除の既定は30日で、最小は1日です。0を指定すると検証エラーになります。対象にはprojects/<project>/<session>.jsonlの会話transcriptが含まれます。この掃除は「古いファイルをまるごと消す」処理で、5MBを超えたファイルの前半だけを削るこの変数とは働く単位が違います。両方を有効にした場合、30日を超えたセッションはファイルごと消えるので、再開もできなくなります。

claude purgeは、指定したプロジェクトのtranscriptと自動メモリ、セッションごとのtasks/・debug/・file-history/、history.jsonlの該当行、~/.claude.jsonのエントリを消します。--dry-runを付けると、削除の計画だけを表示して終わります。v2.1.288より前のコマンド名はclaude project purgeでした。

バックグラウンドセッションをclaude rm <id>で削除しても、transcriptはディスクに残り、claude --resumeで再開できます。「消したつもりで残っている」ケースがここにあります。

CLAUDE_CODE_SKIP_PROMPT_HISTORYは書き込み自体を止めるので、resumeもできなくなります。肥大を抑えつつresumeを残したいなら、選ぶのはこの変数です。

有効にする前に確認すること

  • 使っているClaude Codeがv2.1.287以降であること。この変数はv2.1.287以降が必要です
  • 起動環境で渡すこと。settings.jsonのenvブロックでは有効になりません
  • 長時間走らせる-pやSDKセッションであること。短い実行ではコンパクションが起きず、削る処理に到達しません
  • DISABLE_COMPACTを付けていないこと。コンパクションが止まっていると、この変数は働く機会を持ちません
  • コンパクション前の履歴をtranscriptから読み返す運用がないこと。削った履歴は戻せません

再開まわりの基本は、Agent SDKのセッション管理とセッションエクスポートの記事で押さえておくと、削った後の動きを読み違えません。

まとめ

ファイルが重いと困るのは、長く回す-pとSDKの常駐エージェントです。そこにCLAUDE_CODE_TRANSCRIPT_LOCAL_GC=1を起動環境で渡せば、再開時の会話を変えずに、コンパクション後にファイルが5MBを超え続けるのを抑えられます。その代わり、コンパクション前の履歴はそのファイルからなくなります。ログを全文で残す必要があるジョブでは、別の保存手段を用意してから使います。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →