Claude Media
fileCheckpointingEnabledでチェックポイント機能を無効化する
Claude CodeTips

fileCheckpointingEnabledでチェックポイント機能を無効化する

settings.jsonのfileCheckpointingEnabledをfalseにすると、編集前のファイルスナップショットが止まります。無効化で失う機能と、無効化してもよい場面を判断基準つきでまとめます。

読了目安 約11分

Claude Codeは既定で、ファイルを編集する前にその中身を~/.claude/file-history/へ保存しています。settings.jsonのfileCheckpointingEnabledをfalseにすると、この保存が止まります。代わりに/rewindでコードを元に戻せなくなります。

設定は1つのbool値です。ただ、環境変数との関係、-p実行での扱い、既存データの寿命など、意外な挙動がいくつかあります。以下は公式ドキュメントとClaude Code v2.1.289の--help出力に基づきます。

fileCheckpointingEnabledは何を止める設定か

チェックポイントは、ユーザーがプロンプトを送ってターンが始まるたびに、その時点のコードの状態を記録する仕組みです。fileCheckpointingEnabledはその記録を行うかどうかを決めるキーで、既定値はtrueです。/configにはRewind code (checkpoints)という項目名で並び、そこで切り替えるとユーザー設定にこのキーが書き込まれます。

falseにすると、Claude Codeは編集前のスナップショットを取らず、/rewindはコードを復元できません。会話のほうは別物です。チェックポイントはセッションの会話と一緒に保存されるので、会話の巻き戻しや「ここから要約」はファイルの記録とは独立した操作として残ります。

切り方は2つ、どちらかがオフなら止まる

無効化の入口は設定キーと環境変数の2つです。両者の関係は「どちらが優先か」ではなく、片方でもオフにすれば止まり、もう片方でオンに戻せない形です。

くらべる

設定キーと環境変数の使い分け

恒久的に切る

settings.json

fileCheckpointingEnabled: falseを書くと、そのファイルの適用範囲で止まります。ユーザー設定なら全プロジェクト、リポジトリの.claude/settings.jsonならそのプロジェクトだけです。

1セッションだけ切る

環境変数

CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING=1を付けて起動したセッションだけ止まります。設定ファイルには何も残りません。

設定ファイルの例は次のとおりです。

{
  "fileCheckpointingEnabled": false
}

環境変数で一時的に切るときは、起動前にシェルで設定します。

export CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING=1

環境変数の説明には「fileCheckpointingEnabledの設定を上書きする」とあります。一方、設定キー側の説明では「どちらかがオフにした場合、もう一方でオンに戻すことはできない」とされています。たとえば設定ファイルでfalseにしたまま、環境変数で0を渡しても復活はしません。設定ファイルの置き場所や優先順位の全体像はClaude Code設定ガイドにあります。

-p実行とAgent SDKでは、このキーは読まれない

CIや自動化ジョブでclaude -pを使っている場合は注意が要ります。-p実行とAgent SDKのセッションでは、Claude CodeがfileCheckpointingEnabledを無視するためです。SDKはチェックポイントをenableFileCheckpointingオプションで有効にし、素の-p実行ではCLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=trueを渡さない限りチェックポイントは働かない仕様です。

つまり「CIの負荷を減らすために切る」という動機でfileCheckpointingEnabledやCLAUDE_CODE_DISABLE_FILE_CHECKPOINTINGを足しても、-p実行では効果の出る余地がありません。この設定が実際に意味を持つのは、対話セッションで/rewindを使える状態のときです。環境変数一覧はClaude Code環境変数リファレンスにまとめています。

無効化を検討するのはどんなときか

無効化の実益は、スナップショットの量と残り方に表れます。仕様上の事実から並べます。

  • 保存される量には上限がある: ファイルのスナップショットは、セッションごとに直近100件のチェックポイント分が保持されます。古いチェックポイントを捨てると、どの残存チェックポイントからも参照されないスナップショットは削除されます。ただし各ファイルの最初のスナップショットは、VS Code拡張機能がセッション差分の基準に使うため残ります
  • 編集前の中身がコピーとして残る: file-history/には、Claudeが変更したファイルの編集前の姿が入ります。.envのように値を書き換える作業をした場合、書き換え前の内容も一定期間ディスクに残ります
  • 残る期間はcleanupPeriodDaysが決める: セッションのスナップショットは、最後に保存してから既定で約30日後の掃除処理で削除されます

判断の分かれ目は「/rewindのコード復元を使っているか」です。複数の実装方針を試して比べる、失敗した変更をすぐ戻す、といった使い方があるなら、コード復元を失う代償は大きくなります。そうした使い方では、無効化の前にcleanupPeriodDaysで保持期間を短くする選択肢もあります。

手順

無効化を決めるまでの3手順

  1. 1

    今のディスク消費を見る

    du -sh ~/.claude/file-history/で全セッション分の合計を確かめます。目安として、数十MBなら無効化する実益は薄く、GB単位なら原因のプロジェクトを探す価値があります。

  2. 2

    /rewindを最近使ったか思い返す

    コード復元を使っていないなら無効化の代償は小さくなります。使っているなら、保持期間を縮めるだけで足りないか考えます。

  3. 3

    範囲を決めて書く

    機微なファイルを扱うプロジェクトだけなら、そのリポジトリの.claude/settings.jsonに書きます。全体で使わないなら、ユーザー設定に書きます。

無効化すると残るもの、失うもの

無効化しても、会話の巻き戻しと要約は使えます。失うのは、これから先の編集に対するコード復元です。もともと/rewindが戻せなかったものは、無効でも有効でも同じ扱いになります。

対象外

有効のままでも戻せないもの

  • Bashコマンドの変更

    rm・mv・cpのように、シェル経由で変えたファイルは追跡されません。追跡されるのはClaudeのファイル編集ツールによる変更だけです。

  • サブエージェントの編集

    フォアグラウンドで動くcontext: forkのスキルだけは、自分のターン内の編集なので戻せます。それ以外のサブエージェントの編集は、gitで戻す前提です。

  • シンボリックリンク・ハードリンク

    復元時に該当パスはスキップされ、Restored the code, but skipped N filesという警告が出ます。dotfile管理ツールが貼ったリンクや、pnpmがハードリンクしたファイルが該当します。

追跡の対象になるのは、そのセッションでClaudeが編集したファイルだけです。自分でエディターから書き換えた変更は記録されません。並行して動かした別セッションの編集も、同じファイルに触れた場合を除いて記録されません。

作業中にキューへ入れたメッセージがそのターンに合流したときも、そのメッセージ用のチェックポイントは作られず、/rewindの一覧にも出ません。取り消したいときは、そのターンを始めたプロンプトまで戻します。すると、合流前にClaudeが済ませた作業も含めて、ターンごと巻き戻ります。

既存のスナップショットは、無効化しても自分では消えません。ただし前節のとおり、掃除処理が約30日後に削除します。今すぐ消したいならclaude purgeを使います。v2.1.288より前はclaude project purgeでしたが、現在はclaude purgeが正で、claude project purge --helpにも次の案内が出ます。

claude purge --help

v2.1.289の出力は次のとおりです。

Usage: claude purge [options] [path]
 
Delete all Claude Code state for a project (transcripts, tasks, file history,
config entry)
 
Options:
  --all              Purge state for every project (mutually exclusive with
                     [path])
  --dry-run          List what would be deleted without deleting anything
  -h, --help         Display help for command
  -i, --interactive  Prompt for each item before deleting
  -y, --yes          Skip confirmation prompt

注意したいのは、削除対象がfile-history/だけではない点です。プロジェクトの会話履歴(transcripts)、タスク、デバッグログ、history.jsonlの該当行、~/.claude.jsonのプロジェクト項目、projects/配下の自動メモリー(auto memory)まで消えます。自動メモリーを使っている場合は、これも失われます。スナップショットだけを処分したいときに使うコマンドではなく、先に--dry-runで消える一覧を確かめてから実行します。

戻したくても戻せないときの症状

チェックポイントを無効にしていなくても、復元に失敗する場面があります。無効化との切り分けは、次の症状で見分けます。

症状想定される原因
/rewindにコード復元の項目が出ない想定される原因選んだ時点に追跡済みの編集がない。無効化中も戻せる対象がないので、同じ見え方になる
No files were restored想定される原因保存したバックアップが消えた、またはファイルを書き換えられなかった
Restored the code, but skipped N files想定される原因リンクや、チェックポイント以降に構造が変わったパスを安全のためスキップした

2行目は、掃除処理が約30日後にバックアップを消したあとで古いセッションを再開した場合に出ます。再開後も/rewindは一覧を表示しますが、復元は失敗します。3行目の詳しい原因は、公式のエラー一覧にあるスキップ理由の項に載っています。復元の使い方や対象外の挙動はClaude Code rewindコマンドで扱っています。

VS Code拡張機能のチェックポイント

VS Code拡張機能にもチェックポイントがあり、メッセージにカーソルを合わせると出るrewindボタンから3つを選べます。

  • 会話だけを分岐する「Fork conversation from here」
  • コードだけを戻す「Rewind code to here」
  • 両方を行う「Fork conversation and rewind code」

CLI側で/rewindを使うときは、Escを2回押しても同じメニューが開きます。ただし入力欄に文字が残っていると、2回押しは入力を消すだけで終わります。CLIの/rewindとは並びが違いますが、追跡対象は同じくClaudeのファイル編集ツールによる変更です。

よくある質問

無効化したあとでも、設定を戻せば/rewindでコードを戻せますか

戻せるのは、再度有効にしたあとに取られたスナップショットだけです。無効だった間の編集には記録がないので、その区間のコードは復元できません。

同じセッションの途中で切り替えるとどうなりますか

settings-referenceとenv-varsの説明に、途中で切り替えた場合の挙動の記載はありません。環境変数は「1セッションのオフ」として説明されているので、確実に止めたいときは、起動前にCLAUDE_CODE_DISABLE_FILE_CHECKPOINTING=1を付けてセッションを開始します。

まとめ

fileCheckpointingEnabled: falseは、ディスクに残る編集前コピーを減らす代わりに、これからの編集のコード復元を手放す設定です。-p実行には元から効かないので、使うかどうかは対話セッションでの/rewindの利用頻度で決まります。ワークフロー全体のなかでの位置づけはClaude Codeワークフローにあります。

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

関連する記事

Claude Code をもっと見る →