Definition
A subagent is a helper agent that a main AI coding agent starts to handle one piece of work in its own separate context, handing back only the result.
Also called: sub-agent, Task tool agent, spawned agent, agent thread.
Subagents keep noisy side work, such as search results, logs or long file reads, out of the main conversation, and let independent jobs run in parallel. The trade-off is usage: every subagent's work counts towards your plan limits.
| Claude Code | Codex | |
|---|---|---|
| How it starts | Claude calls the Agent tool (formerly the Task tool), on its own or when you ask | when you ask, e.g. “spawn one agent per point” |
| Where it works | its own context window, system prompt, tools and permissions | its own agent thread, which you can open |
| Custom definitions | Markdown files in .claude/agents/ or ~/.claude/agents/ (see Claude Code agent) | TOML files in ~/.codex/agents/ |
In Claude Code a subagent can also run in the background or in its own git worktree (isolation: worktree) so parallel edits don't collide. Codex can cap how many spawned threads run at once with agents.max_concurrent_threads_per_session.
In Pairbar
Claude Code subagents and Codex's spawned threads appear under their chat, tied to it by a thin line. The 👥 chip on a row counts those working now; click it, or choose Show subagents. Summary chips count what's running, needs you, failed, stopped and done, with the tokens the subagents used. Each row shows its job, type, how long it ran and what it's doing or found; nested subagents are indented, and done ones fold behind Show N done. A subagent waiting for an answer makes its parent chat show Needs you, and Codex subagents open in their own thread when clicked. See Subagents.
Rest the pointer on one for a hover card with its model, tokens and share of the chat, and tool calls. Click it to open the transcript reader beside the sidebar: the brief it was given, every step (open one for its output or diff), the result, ⌘F search, and live follow while it runs, with Show in chat, Copy result and Copy all. The reader only reads the transcript on your Mac. See read Claude Code subagent transcripts.
Frequently asked questions
- Is a subagent the same as the Task tool?
- In Claude Code, subagents are started with the Agent tool, which was previously called the Task tool. The subagent is the helper; the tool is how Claude launches it.
- Do subagents share the main chat's context?
- No. Each works in its own context and returns a summary, which is why they help keep the main conversation focused.
- Can Codex use subagents?
- Yes. Codex spawns subagents when you ask it to delegate or parallelise, and each works in its own agent thread.
Related
- GlossaryClaude Code agentA Markdown file with YAML frontmatter that defines a reusable Claude Code specialist, such as a reviewer, Claude can delegate to.
- Use caseSee the Claude Code subagents and Codex spawned threads running inside your chatsA 👥 chip per chat counts working subagents; the list shows each one's job, agent, progress and time, and questions surface on the parent.
- Use caseRun several Claude Code and Codex agents in parallel without losing trackA Needs you section, live activity lines, subagent chips, worktrees and ⌃1–9 for running many agents at once.
- DocsChatsThe chat list: status, grouping, sorting, filters, pins, labels, hover details, subagents, bulk actions, the chat menu
- Use caseRead what a Claude Code subagent actually did: its brief, every step and its resultA transcript reader for subagents: the brief, one line per step (opened for its output or diff), the result with Copy, ⌘F search and live follow.
- GlossaryAgent profileA named preset (app, model, effort, access, when to use it) that an AI agent names when it asks for a helper, review or second opinion.