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.
- 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.
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
-
The task
A codebase search, in your session
The agent reads files and runs greps where you are working.
-
The context
Everything it reads stays
Forty minutes in, the session holds three test runs, two grep sweeps and a migration log.
-
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.
-
What you can rely on
Whatever still fits
Noisy work and the answer share one window.
In a subagent Own context
-
The task
Delegated to a subagent
The main agent writes a task message, the only channel for anything specific to the job.
-
The context
A fresh window of its own
It does not see your conversation history: only its prompt, the task message and your
CLAUDE.mdfiles. -
The work
Reads, greps, runs the tests
Its own tool limits apply, and the noisy side work stays out of the main conversation.
-
What you can rely on
One summary comes back
Treat it as a claim to check, not as evidence.
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.
Keep reading.
The guides that go deeper, and the terms and comparisons next to this one.
In the docs
Does this page answer your questions?
One tap, no sign-in.
What are you here for?
What is holding you back?
How does it read?
Thanks. If you left an email, Michał will reply.
Answering your questions?
One tap each. Close whenever you like.
no sign-in
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.
Michał replies, not a bot. The address is used for this reply only.