# CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS

> It sets how many subagents can run at the same time.

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

## Think of it like

It is like a small kitchen. Only so many cooks fit at once.

## Definition

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS sets how many subagents can run at once in one session. The default is 20. Past that, the Agent tool will not start another. It takes a whole number above 0, so you can move the cap but not remove it. It needs version 2.1.217 or later.

## Example

Jack's laptop slows down when Claude starts many helpers. He sets the cap to 5, and the work runs steady.

## Example code

```bash
export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=5
claude
```

Run at most five helpers at once.

## Why it matters

Each helper uses memory, tokens and API calls. A cap keeps a burst from swamping you.

## Common mistake

Trying to set 0 to turn the cap off. Anything that is not a whole number above 0 is ignored.

## Three principles

- **Default 20.** At once.
- **Whole number.** Cannot remove it.
- **2.1.217 or later.** Older ignore it.

## Related terms

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

![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-concurrent-subagents-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.
