CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSとは — 並列数の上限を変える環境変数
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSは同時実行できるサブエージェント数の上限を変える環境変数です。既定値20の挙動、深さ上限との違い、上限にカウントされる対象をまとめます。
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS は、1つのセッション内で同時に実行できるサブエージェントの数に上限をかける環境変数です。既定では20件が動いている状態でAgentツールが21件目を起動しようとすると、「Concurrent subagent limit reached」というエラーで起動が拒否されます。値を大きくすれば並列度を上げられ、逆に絞ればリソース消費を抑えられます。v2.1.217以降で使えます。
既定の挙動
上限に達した状態でAgentツールが新しいサブエージェントを起動しようとすると、起動そのものが失敗します。エラーメッセージにはClaudeへ「リトライしないように」という指示が添えられており、Claudeが同じ起動を無限に試み続けることはありません。実行中のサブエージェントのどれかが完了して実行数が上限を下回れば、次の起動は成功します。
正の整数であればCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSに好きな値を設定できます。セッション全体でClaudeが生涯に起動できるサブエージェントの総数には上限がなく、この変数が制御するのはあくまで「同時に動いている数」です。
深さの上限とは別の変数で制御する
サブエージェントの並列実行を制限する仕組みはもう1つあり、名前が紛らわしいので区別が必要です。
| 制御対象 | 変数 | 既定値 |
|---|---|---|
| 同時に実行中のサブエージェント数 | 変数CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS | 既定値20 |
| サブエージェントが自分の子サブエージェントを何階層まで持てるか | 変数CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH | 既定値3 |
前者は「横方向」、後者は「縦方向」の制限だと考えると区別しやすくなります。CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSを大きくしても、サブエージェントが孫サブエージェントをさらに増やせるようにはなりません。逆にCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHを増やしても、同時に動ける数そのものは変わりません。深い階層構造を持つ並列処理を組みたい場合は、両方の変数を目的に応じて調整する必要があります。
設定のしかた
シェルの環境変数として渡します。
export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=40
claudeプロジェクトで固定値を共有したい場合はsettings.jsonのenvキーに書きます。
{
"env": {
"CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "40"
}
}上限はセッション単位
この上限は「1つのセッション内」で数えられるもので、マシン全体やユーザーアカウント全体で共有される予算ではありません。同じ端末で複数のターミナルを開き、それぞれ別のClaude Codeセッションを起動している場合、各セッションは独立して20件までのサブエージェントを持てます。並列作業のために複数セッションを開いている構成では、1つのセッションの上限を上げるより、作業をセッション単位で分割する方がAPIへの負荷を分散させやすいこともあります。
上限にカウントされるもの・されないもの
上限が直接ブロックするのは、ClaudeがAgentツールで新規に起動しようとするサブエージェントだけです。ただし、それ以外の実行もスロットを消費するため、実行数の管理はやや複雑です。
/subtaskで現在の会話をフォークして走らせる実行は、動いている間スロットを1つ占有しますが、上限によってブロックされることはありません。上限を超えていてもフォークは常に成功します。
ワークフロー機能で動くエージェントやAgent Teamsのteammateは、この上限とは別の仕組みで並列数が制御されます。つまりCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSを調整しても、ダイナミックワークフローの並列度やAgent Teamsのチームサイズには影響しません。
ダイナミックワークフローの並列数は最大16で別枠
ダイナミックワークフローのランタイムは、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSの値に関係なく同時実行エージェント数を最大16(CPUに余裕がない環境ではさらに少ない数)に固定し、1回の実行で起動できるエージェント総数も1,000に抑えます。この上限は環境変数ではなくworkflowSizeGuideline設定(small/medium/large/unrestricted)や実行時のプロンプトで調整するもので、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSを上げてもワークフロー実行の並列数は16のまま変わりません。Agentツールで直接起動する通常のサブエージェントの並列数を上げたい場合と、ダイナミックワークフローの規模を変えたい場合とでは、触るべき設定がそもそも違います。
ワークフローの規模はworkflowSizeGuidelineという別の設定でClaudeへの目安として渡します。あくまで目安であって強制的な上限ではなく、実際の同時実行数は上の16という上限で抑えられます。
| 値 | 目安のエージェント数 |
|---|---|
small | 目安のエージェント数5未満 |
medium(既定) | 目安のエージェント数15未満 |
large | 目安のエージェント数50未満 |
unrestricted | 目安のエージェント数目安なし。タスクに応じてClaudeが規模を決める |
ワークフローがエージェント25件、または見積もりトークン総量150万を超えると、タスクパネルに「Large workflow」という警告が表示されます。これも実行を止めない目安表示で、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSのような強制力のある上限とは性格が異なります。コストが気になる大規模なワークフローを試すときは、いきなり本番相当の範囲で走らせず、対象を1ディレクトリに絞るなど小さく試してから広げる方が安全です。
上限に達したときに実際に何が起きるか
例えば、既定値20のまま「リポジトリ内の30ファイルをそれぞれ別のサブエージェントでレビューして」という依頼をしたとします。Claudeが30件のAgentツール呼び出しを一度に発行しようとしても、21件目以降は次のようなエラーで起動が拒否されます。
Concurrent subagent limit reachedこのエラーはClaudeに向けたメッセージで、人間の画面にそのまま表示されるとは限りません。残り10件を後から順に起動し直すかどうかはそのときのClaudeの判断によりますが、起動失敗そのものがタスク全体を止めるわけではなく、上限はあくまで「同時に走らせられる数」を絞る仕組みという位置付けです。
急ぎの一括処理で待ち時間を縮めたいなら上限を引き上げる、逆にAPIへの負荷やコストの急増ペースを抑えたいなら上限を絞る、という判断の材料としてこの挙動を踏まえておくと具体的にイメージしやすくなります。
どのくらいの値にすると効果があるか
既定値の20は、通常の対話的な開発フローの中で意図せずリソースを使い切らないための、保守的な設定です。値を上げる動機になるのは、ファイル単位で独立したタスクを大量に並列処理したいワークフロー的な使い方です。1つのプロンプトから「N個のファイルをそれぞれ別のサブエージェントで検証して」と依頼するようなケースでは、Nが20を超えると既定値のままでは一部が起動失敗になります。
逆に値を下げる動機になるのは、CI環境でのAPIレート制限やコストの急増を避けたい場合です。並列に動くサブエージェントの数だけAPIリクエストも同時に発生するため、上限を絞ることは間接的にコストの急増ペースを抑える手段にもなります。ただし正確な支出上限をかけたいなら、この変数ではなく--max-budget-usdフラグの方が直接的です。値を1桁台まで絞ると、通常の対話的な開発フローでも複数のツール呼び出しが同時に必要な場面で待ちが発生しやすくなるため、極端に小さい値は避けたほうが扱いやすくなります。
まとめ
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSは、同時実行中のサブエージェント数という「横方向」の上限を変える環境変数です。子サブエージェントの階層という「縦方向」を制御するCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHとは別物である点、/subtaskのフォークや完了済みサブエージェントの再開は上限チェックの対象外でスロットだけ消費する点は、値を決める前に押さえておく価値があります。ワークフロー機能で動くエージェントやAgent Teamsは別の上限体系に従うため、この変数は純粋にAgentツールで起動するサブエージェントの並列数だけを動かします。サブエージェント全体の設計はClaude Codeのサブエージェント完全活用、メインを指揮役に回す構成はClaude Codeオーケストレーター設計、大規模な並列処理の仕組みはClaude Codeワークフローにまとめています。環境変数全体の一覧はClaude Code環境変数リファレンスを参照してください。