The short answer
- Subagents split one task. The main agent hands a focused job, such as searching the codebase or reviewing a diff, to a subagent with its own context window. The subagent returns a summary and the main agent carries on.
- Parallel agents split the work. You run several independent agent sessions, each on its own task, often each in its own git worktree, and review what each one produces.
Most real workflows use both: several parallel agents, each of which uses subagents along the way.
What is a subagent in AI coding?
In Anthropic's words, Claude Code subagents are "specialized AI assistants that handle specific types of tasks." Each one runs in its own context window with its own system prompt, tool access and permissions. When it finishes, only its result comes back to the main conversation, so the noisy intermediate work (dozens of file reads, long test logs) stays out of the main agent's context.
Codex has the same idea: it can "spawn specialized agents in parallel and then collect their results in one response."
How Claude Code subagents work
Built-in subagents. Claude Code ships with:
- Explore, a fast, read-only agent for searching and analysing a codebase.
- Plan, a research agent that gathers context in plan mode before presenting a plan.
- General-purpose, for complex, multi-step tasks that need both exploration and action.
Custom subagents. A subagent is a Markdown file with YAML frontmatter. Put it in .claude/agents/ to share it with everyone on the project, or in ~/.claude/agents/ to use it in all your projects. Only name and description are required:
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
The description tells Claude when to delegate to the subagent, tools restricts what it can use, and model picks the model it runs on.
Foreground and background. A foreground subagent blocks the main conversation until it finishes. A background subagent runs while you keep working, and its result arrives as a notification in a later turn.
Nesting and isolation. By default a subagent can start subagents of its own, up to three layers below the main conversation. A subagent starts in the main conversation's working directory; set isolation: worktree in its frontmatter to give it a temporary git worktree with its own copy of the repository instead.
How Codex subagents work
Codex defines custom agents as TOML files in ~/.codex/agents/ (personal) or .codex/agents/ (project). Each file sets a name, a description and developer_instructions. Codex also ships built-in agents named default, worker and explorer. Subagents work in their own agent threads, inherit the parent's sandbox and approval settings, and return summaries to the main thread. OpenAI's docs suggest them for parallel exploration, tests and log analysis.
What are parallel agents?
Parallel agents are independent sessions of a coding agent, each working on a different task at the same time. Each one has its own conversation, its own context window and its own goal, and you talk to each one directly.
The usual setup:
- One task per agent, chosen so the tasks touch different files.
- One checkout per agent, usually a git worktree on its own branch, so each agent's edits stay on its own branch.
- One review per result, merging each branch when it's ready.
Claude Code supports this with claude --worktree, background agents and agent teams. Codex supports it with several local sessions, codex --worktree and cloud tasks. Tools such as Claude Squad, Vibe Kanban and Chief help you run and track many sessions at once. The step-by-step version is in how to run multiple Claude Code agents in parallel.
Subagents vs parallel agents at a glance
| Subagents | Parallel agents | |
|---|---|---|
| What it splits | One task into focused sub-jobs | A project into independent tasks |
| Who starts it | The main agent, when it decides to delegate | You, or an orchestrator |
| Context | Own context window; returns a summary to the parent | Own session and full context for its whole task |
| Who you talk to | The main agent only | Each agent directly |
| Working copy | The parent's directory by default (isolation: worktree for a copy) | Usually its own git worktree or branch |
| Lifetime | Ends when its sub-job is done | Runs until its task is done |
| Configured in | .claude/agents/ or .codex/agents/ | Your terminal, worktrees or an orchestrator |
| Best for | Research, search, review and test runs inside one task | Shipping several features or fixes at once |
When to use subagents
Anthropic's docs suggest subagents when:
- The task produces verbose output you don't need in your main context, such as a codebase search or a long test run.
- You want specific tool restrictions or permissions, such as a read-only reviewer.
- The work is self-contained and can come back as a summary.
Stay in the main conversation when a task needs frequent back-and-forth, when planning, implementation and testing share a lot of context, or when you're making a quick, targeted change.
When to use parallel agents
Reach for parallel agents when:
- You have more independent work than one session can do, such as three bug fixes and a new endpoint.
- The work won't fit in one context window, or needs to keep running while you do something else.
- You want different agents or models on different tasks, such as Claude Code on a refactor and Codex on tests.
The cost of parallel agents is coordination: choosing tasks that won't collide, keeping track of which agent is waiting on you, and reviewing every result.
How Chief runs parallel agents for you
Chief is an AI agent manager. It takes on the coordination work around parallel agents so you can focus on the decisions.
- You set the goal, Chief plans the work. Chief breaks a goal into milestones, each with a definition of done and the milestones it depends on.
- Parallel by plan. Chief runs every milestone whose dependencies are done at the same time. It plans shared pieces such as types and migrations first, and chains work that would edit the same files, so parallel agents stay out of each other's way.
- Your subagents come along. Each milestone runs as its own agent session in your project folder, so the subagents you keep in
.claude/agents/or.codex/agents/are there for the agent to use. - Runs on your computer, with your subscriptions. The Chief relay starts Claude Code, Codex and other agents on your machine, signed in with your own accounts.
- Every result is reviewed. Chief checks each milestone against its definition of done and collects the decisions only you can make in one queue.
Let Chief run your parallel agents. Start free →
FAQ
What is the difference between a subagent and an agent?
An agent is a full session you work with directly. A subagent is a helper that an agent starts inside its own session for one focused job. It has its own context window and returns a summary to the agent that started it.
Do Claude Code subagents run in parallel?
They can. Claude Code can run several subagents at once, and background subagents run while you keep working. They're still part of one session, though, and their results all come back to the same main conversation.
Where do I put Claude Code subagent files?
In .claude/agents/ for subagents specific to one project (check them into version control so your team can use them), or in ~/.claude/agents/ for personal subagents available in all your projects.
Should I use subagents or parallel agents?
Use subagents to keep one task's context clean: research, search, review and test runs. Use parallel agents to get more independent tasks done at once. Most teams use both.
Does Chief replace Claude Code subagents?
No. Chief works one level up: it plans and runs separate agent sessions in parallel. Inside each session, Claude Code or Codex can still use its own subagents.