Nested subagents in Claude Code and Codex: depth, concurrency and mixing models

One feature of Claude Code and Codex gets little attention: the main agent can start its own subagents, and those subagents can start subagents of their own. Inside a single session you can run a small team of agents that splits the work and runs tasks in parallel. The agents don't all have to use the same model.

How it looks in Claude Code

A typical setup has three layers:

• Opus is the main agent. It owns the architecture, the plan and the orchestration.
• Sonnet subagents take the features. They split their work further.
• Haiku subagents get the simple, well-defined tasks: searches, checks, small edits.

The structure isn't limited to one parent with a few children. Layers can nest.

By default, Claude Code allows a depth of 3 and 20 subagents running at once. Neither number is a hard ceiling. Two variables in the env block of ~/.claude/settings.json raise them:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "10",
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "50"
  }
}

The first sets how many layers deep agents can go. The second sets how many can run at the same time.

Older versions also capped the total number of subagents per session at 200. Version 2.1.224 removed that cap. The depth and concurrency limits still apply, and both can be configured.

You can pick models per agent as well:

• CLAUDE_CODE_SUBAGENT_MODEL sets the default subagent model.
• Agent definitions under .claude/agents/ take model: sonnet, model: haiku and so on.

Codex

Codex has a similar system, and it comes in two versions.

Multi-agent V1. The default depth is 1 and the concurrency limit is 6, so with default settings subagents don't start subagents of their own. To change both limits, edit ~/.codex/config.toml:

[agents]
max_depth = 10
max_concurrent_threads_per_session = 50

Multi-agent V2. The default concurrency limit is 4 in total, including the main agent. You raise it with max_concurrent_threads_per_session under [features.multi_agent_v2]. V2 ignores V1's max_depth, so the two systems don't handle depth the same way.

Caveats

• Allowing 50 agents doesn't mean 50 agents will run smoothly. API rate limits, local resources and plan usage limits still apply. One lesson from my own setup: subagents draw on the same subscription quota as anything else on the account that uses it. A busy afternoon of parallel agents emptied my quota and stalled an unrelated production job that relied on the same CLI.
• More agents is not better by default. A task that's split for the sake of splitting costs more and is harder to follow than the same task done by one agent.
• A bigger team doesn't guarantee better code. The quality of the orchestration and of the task split matters far more than the head count.

Where it pays off

On a large project, it makes sense to separate the agents that plan the architecture, build features, write tests, review code and investigate bugs. I like using a strong model for orchestration and handing small, independent tasks to lighter models. The main agent's context stays clean, independent work runs in parallel, and the cheap tasks run on cheap models.

Instead of one model writing all the code, you're running a small software team of models that organise themselves.

İsmail Oktay Dak · LinkedIn · X