CLAUDE_CODE_WARN_DISK_FREE_GIBとMEMORY版で空き不足をClaudeに伝える

CLAUDE_CODE_WARN_DISK_FREE_GIBにGiB単位の整数を入れて起動すると、作業ディレクトリのファイルシステムの空きがその値を下回ったとき、Claude Codeが空き容量をsystem reminderとしてClaudeに伝えます。メモリー版のCLAUDE_CODE_WARN_MEMORY_FREE_GIBは同じ仕組みで、対象がLinuxとWSLの利用可能メモリーです。どちらもv2.1.304以降の機能です。

注意点が1つあります。2つとも、起動時の環境に置いた値だけが効きます。settings.jsonのenvブロックに書くと無視されます。

2つの変数は何を警告するのか

Claude Codeの環境変数一覧にある2行が、この機能の仕様のすべてです。

警告の宛先はユーザーの画面ではなく、Claudeです。system reminderは、会話に差し込まれてClaudeだけが読む注意書きの扱いです。Claudeは、空きが少ないという事実を知ったうえで次の操作を選べます。依存パッケージの大量インストールやビルドの前に、空きが足りているかを意識させる狙いと読めます。

ここで公式の記述が止まっている点も押さえておきます。警告を受けたClaudeが実際にどう振る舞うかは、環境変数の説明に書かれていません。止まる、確認する、といった動きを保証する仕様ではなく、「判断材料を渡す」機能だと考えるのが安全です。

値の書き方と、無効になる指定

どちらの変数も、整数のGiBで指定します。無効になる条件は3つ書かれています。

• 変数が未設定
• 値が0
• 値が数字だけの文字列ではない

3つ目の「数字だけではない」は、思ったより広く効きます。次の表は、この規則をそのまま当てはめた結果です。

単位を付けると黙って無効になる点が落とし穴です。エラーにはならないので、書いたつもりで警告が出ないまま気づきにくくなります。

起動環境に置く手順

settings.jsonには書けないため、claudeを起動するシェルの環境に置きます。1回だけ試すなら、コマンドの前に付けます。

CLAUDE_CODE_WARN_DISK_FREE_GIB=10 \
CLAUDE_CODE_WARN_MEMORY_FREE_GIB=4 \
claude

毎回効かせるなら、シェルの設定ファイルにexportを足します。

# ~/.bashrc または ~/.zshrc
export CLAUDE_CODE_WARN_DISK_FREE_GIB=10
export CLAUDE_CODE_WARN_MEMORY_FREE_GIB=4

環境変数は起動時に読まれるので、設定ファイルを書き換えたあとは新しいシェルを開くかsourceし、claudeを起動し直します。動いているセッションには反映されません。

メモリー側は、公式の記述がLinuxとWSLに限られています。macOSでCLAUDE_CODE_WARN_MEMORY_FREE_GIBを設定した場合の挙動は記載がないため、効く前提で運用しないでください。ディスク側は環境の限定が書かれていません。

閾値の決め方の例

公式の例は、ディスクが10、メモリーが4です。これは書き方の見本で、推奨値ではありません。目安を立てるなら、自分の作業で一度に増えるサイズから逆算します。

• 大きなコンテナイメージやモデルファイルを扱う環境は、ディスクの閾値を大きめにする
• ビルドで数GiBを使うことが分かっているなら、その分より少し上に置く
• メモリー側は、普段のビルドやテスト実行でどこまで落ちるかをfree -gで見てから決める

閾値を高く置きすぎると、通常の状態でも警告が出続けます。警告が常時出るなら、Claudeに渡るreminderも常時増えるため、必要になる値より少し手前で止めるのが現実的です。

settings.jsonのenvに書いても効かない

多くの環境変数は、settings.jsonのenvブロックに書けば有効になります。公式はenvの値でシェルの同名変数が上書きされると説明し、ファイルの変更は実行中のセッションにも反映されると書いています。

この2変数だけは別扱いです。環境変数の行に「Claude Codeは、settingsのenvブロック経由で渡されたコピーを無視する」とあります。次の設定は書いても警告を出しません。

{
  "env": {
    "CLAUDE_CODE_WARN_DISK_FREE_GIB": "10"
  }
}

プロジェクトの設定ファイルで全員に共有する形にできない、という意味でもあります。チームで揃えたい場合は、各自のシェル設定、またはclaudeを起動するラッパースクリプトやコンテナ定義の環境変数に入れます。

envで無視される変数には別の分類もあります。設定ファイルのenvで、プロジェクトとローカルの設定が上書きできない変数群です。リポジトリが制御すべきでない変数(CLAUDE_CONFIG_DIRやOpenTelemetryの送信先など)が該当します。今回の2変数は、その一覧とは別に、環境変数の行そのものに「envでは無視される」と書かれた例です。

ディスク警告が測るのは「どこで起動したか」で決まる

ディスク版が見るのは、作業ディレクトリのファイルシステムです。ホームディレクトリではなく、claudeを起動したディレクトリがあるボリュームが対象になります。外付けディスクやネットワークマウント、コンテナのボリュームの上にリポジトリがあるなら、システムのルートに十分な空きがあっても、そのボリュームの空きで判定されます。

起動前に、そのディレクトリで空きを確かめておくと、閾値を決めやすくなります。

cd ~/work/my-repo
df -h .

複数のリポジトリを別々のボリュームに置いている場合、同じ10でも意味が変わります。大きなリポジトリを置くボリュームほど、閾値を余裕のある値にしておくと警告が役に立ちます。

一時ファイルの置き場は、別の話です。Bashの出力ファイルは一時ディレクトリに作られ、CLAUDE_CODE_TMPDIRで場所を付け替えられます。作業ディレクトリと一時ディレクトリが別のボリュームにあるとき、この環境変数が見るのは作業ディレクトリ側だけです。一時ディレクトリ側の容量切れは、後述するdisk quota is fullの診断が対象です。

効かないときの切り分け

警告が出ないときは、次の順に確かめます。

動作の確かめ方

警告が出る状態を人為的に作るには、閾値を現在の空きより大きくします。まず現状の空きを見ます。

# 作業ディレクトリのファイルシステムの空き(GiB 表示)
df -h .
 
# Linux・WSL の利用可能メモリー
free -g

dfの空きが例えば80GiBなら、閾値を99999にして起動すれば、空きが必ず閾値を下回ります。この状態でClaudeに「いま何か通知は届いている?」のように尋ねると、reminderが届いているかを確認できます。

CLAUDE_CODE_WARN_DISK_FREE_GIB=99999 claude

確認が済んだら、変数を外して通常の閾値に戻します。reminderがどんな文面で、どのタイミングで差し込まれるかは公式の記述にないため、上の方法は「届いているか」を見るためのものです。文面の細部は、この確認で実際に見える範囲に留めて扱ってください。

警告を受けたClaudeに動いてもらう

reminderで空きの少なさが伝わっても、どう動くかはClaudeの判断です。動き方を揃えたいなら、CLAUDE.mdに方針を1段落書いておく方法があります。次は書き方の一例です。

## 空き容量の警告が出たとき
 
- システムから空きディスク・メモリーの警告が届いたら、
  新しい依存のインストールや大きなビルドを始める前に、
  何を実行する予定かを私に伝えて確認を取る。
- 不要なビルド成果物やキャッシュは、削除する前に一覧を示す。

警告そのものは情報提供にとどまるので、削除のような取り消しにくい操作は、方針として確認を挟む形にしておくと安全です。権限の面では、削除系コマンドを承認制にしておくと二重に守れます。

発生後のエラーや他の警告との違い

この機能は、空きが減っている段階で伝える予防の仕組みです。すでに空きが尽きたあとに出るエラーは、別の話になります。

• Bashの一時領域が満杯になったときのdisk quota is fullは、disk quotaとswap refusedの記事が扱っています。
• v2.1.274で加わったメモリー使用量が危機的なときの警告は、しきい値が公式に説明されていません。経緯はv2.1.274のリリースノートにあります。自分で閾値を決められるCLAUDE_CODE_WARN_MEMORY_FREE_GIBとは、仕組みが別です。
• agent viewの行に出る注記は、possibly low memoryの記事にまとめています。バックグラウンドセッションが起動前に落ちた場合の説明です。

早めに知らせる変数と、起きたあとの診断は、役割が違います。両方を用意しておくと、容量やメモリーが原因の不具合を早く切り分けられます。

まとめ

CLAUDE_CODE_WARN_DISK_FREE_GIBとCLAUDE_CODE_WARN_MEMORY_FREE_GIBは、整数のGiBを起動環境に置くだけで、空きの不足をClaudeに伝える環境変数です。単位付きの値やsettings.jsonのenv経由の設定は、エラーにならないまま無効になります。まずはdf -h .で現状の空きを見て、いつもの作業で余裕を持てる値を決め、99999で一度だけ届き方を確かめるのが手早い進め方です。