結論：上限を置く前に、誰のメモリかを分けて測る
Claude Code 2.1.233では、Linux上のBash tool commandへopt-inのmemory cgroupを適用するCLAUDE_CODE_TOOL_MEMORY_LIMITが追加されました。buildやtestのchild processがhost全体を圧迫する事故を、制御された失敗へ変えるための機能です。Claude Code本体、会話context、plugin、MCP serverの使用量まで同じ変数で制限できるとは扱いません。
読者の具体的な困りごとは、Claudeが大きなbuildを始めた後に端末全体が応答しなくなり、原因がClaude本体なのかcompilerやtest workerなのか分からないことです。この記事を読むと、cgroup上限、Claude本体の診断、sandbox、container・CI limit、HOLDを6軸で選べます。
次の行動：代表build一つについて、通常時peak、異常時peak、hostの総memory、同時実行数、失敗後に消すprocessとartifactを一行へ記録してください。
正式な対象範囲と提供条件を確認する
公式changelogの表現は「Bash tool commands on Linux」へのopt-in memory cgroupです。対象はClaudeがBash toolから起動するcommandとその作業負荷であり、Claude Code process全体の一般的なmemory capとは区別します。追加料金の記載はありませんが、失敗後の再試行が増えればmodel利用量とCI時間は増えるため、費用が無関係になるわけではありません。
まずclaude --versionで2.1.233以降を確認し、release channelとinstall方法を台帳へ残します。環境変数の値形式や子processへの適用結果は、導入時点の公式environment variable referenceと実機の診断出力で再確認してください。changelogの一行だけから、単位、既定値、hard/soft limit、swap動作を推測して社内標準へ固定しません。
Linuxでも、hostがcgroupを利用できること、containerやrunnerの上位limitと矛盾しないことが必要です。上位containerが先にOOM killする構成ではClaude Code側のlimitだけを見ても原因を説明できません。native Windows向け機能とも解釈しません。Windows利用者はWSL2、container、VM、runner側のresource controlを別途選びます。
Claude Code公式troubleshootingは、高memory時に/compact、session再起動、大きなbuild directoryの除外、--safe-modeによるcustomization切り分けを案内します。さらに/heapdumpはJS heapとnative memoryの診断に使えますが、snapshotには会話全文やcredential文字列が含まれ得ます。公開issueへそのまま添付しないことが明記されています。
原因別に6つの制御を使い分ける
- Bash child process：compiler、test worker、package buildが増えるならLinux memory cgroupの候補です。
- Claude本体：長い会話、巨大paste、JS heap、native memoryならcompact、再起動、heap診断を使います。
- customization：plugin、MCP、Hook、LSPが疑わしい場合はsafe modeで差を測り、原因を一つずつ戻します。
- filesystem・network：sandboxはBashの到達範囲を制限します。memory上限とは別の境界なので両方を設計します。
- container・CI：複数sessionやjobを同居させる場合はpod、container、runnerのmemory request・limitと並列数を正本にします。
- host：swap、OOM killer、他process、監視不能が残るなら専用VMまたは使い捨てrunnerへ移します。
cgroup上限は「どのfileへ触れるか」や「どのhostへ通信するか」を決めません。Claude CodeのsandboxはmacOS、Linux、WSL2でBashのfilesystemとnetworkを隔離し、native Windowsは対象外です。Linuxではbubblewrapとsocatが必要で、dependency不足時にも無隔離で続けたくない組織はsandbox.failIfUnavailableを検討します。memoryとaccessの二つを別gateにしてください。
上限設定をcanary導入する8手順
- 一つのrepositoryと代表buildを選び、同時実行するClaude session、test worker、compiler jobを固定します。
- Claude Code本体とBash child processを別PID・cgroup・container metricで観測し、通常peakを複数回測ります。
- host総memoryからOS、監視、他service、Claude本体、並列余力を引き、Bash jobへ割り当てられる上限を決めます。
- 2.1.233以降とLinux実行を確認し、環境変数はprojectの秘密ではなく管理された起動設定から渡します。
- canary端末またはrunner一台だけで適用し、通常build、意図的な高負荷、複数workerを順番に試します。
- 上限到達時のexit、stderr、残存child process、一時file、lock、partial artifactを記録します。
- Claudeが同じcommandを無限再試行しないよう、失敗回数、時間、token、再実行許可をgoalや運用ruleで固定します。
- 一週間のpeakと失敗率をreviewし、上限調整、job分割、並列数削減、専用runner移行のどれかを決めます。
正常buildのpeakへ近すぎるlimitは、cache missやdependency更新のたびに失敗します。反対にhost限界と同じ値では他processの余力がありません。通常peak、p95、異常例、host予約分を分け、再現可能なjobだけ自動化します。buildが分割できるなら、単一の大きなlimitよりstageごとの小さな上限の方が原因を説明しやすくなります。
監視・復旧チェックリストとHOLD条件
- 2.1.233以降を確認した
- Linux実行を確認した
- Claude本体とchild processを分けた
- 通常peakを複数回測った
- host予約memoryを残した
- 上位container limitを確認した
- 並列session数を固定した
- 上限到達時のexitを記録した
- 残存processを確認した
- partial artifactの削除手順がある
- 再試行回数を制限した
- heap snapshotを公開しない
- rollback方法を確認した
HOLDするのは、値の単位や適用対象を公式資料・実機で確認できない、host metricを取得できない、production serviceと同居し余力を予約できない、OOM後のdata整合性を確認できない、credentialを含むheap snapshotの保管先がない、上限到達を無条件retryする場合です。hostが落ちなかったことだけを成功とせず、正常jobの完了率も見ます。
よくある質問と次の行動
/compactとmemory cgroupは同じ対策ですか？
違います。compactは会話contextを整理し、memory cgroupはLinuxのBash tool command負荷を制限します。症状の主体を測って選びます。
sandboxを有効にすればmemoryも制限されますか？
sandboxの主目的はfilesystemとnetworkの隔離です。memory上限の代替として扱わず、両方を独立して検証します。
上限到達後は自動retryしてよいですか？
同じ条件の再試行は再び失敗し、tokenと時間を消費します。job分割、worker削減、cache確認、limit見直しのいずれかを人が選びます。
memory cgroupの追加versionはClaude Code公式changelog、Claude本体の高memory切り分けとheapdump注意は公式Troubleshooting、Bashのfilesystem・network隔離条件は公式Sandboxing guideで公開直前にも確認してください。
更新経路はrelease channelの選び方、WindowsとWSL2の違いはWindows環境比較、全体の停止設計は企業導入チェックリストへつなげます。Miraigentの無料診断では、代表job、metric、上限、失敗、復旧、reviewを一枚の運用表へ整理します。