Skip to content
Cursor Handbook

Subagents

A subagent is a scoped child run with its own context, used to keep a long task from poisoning one conversation.

  • Automation
  • Pro, Pro+, Ultra, Teams and Enterprise.

Checked against cursor.com on 25 September 2026

What it does

One agent working through a large task accumulates everything it read into a single context window. By the time it reaches the last file, the early reasoning is competing for attention with a hundred irrelevant search results. Subagents solve this by handing a defined piece of work to a child agent with a fresh context, which returns a result rather than a transcript.

The pattern suits work that decomposes cleanly: explore three candidate implementations at once, run a search across an unfamiliar area of the codebase and report back, or apply the same mechanical change to several packages. Design Mode leans on the same machinery, which is why you can fire off several interface edits before the first has finished.

Delegation is not free. Each subagent is a separate run drawing on the same usage allowance, so parallelising a task that did not need it spends more than doing it once.

Checked against Subagents documentation on 25 September 2026.

Frequently asked questions

How are subagents different from opening several chats?
A subagent is launched and supervised by a parent agent, which passes it a scoped brief and consumes its result. Separate chats have no shared parent, so you become the integration step.
Do subagents use more of my quota?
Yes. Every subagent is a separate run billed against the same Agent allowance, so three parallel subagents cost roughly three runs rather than one.
Can I run several agents on the same repository safely?
Use worktrees. Each git worktree gives an agent its own checkout on its own branch, which is what keeps parallel runs from overwriting each other in the same working tree.

Keep reading