A Claude Code subagent is a helper with its own context window, prompt and tools, defined in a Markdown file in .claude/agents/, that hands its result back to the main session. Agent teams, still experimental, run several full sessions that share a task list and message each other.
A subagent takes a side task into its own context window, with its own system prompt, tools and permissions, and returns only its result, so the logs and files it read stay out of your main conversation. Claude Code ships several: Explore and Plan for read-only research, general-purpose for multi-step work, and fork, which starts from a copy of the current conversation.
How to create a subagent in .claude/agents
A custom subagent is a Markdown file: YAML frontmatter, then its system prompt.
Project: .claude/agents/<name>.md, committed so the whole team gets it. Personal: ~/.claude/agents/<name>.md, in every project on your machine.
Plugin: a plugin's agents/ folder, named plugin-name:agent-name.
name and description are required. tools or disallowedTools limit what it can call, and model takes sonnet, opus, haiku, fable, inherit or a full model ID; skills, mcpServers, hooks, effort and isolation: worktree are optional.
Claude delegates when your task matches a description, more readily if it says “use proactively”. An @-mention such as @agent-code-reviewer always runs that subagent.
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.
While teams are on, a subagent that Claude names launches as a teammate, so set the variable back to 0 when you want plain subagents. Teammates can't start teams of their own.
When subagents and agent teams cost more
Each subagent sends its own requests against the same usage limits, and builds its own cache, which lasts five minutes even on a subscription where the main conversation's lasts an hour; a fork reads 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. /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.
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.
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, and Ask Zest can compare which agents the team used against an earlier period. Codex subagent threads aren't tracked yet. More in Claude Code usage.
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.
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 that don't name one; otherwise a subagent runs 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.
