Subagents

Subagents are helper agents that a parent agent creates to handle a focused piece of a larger task. Each one is a real, independent agent session in the same workspace, not a lightweight sub-process, so it can read files, run commands, and think through a problem on its own.

Use subagents when work benefits from parallel investigation, implementation, or review but should still stay connected to the same broader objective.

When to use subagents

Ask your agent to spawn a subagent for:

• Long-running work that benefits from delegation instead of blocking the main conversation.
• Independent codebase investigations, such as tracing how a subsystem works before deciding how to change it.
• A focused review pass on a plan or a diff (see Plan & code review).
• Comparing two possible implementations before committing to one.
• Splitting a larger task into scoped worker pieces that don't need to share context with each other.

Skip subagents when a single, direct conversation with your agent would just be simpler. Spinning up a helper adds coordination overhead you don't always need.

Common patterns

• A planning agent asks a subagent to inspect one risky subsystem before finalizing a plan.
• A reviewer-style subagent checks a branch or a plan while the main agent keeps working on something else.
• A parent agent spawns two subagents to try different approaches, then compares their results before picking one.

Workspace boundaries

Subagents work inside the same workspace as their parent: same repository checkout, same files, same git state. There's no separate environment to provision.

A few limits keep delegation predictable:

• A parent session can have up to 8 subagents at a time.
• A subagent can't spawn subagents of its own. Delegation is one level deep.
• A subagent doesn't inherit the parent's connected integrations or other MCP tools. It starts clean, with just its own core agent abilities.

How subagents show up

Creating, messaging, checking on, and closing subagents all happen through a built-in tool set your agent gets automatically once subagents are enabled for the workspace. You don't install or configure anything for this; it's part of the agent's core toolkit, the same way file editing and running commands are.

When your agent creates a subagent, it shows up right in the transcript as a receipt you can expand to see the child's name and the prompt it was given.

The child agent's tab groups next to its parent's tab in the top tab strip, under a small collapsible pill (for example, "3 agents") so you can tell delegated work apart from tabs you opened yourself.

You can also check on every subagent from the composer's Agents popover, which lists each one with its current status and a Wake button if you want to be notified the moment it finishes.

When a subagent that scheduled a wake finishes a turn, the parent's transcript gets a short receipt, such as "API Surface Check finished a turn", that you can click straight through to open that subagent's session and read what it found.