What is a sub-agent?

A subagent is a helper agent that the main agent starts for one subtask, with its own context window, so the parent’s context stays small. It does not see your conversation history: Claude Code gives it its own prompt, the task message, your CLAUDE.md files and a git status snapshot, and it returns a summary. Claude Code ships Explore, Plan and general-purpose subagents; Codex has /subagents; Cursor has Subagents.

Last updated
By
Published
In Polish
Subagent
First set up at
Level 3, free guide
Also searched as
subagent, sub agents

$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.

On this page Why it mattersHow each tool does itQuestions

Why it matters.

A subagent’s real product is a summary, not a transcript: a test run, a log triage or a codebase search happens in its own context window, and only the answer comes back. That answer is a claim, not evidence, so the parent should spot-check it. A role that exists only as a sentence in a prompt can still edit files; tool limits belong in configuration.

One side task, two places

A codebase search, run in the main conversation and in a subagent, as the Claude Code guide draws it.

  • Shared context window
  • Runs in its own context
  • What you can rely on

In the main conversation One context

  1. The task

    A codebase search, in your session

    The agent reads files and runs greps where you are working.

  2. The context

    Everything it reads stays

    Forty minutes in, the session holds three test runs, two grep sweeps and a migration log.

  3. The constraint

    Buried under the output

    The rule you set at the start, “do not touch the public API”, is buried, and a review would compete for the same context.

  4. What you can rely on

    Whatever still fits

    Noisy work and the answer share one window.

In a subagent Own context

  1. The task

    Delegated to a subagent

    The main agent writes a task message, the only channel for anything specific to the job.

  2. The context

    A fresh window of its own

    It does not see your conversation history: only its prompt, the task message and your CLAUDE.md files.

  3. The work

    Reads, greps, runs the tests

    Its own tool limits apply, and the noisy side work stays out of the main conversation.

  4. What you can rely on

    One summary comes back

    Treat it as a claim to check, not as evidence.

Delegate when the side task is separable and its output is a summary the parent can check. Keep the work in the main thread when each step depends on the previous result, or when two writers would touch the same files. Source: Claude Code subagents guide, Claude Code 2.1.283, 2026-09-26.

How each tool does it.

Cursor, Claude Code and Codex each name this their own way. Each note carries the date it was checked.

Cursor

Subagents are “specialized AI assistants that Cursor’s agent can delegate tasks to”; since 2026-08-19 a cloud subagent can run on its own virtual machine with an isolated copy of the project.

Local subagents share your checkout, so run any writing role in a worktree or a cloud subagent.

Scoped subagents guide (Cursor docs), 2026-08-28

Claude Code

Built-in Explore, Plan and general-purpose subagents; custom ones are Markdown files in .claude/agents/. Each runs in its own context window and returns only a summary.

A subagent does not see your conversation history: it gets its own prompt, the task message and your CLAUDE.md files. Spawning fails once 20 are running in a session, the default limit.

Claude Code subagents guide, Claude Code 2.1.283, 2026-09-26

Codex

Subagents run inside one session: ask for them in the prompt and switch with /subagents; [agents] in config.toml caps concurrency.

They suit read-heavy fan-out, such as exploring a codebase or reviewing a diff from several angles. Worktree sessions, scripted codex exec and cloud tasks are separate ways to run agents in parallel.

Codex multi-agent guide, Codex 0.157.1, 2026-09-26

Questions about the sub-agent.

Does a subagent share the parent’s context?

No, and that is the point. A Claude Code subagent starts with its own system prompt, the task message the parent writes, your CLAUDE.md files and a git status snapshot. It does not see your conversation history or the files the parent already read, and it returns a summary. A fork started with /subtask is different: it inherits the conversation.

When is a subagent worth starting?

When the side task is separable and its output is a summary the parent can check: repository mapping, documentation research, log triage, a fresh-context review. Keep the work in the main thread when each step depends on the previous result, or when two writers would touch the same files.

How does Codex do the same thing?

With its own subagents: /subagents manages them inside one session, with built-in default, explorer and worker roles and custom roles in .codex/agents/. Worktree sessions and cloud tasks are separate ways to run agents in parallel, not a stand-in for subagents.

Can a subagent be trusted to stay read-only?

Only if configuration enforces it. In Claude Code, tools is an allowlist and the hard boundary, but Bash can still write, for example with sed -i, so add deny rules. In Codex a role file cannot take editing away: the spawned agent inherits the session’s sandbox and approvals. Test the boundary by asking the role to edit README.md, then run git status.

Does this page answer your questions?

One tap, no sign-in.

not at all fully

Read the guides in the same words.

Open every guide with the Toolkit. Each term is defined once here, and the guides use it the same way.

$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.