CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSとは — 並列数の上限を変える環境変数

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS は、1つのセッション内で同時に実行できるサブエージェントの数に上限をかける環境変数です。既定では20件が動いている状態でAgentツールが21件目を起動しようとすると、「Concurrent subagent limit reached」というエラーで起動が拒否されます。値を大きくすれば並列度を上げられ、逆に絞ればリソース消費を抑えられます。v2.1.217以降で使えます。

21件目を起動しようとすると何が起きるか

上限に達した状態でAgentツールが新しいサブエージェントを起動しようとすると、起動そのものが失敗します。エラーにはClaudeへ「リトライしないように」という指示が添えられています。実行中のサブエージェントのどれかが完了して実行数が上限を下回れば、次の起動は成功します。

例えば既定値20のまま「リポジトリ内の30ファイルをそれぞれ別のサブエージェントでレビューして」と頼むと、21件目以降は次のエラーで拒否されます。

Concurrent subagent limit reached

正の整数であれば好きな値を設定できます。この変数が制御するのは「同時に動いている数」だけで、1つのセッションで起動できる総数は数えません。

横方向の上限と縦方向の上限は別の変数

サブエージェントの数を縛る仕組みはもう1つあり、名前が紛らわしいので区別が必要です。

深い階層構造を持つ並列処理を組みたいときは、両方の変数を目的に応じて調整します。深さの既定値はバージョンで変わってきました。v2.1.172〜v2.1.216は最大5階層で変更不可、v2.1.217〜v2.1.218は既定が1で子を持てず、v2.1.219から3になっています。同時実行数の上限が入ったv2.1.217は、深さを設定で変えられるようになった版でもあります。古い環境で「サブエージェントが子を作れない」と感じたら、バージョンを見る価値があります。深さ3の既定値は、メインの会話から数えて3層目のサブエージェントまでが動けるという意味です。3層目のサブエージェントはそれ以上サブエージェントを起動できません。1にすると入れ子そのものが無効になります。この変数も正の整数だけを受け付け、それ以外の値は無視されるので、深さは調整できても外せません。入れ子の段数を変える手順はCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHにまとめています。名前にCONCURRENCYを含むCLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYという変数もありますが、こちらは読み取り専用ツールとサブエージェントを合わせて同時に実行できる数(既定10)です。サブエージェントだけを数える今回の変数とは、対象範囲が違います。違いはMAX_TOOL_USE_CONCURRENCYとMAX_CONCURRENT_SUBAGENTSの違いで扱っています。

設定のしかた

シェルの環境変数として渡します。

export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=40
claude

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

{
  "env": {
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "40"
  }
}

この上限は「1つのセッション内」で数えられます。

並列数を上げたときに遭遇すること

上限を上げると、その分だけ同時に動くサブエージェントが増えます。増えた先で実際に起きる事象が3つあります。

1つ目は、権限プロンプトの増加です。バックグラウンドで動くサブエージェントが権限の要るツール呼び出しに達すると、Claude Codeはメインのセッションにプロンプトを表示し、確認を求めているサブエージェントの名前を添えます。承認すればサブエージェントは続行し、Escを押せばそのツール呼び出し1回だけが拒否されて、サブエージェントは止まりません。フォアグラウンドのサブエージェントは、メインの会話をブロックしたまま同じ形でプロンプトを渡してきます。

2つ目は、別の並列数の上限です。CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYは、読み取り専用ツールとサブエージェントを合わせて同時に実行できる数を決める変数で、既定値は10です。公式のドキュメントは、この変数と今回の変数の関係を書いていません。同時実行の上限を40にしても期待したほど並列に動かないときは、こちらの値も確認対象に入ります。

3つ目は、サブエージェントパネルの表示です。ターミナルでは入れ子のサブエージェントがツリーとして並び、子孫を持つ行には(+N)の件数が付きます。行を開くと、そのサブエージェントの兄弟と直接の子が、mainまでの経路つきで見えます。数が増えたときに、どの枝が上限を使っているかを追う入り口になります。なお、この上限はチームの同時起動数ではなく、Agentツールで起動されるサブエージェントを数えるので、Agent Teamsのteammateが増えても件数は動きません。

上限とは別にスロットを消費する実行

上限が直接ブロックするのは、ClaudeがAgentツールで新規に起動しようとするサブエージェントだけです。ほかの実行も同じスロットを使うため、数え方に抜け道があります。

ダイナミックワークフローの並列数は別の環境変数で決まる

ワークフロー実行の並列数は、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSの値と無関係です。上げても下げても、ワークフローの同時実行数は変わりません。

ワークフローの同時実行数を変えたいときは、専用のCLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSに1〜256の値を入れます。実行中のエージェントの履歴はClaude Codeのメモリに残るため、値を上げるとメモリ使用量が増えます。範囲外の値や数字以外の書き方は無視されて既定値のままになる点は、今回の変数と同じです。Agentツールで直接起動する通常のサブエージェントの並列数と、ワークフローの規模とでは、触る設定が別になります。

ワークフローの規模はClaudeへの目安として渡すworkflowSizeGuidelineという別の設定でも変わります。強制的な上限ではなく、プロンプトで別の規模を求めればそちらが優先されます。

この設定はv2.1.219以降で有効で、それより前のバージョンの既定はunrestrictedです。既定はmediumですが、Proプランでサインインしていてv2.1.271以降ならsmallになります。largeは警告が出る25件を超えうる規模なので、コストが気になる場合は対象を1ディレクトリに絞るなど、小さく試してから広げる余地があります。Large workflowの警告は実行を止めず、/workflowsで止めるかどうかを判断するための表示です。

値を変える判断と、実機で確認できること

値を上げる動機になるのは、ファイル単位で独立したタスクを大量に並列処理する使い方です。「N個のファイルをそれぞれ別のサブエージェントで検証して」と頼み、Nが20を超えると、既定値のままでは一部が起動失敗になります。

逆に値を下げるのは、APIのレート制限やコストの急増ペースを抑えたいときです。並列に動く数だけAPIリクエストも同時に発生します。ただし正確な支出上限をかけたいなら、この変数ではなく--max-budget-usdが本来の手段で、これには条件があります。v2.1.285でclaude --helpを実行すると、次のように出ます。

claude --version
claude --help | grep -A1 "max-budget-usd"

2.1.285 (Claude Code)
  --max-budget-usd <amount>             Maximum dollar amount to spend on API
                                        calls (only works with --print)

--print(非対話モード)でしか効かないため、対話セッションの支出を絞る用途には使えません。同じ--helpの出力にconcurrentを含む行は1つもなく、この環境変数は--helpからは見つかりません。存在と挙動を確かめる場所は、公式のenv-varsページとsub-agentsページです。

まとめ

「なぜ21件目が拒否されたのか」を調べるときは、まず数えている対象がAgentツールの新規起動かどうかを切り分けると原因に届きます。サブエージェント全体の設計はClaude Codeのサブエージェント完全活用、メインを指揮役に回す構成はClaude Codeオーケストレーター設計、大規模な並列処理の仕組みはClaude Codeワークフローにまとめています。環境変数全体の一覧はClaude Code環境変数リファレンスです。