# CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH

> It sets how deep helpers may start helpers.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH environment variable

## Think of it like

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

## 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

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.

## Example code

```bash
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1
claude
```

Let only the main chat start helpers.

## Why it matters

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

## Common mistake

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

## Three principles

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

## Related terms

- [Subagent](https://learn.benibix.com/term/ai/subagent)
- [CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS](https://learn.benibix.com/term/ai/claude-code-max-concurrent-subagents-variable)
- [Agent Tool](https://learn.benibix.com/term/ai/agent-tool)

![Up to 20 subagents run at once, and they nest at most 3 layers deep by default.](https://learn.benibix.com/diagrams/env-subagent-caps.svg)

---

Source: https://learn.benibix.com/term/ai/claude-code-max-subagent-spawn-depth-variable
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
