CLAUDE_CODE_TOOL_MEMORY_LIMITでBash・PowerShellのメモリを制限する

CLAUDE_CODE_TOOL_MEMORY_LIMITは、LinuxとWSL上でBash・PowerShell・Monitorツールが実行するコマンドのメモリ使用量に上限をかける環境変数です。ビルドやテストの暴走で1本のコマンドがメモリを食い尽くし、セッション全体の動作が重くなる事態を防ぎます。v2.1.233で追加され、2026年8月10〜14日のWeek 33アップデートで告知されました。

対象のOSとツール

対応するのはLinuxとWSL(Windows Subsystem for Linux)のみです。macOSやネイティブのWindows環境では、この変数を設定しても何も起きません。

制限がかかるのはBashツールとPowerShellツール、そしてMonitorツールが実行するコマンドの3種類です。ただしMonitorツールが対象に入ったのはv2.1.246以降で、それより前のバージョンではMonitorのコマンドはキャップの外で動いていました。古い版の情報を前提に「Monitorも常に制限される」と思い込むと、実際の挙動と食い違います。Bashツールのシェル関数捕捉はzoxideが使えない原因でも扱っています。

なぜLinux/WSL限定なのか

この上限を実現しているcgroup(control group)は、Linuxカーネルが持つリソース管理の仕組みです。macOSの基盤であるDarwinカーネルにも、ネイティブのWindowsにもcgroupは存在しません。WSLは仮想化されたLinuxカーネルをそのまま動かす仕組みなので、Linuxと同じcgroupが使えます。対応環境がLinuxとWSLの2つに限られているのは、機能を絞っているのではなく、cgroupという実装手段そのものがこの2つの環境にしか存在しないためです。

値の書き方

サイズはバイト数の数字だけ、またはK・M・G・Tのいずれかの接尾辞を付けて書きます。上限を切りたいだけなら4Gのように書けば十分で、正確なバイト数を計算する必要はありません。

読み取れない値を入れても、Claude Codeはエラーを出さずに単に無視します。設定したつもりで上限がかかっていない場合は、まず値の書式を疑うのが早道です。

上限はセッション全体で共有される

この変数が管理するのは「1つのセッション内のBash・PowerShell・Monitorコマンド全体」で使えるメモリの合計量です。コマンドごとに個別の上限が割り当てられるわけではありません。したがって、複数のコマンドを並行して実行している状況では、どれか1本が多くのメモリを使うと、残りのコマンドが使える余地がその分だけ減ります。

たとえば4Gを設定した状態で、Bashツールから2つのビルドコマンドを同時にバックグラウンド実行したとします。片方が3ギガバイトを使うと、もう片方に残るのは1ギガバイト分だけです。個別に4ギガバイトずつ確保できるわけではない点は、並列実行を前提にした値を決めるときに意識しておく必要があります。

cgroupで実現する仕組みと、失敗したときの挙動

Claude Codeはこの上限をLinuxのメモリcgroup(control group)で実現します。cgroupのセットアップに失敗する環境では、コマンドはキャップなしでそのまま実行され、なぜ失敗したかはclaude --debugで起動したときのデバッグログにだけ出力されます。通常の実行画面には失敗の理由が表示されません。

コンテナ環境や権限が制限された実行基盤では、cgroupを作る権限自体が無いことがあります。「環境変数を設定したのに上限が効いていない気がする」というときは、まずclaude --debugのログを確認する価値があります。

上限に達すると何が起きるか

たとえば4Gに設定した環境で、Bashツールからモノレポ全体のビルドやDockerイメージのビルドを実行し、そのプロセスが4ギガバイトを超えるメモリを確保しようとしたとします。この場合、Linuxカーネルがそのプロセスを強制終了します。

値の変更はセッションの再起動まで反映されない

Claude Codeが起動する最初のプロセスが、このキャップを有効化または無効化した時点で、その状態はセッションを再起動するまで固定されます。つまり実行中のセッションで環境変数の値を書き換えても、claudeコマンドを新しく起動し直すまでは反映されません。有効から無効へ、あるいは値の変更を反映させたいときは、必ずセッションを立て直します。

設定のしかた

シェルの環境変数として渡すか、claudeを起動する前にエクスポートします。

export CLAUDE_CODE_TOOL_MEMORY_LIMIT=4G
claude

プロジェクトで固定値を共有したい場合は、settings.jsonのenvキーに書きます。

{
  "env": {
    "CLAUDE_CODE_TOOL_MEMORY_LIMIT": "4G"
  }
}

シェルとsettings.jsonの両方でこの変数を設定した場合は、settings.jsonのenvブロック側の値が優先されます。チーム共有の.claude/settings.jsonに値を書いておけば、開発者ごとのシェル設定に左右されずに同じ上限を強制できます。

CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDEで対象を調整する

キャップの対象は、Bash・PowerShell・Monitorのコマンドだけにとどまりません。Claude Codeが起動するローカルMCPサーバーや言語サーバー、フックコマンドなど、ほかの種類のプロセスも同じ上限にまとめてカウントできます。CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE(v2.1.246以降)は、そのうちどの種類をキャップの対象外にするかをカンマ区切りで指定する変数です。

一覧にない名前を指定した場合、Claude Codeはその名前を単に無視します。特別な値も2つあります。noneを指定するとすべての種類がキャップの対象になり(除外なし)、all-newを指定するとBash・PowerShell・Monitor以外はすべて対象外になります。

CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDEを設定しない場合、どの種類が既定で対象外になるかはAnthropicがサーバー側から配信する設定で決まり、その内容は時間とともに変わることがあります。除外の範囲を固定しておきたい構成では、この変数を明示的に設定しておくのが確実です。

たとえばローカルのMCPサーバーや言語サーバーがメモリを多く使う構成で、Bash・PowerShell・Monitor以外は上限の計算に含めたくない場合は、次のように設定します。

export CLAUDE_CODE_TOOL_MEMORY_LIMIT=4G
export CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE=mcp,lsp,hooks,plugin,helper,agent
claude

これはall-newを指定した場合と同じ効果になります。逆に、フックやプラグインが暴走したときも含めてまとめてキャップで守りたい場合は、CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE=noneを設定し、後述する権限確認フックの例外だけを踏まえたうえで運用します。

似た名前の環境変数との使い分け

「上限」を意味する変数はほかにもあり、それぞれ制限する対象が異なります。名前の響きが近いため混同しやすいので、対象の違いを先に表で確認します。

CLAUDE_CODE_TOOL_MEMORY_LIMITだけが唯一「メモリ」という物理リソースを制限する変数で、しかもLinux/WSL限定です。ほかの変数はいずれも実行回数やトークン数のような論理的な数量を制限しており、対応環境もOSを問いません。環境変数全体の一覧と探し方はClaude Code環境変数リファレンスにまとめています。Bash・PowerShell側でなくClaude Code本体プロセスがメモリを使い切る場合は、Claude Codeのメモリリークとその対処で扱う原因が当てはまります。

よくあるつまずき

• 値を変えたのに反映されない: 実行中のセッションでは反映されません。claudeを再起動します
• キャップが効いているはずなのに制限されていない: macOS/ネイティブWindowsでは対象外です。またコンテナ環境などでcgroupのセットアップ自体に失敗している可能性があり、claude --debugのログで確認します
• コマンドが理由不明で落ちる: メモリキャップによる強制終了は、実行結果にその旨が表示されません。ビルドやテストが突然落ちたときは疑ってみる価値があります
• フックだけ除外から漏れると思っている: 権限確認フックとその呼び出し先のMCPサーバーは、noneを指定してもキャップの対象外のままです。除外設定を厳しくしても、この安全策だけは外れません

まとめ

CLAUDE_CODE_TOOL_MEMORY_LIMITは、Linux/WSL環境でBash・PowerShell・Monitorコマンドのメモリ使用量にcgroupで上限をかける環境変数です。値はバイト数かK/M/G/T接尾辞で指定し、0やoffで無効化できます。上限はセッション全体で共有され、変更はセッションの再起動まで反映されません。上限に達したコマンドはヒントなしで強制終了される点と、cgroupのセットアップに失敗すると静かにキャップなしで動く点は、原因調査の前に知っておく価値があります。対象プロセスの範囲を広げたり絞ったりしたいときはCLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDEを使いますが、権限確認フックとその呼び出し先のMCPサーバーだけは常にキャップの対象外です。