AI glossary · Agents and tools

What is a subagent in Claude Code?

Also called: sub-agent, Claude Code subagent, custom agent

Definition

A subagent is a separate AI worker that a main agent hands a task to, running in its own context window with its own system prompt, tools and model, and returning only its result to the main conversation.

Explained

How it works

In Claude Code, the main conversation can delegate a task, such as searching a codebase or reading a long log, to a subagent. The subagent starts fresh: it doesn’t see your conversation history or the files Claude has already read. It does load your CLAUDE.md, unless its file sets omitClaudeMd: true (the built-in Explore and Plan agents skip it), then works through its own tool calls and hands back a summary.

You define one as a Markdown file with YAML frontmatter, in .claude/agents/ for one project or ~/.claude/agents/ for all of them. Only name and description are required, and the body becomes its system prompt. Claude reads the description to decide when to delegate, so write it as “when to use me”. Built-in subagents include Explore, Plan and general-purpose, and by default a subagent can start its own, up to three layers below the main conversation.

Example

A log-summarising subagent and what its description costs

This file keeps long build and test logs out of the main conversation. tools limits the subagent to reading and searching, and model: haiku runs it on Claude Haiku 5.5, at $0.10 per million input tokens against $2 for Claude Sonnet 5.5 in our daily data.

The description is 36 tokens on OpenAI’s o200k_base tokenizer (Claude’s tokenizer counts differently, so treat it as an estimate). Descriptions take up space in the main context, which is why Claude Code warns at startup when your custom subagents’ descriptions together pass 15,000 tokens.

.claude/agents/log-summariser.md

---
name: log-summariser
description: Reads long build, test or CI logs and returns only the failures, each with file, line and error message. Use proactively when a log is too long to read in full.
tools: Read, Grep, Glob
model: haiku
---

You summarise logs. Find every failure or error in the log you are given.
For each one, report the file, the line and the exact error message, then
one sentence on the likely cause. Never paste the whole log back.

Cost and quality

Why it matters

A subagent’s file reads, searches and tool output stay in its own context, so the main conversation stays short and focused, and every later turn re-sends less. Routing routine work to a cheaper model lowers cost further.

It isn’t free. A subagent spends tokens of its own while it runs, which count towards the same usage limits, and many subagents returning long reports can still fill the main context. Ask for short results.

Don’t mix up

Common confusions

Subagent vs skill: By default, a skill loads its instructions into the current conversation when it’s used; a skill with context: fork runs in a subagent instead. A subagent runs in a separate context window and only its result comes back.
Subagent vs fork: A normal subagent starts with an empty context plus its task. A fork starts with a copy of your conversation so far, then works separately.

Go deeper

Try it and read more

All 40 terms in the AI glossary

How it works

A log-summarising subagent and what its description costs

Why it matters

Common confusions

Try it and read more

Related terms