Zest

CLAUDE CODE · SUBAGENTS

Claude Code subagents
and agent teams.

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.

Start free
npx @winding-labs/zest

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

Flyps Charm Wildfires Geoforge MisaLabs

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.
SubagentToolsUsed for
ExploreRead-onlySearching a codebase; skips CLAUDE.md to stay small
PlanRead-onlyResearch while you are in plan mode
general-purposeAllMulti-step work that explores and edits
forkSame as the main sessionA 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.
LocationWho gets it
Managed settingsYour whole organization
--agents JSON flagThat session only
.claude/agents/Everyone who clones the repository
~/.claude/agents/You, in every project
A plugin's agents/Anyone with the plugin, as plugin-name:agent-name

Subagent frontmatter fields

Only name and description are required. Field names are camelCase and must match exactly: Claude Code ignores an unknown field without an error.

Subagent frontmatter in Anthropic's docs. Plugin subagents ignore hooks, mcpServers and permissionMode.
FieldWhat it does
nameUnique id, such as code-reviewer. It can't contain :
descriptionWhen Claude should delegate. "Use proactively" makes it delegate more readily
tools, disallowedToolsAllow or deny list; without either, it gets every tool
modelsonnet, opus, haiku, fable, a full model ID, or inherit
permissionModedefault, acceptEdits, auto, dontAsk, bypassPermissions or plan
skillsSkills whose full text loads at startup
mcpServers, hooksMCP servers and hooks scoped to this subagent
memoryuser, project or local: a folder of notes it keeps across sessions
maxTurns, effortA turn limit and an effort level
isolation: worktreeRuns 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.

~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

When subagents and agent teams cost more

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.
SymptomCause and fix
Never appearsNo name, or the first --- isn't line 1, so the file reads as documentation
Skipped, with a debug-log errorA name without a description, or a name containing :
The wrong definition runsTwo files in one agents folder share a name and file order picks one; /doctor reports duplicates
Ignores CLAUDE.mdExplore and Plan skip it. Restate the rule in the task you delegate
disallowedTools: Bash(git push *) removes all of BashA 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

Start free
npx @winding-labs/zest

A FEW THINGS TO KNOW

Questions

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.