Skip to content
BENIBIX Learn

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH

AI⌨️ Claude CodeConfiguration

Also known as CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH environment variable

It sets how deep helpers may start helpers.

Think of it like

It is like a helper who may ask a helper. But it stops a few steps down.

Example

Emma's helpers kept starting helpers, and costs grew fast. She sets the depth to 1, and only the main chat can hand out work.

Why it matters

Each layer can fan out again, so depth grows the work faster than you expect.

Definition

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH sets how many layers of subagents may sit below the main chat. The default is 3. So a subagent can start its own, and the third layer cannot start more. Set it to 1 to stop subagents from starting their own. It takes a whole number above 0 and needs version 2.1.217 or later.

Example code

bash
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1
claude
Let only the main chat start helpers.
The depth counts the layers going down.

Common mistake

Setting 0 to turn nesting off. The value must be at least 1, and 1 is what turns it off.

Key takeaways

  1. 1
    Default 3. Layers below main.
  2. 2
    1 turns nesting off. Main chat only.
  3. 3
    Whole number. Cannot remove it.