A Claude Code subagent is a Markdown file in .claude/agents/ with a name, a description and a system prompt. Claude hands it a side task, it works in its own context window and returns only a summary; agent teams, still experimental, are full sessions that message each other.
Free for 3 seats · No credit card · One command signs in every agent on your machine
Sample data
Stack in the Zest app: how well your setup is wired, and what raises the score
USED BY ENGINEERING TEAMS AT
What Claude Code subagents are
A subagent takes a side task into its own context window, with its own system prompt, tools and permissions, and hands back only its result, so the files and logs it read stay out of your conversation. Its requests count toward the same usage limits as yours. Claude Code ships these:
Built-in subagents in Anthropic's subagents docs.
Subagent
Tools
Used for
Explore
Read-only
Searching a codebase; skips CLAUDE.md to stay small
Plan
Read-only
Research while you are in plan mode
general-purpose
All
Multi-step work that explores and edits
fork
Same as the main session
A side task that needs the whole conversation; start one with /subtask
How to create a subagent in .claude/agents
A custom subagent is a Markdown file: YAML frontmatter, then its system prompt. The body replaces Claude Code's own system prompt, so it has to say everything the subagent needs. Ask Claude to write the file, or save it yourself: Claude Code notices new and edited files within seconds, unless the agents folder didn't exist when the session started. /agents no longer opens an editor; it points you to these folders.
.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for bugs, security and missing tests. Use proactively after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. Run git diff to see the recent changes
and review only the modified files. Report critical issues first, then
warnings, then suggestions, each with the file, the line and a fix.
Where subagent files load from. On a name clash, the higher row wins.
user, project or local: a folder of notes it keeps across sessions
maxTurns, effort
A turn limit and an effort level
isolation: worktree
Runs it in its own git worktree, removed if it changes nothing
How Claude picks a subagent
Claude delegates on its own, or when you name the subagent:
Automatically, by matching your task against each description. Keep descriptions short: past 15,000 tokens combined, Claude Code warns at startup.
By @-mention: @agent-code-reviewer always runs that subagent for one task.
For a whole session: claude --agent code-reviewer, or "agent": "code-reviewer" in .claude/settings.json.
In an interactive session subagents run in the background, and their permission prompts appear in your main session. /tasks lists them with the model each one runs on.
Claude Code agent teams
Agent teams are experimental and off by default. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your shell or under env in settings.json, then ask Claude for teammates in an interactive session. One session leads; each teammate is a separate Claude Code instance with its own context window, claiming work from a shared task list and messaging the others directly. Teammates can't start teams of their own.
While teams are on, a subagent that Claude gives a name launches as a teammate, so a team can form without you asking. Set the variable back to 0 to get plain subagents.
Each subagent sends its own requests and builds its own prompt cache, which lasts five minutes even on a subscription where the main conversation's lasts an hour; a fork reuses the parent's cache instead. Anthropic puts agent teams at about 7 times a standard session's tokens when teammates run in plan mode, and suggests Sonnet for teammates and Haiku for simple subagents. On a Pro, Max, Team or Enterprise plan, /usage shows the share that went to subagents.
Our numbers, from one engineer's 318 Claude Code sessions (September 4 to October 3, 2026) at list price: 168 (53%) launched subagents, 1,844 in all (general-purpose 1,425, fork 298, Explore 109). They used 41% of the tokens and 34% of the cost, and on the two heaviest days they sent 84% and 91% of all API calls. Every subagent cache write used the five-minute cache. The rest of that month is in Claude Code token usage.
Why a subagent doesn't load or misbehaves
Claude Code skips a broken agent file without a message in the session. claude --debug logs why, and claude plugin validate .claude/agents finds YAML that doesn't parse. The usual causes:
Subagent problems and their fixes, from Anthropic's subagents and configuration-debugging docs.
Symptom
Cause and fix
Never appears
No name, or the first --- isn't line 1, so the file reads as documentation
Skipped, with a debug-log error
A name without a description, or a name containing :
The wrong definition runs
Two files in one agents folder share a name and file order picks one; /doctor reports duplicates
Ignores CLAUDE.md
Explore and Plan skip it. Restate the rule in the task you delegate
disallowedTools: Bash(git push *) removes all of Bash
A pattern still removes the whole tool; put Bash(git push *) in permissions.deny instead
Codex subagents
Codex has subagents too, on by default in the ChatGPT desktop app, the CLI and the IDE extension, and it delegates when you ask or when AGENTS.md or a skill says to. It ships default, worker and explorer agents; custom ones are TOML files in .codex/agents/ or ~/.codex/agents/ with a name, a description and developer_instructions. OpenAI notes they use more tokens than a single agent. Config keys, model choice and what they inherit are on Codex subagents.
On the same engineer's laptop, 188 of 368 Codex sessions from June 21 to September 22, 2026 were subagent threads, started by 222 spawn_agent calls.
What Zest shows about subagents
Zest's Claude Code plugin records which subagents each session launched and how many times, built-in, custom or from a plugin, by name only, never the prompt. Their tokens count toward the session's total. The AI Stack view lists each engineer's agents next to their skills and MCP tools. Codex subagent threads aren't tracked yet. More in Claude Code usage.
Stack in the Zest app: how well your setup is wired, and what raises the scoreSample data
TRY IT ON YOUR TEAM
See what your team ships with AI.
Starter is free (3 seats, no credit card). Pro is $49 a month with 5 seats and Max is $149 a month with 10 seats — priced per workspace, not per engineer, with extra seats at $19 a month. See pricing
What is the difference between subagents and agent teams?+
A subagent works inside one session and hands its result back to the session that launched it. An agent team is several full Claude Code sessions with a shared task list, messaging each other; it is experimental, off by default and uses more tokens.
Can a subagent run on a cheaper model?+
Yes. Set model: haiku or model: sonnet in its frontmatter. CLAUDE_CODE_SUBAGENT_MODEL sets a default for subagents whose file names no model; without it they run on the main conversation's model.
How many subagents can run at once?+
Twenty at a time by default, nested up to three levels below the main conversation. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS and CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH change the limits.
Can a subagent use skills?+
Yes. It can call project, user and plugin skills like the main session, and its skills field loads chosen skills' full text at startup. A skill set to disable-model-invocation: true can't be preloaded.