# Claude Code Subagents

> How Claude Code subagents work in their own context and send back a summary. The built-in ones, writing your own, the agent tools and agent teams.

**Course:** [Claude Code Basics](https://learn.benibix.com/learn/ai-claude-code)  
**Time:** 11 min

**After this lesson you can:**

- Say why a subagent keeps the main chat clean
- Write a subagent file
- Tell a subagent from an agent team

## How helpers work beside the main chat

A subagent is a helper with its own fresh context window. Claude starts one with the Agent tool and hands it a task. It works alone, then sends back one final answer. The main chat never sees the steps in between. Subagents run in the background by default, and a session can run up to 20 at once.

That is the point of them. A search through 300 files fills a context window with results. Done by a subagent, the main chat gets back only the short answer and keeps its room for the real work. A subagent can start its own helpers too, up to three layers deep.

Claude Code comes with a few ready to use. Explore can only read and search, and it looks through a codebase fast. Plan gathers facts while you are in plan mode. The general-purpose one can use every tool a subagent may have, for jobs that mix looking and doing.

You can write your own as a Markdown file in .claude/agents/ for one project, or in ~/.claude/agents/ for all of them. The header needs a name and a description of when to use it. It can also list its tools and its model. The text below the header is the helper's own instructions.

A few more tools manage helpers. SendMessage sends a note to another agent, and ListAgents lists who can get one. TaskStop stops a background task by its id. In auto mode, a subagent hands its report back with SubagentHandback, so the safety check reads it first. The Workflow tool runs a script that sends out many helpers and joins what they find.

Agent teams go one step further. Several full Claude Code sessions work together under one team lead. They share a task list and send messages straight to each other, and you can talk to any of them. Teams are an early feature and are off by default. They cost more tokens, since each teammate is a whole session.

```markdown
---
name: code-reviewer
description: Reviews a change for bugs and unclear names. Use after writing code.
tools: Read, Grep, Glob
model: sonnet
---

You review code. List each problem with its file and line, and say why it matters.
```
A helper that can only read. It reviews the change and sends back one list.

![The main session sends tasks out to three helpers: Explore reads and searches only, Plan gathers facts in plan mode, and the general-purpose one does most jobs. Each sends a summary back.](https://learn.benibix.com/diagrams/cc-built-in-subagents.svg)

### Example: Jack keeps the main chat for the fix

Jack needs to know where a date format is used in a repo of 2,000 files. He asks Claude to find out without filling the chat.

Claude sends Explore. It reads 60 files and returns a list of 9 places in 12 lines, and the main chat goes straight on to the fix.

**Words in this lesson:** [Subagent](https://learn.benibix.com/term/ai/subagent), [Agent Tool](https://learn.benibix.com/term/ai/agent-tool), [Built-in Subagents](https://learn.benibix.com/term/ai/built-in-subagents), [Claude Code Subagent](https://learn.benibix.com/term/ai/claude-code-subagent), [SendMessage Tool](https://learn.benibix.com/term/ai/send-message-tool), [ListAgents Tool](https://learn.benibix.com/term/ai/list-agents-tool), [TaskStop Tool](https://learn.benibix.com/term/ai/task-stop-tool), [SubagentHandback Tool](https://learn.benibix.com/term/ai/subagent-handback-tool), [Workflow Tool](https://learn.benibix.com/term/ai/workflow-tool), [Agent Teams](https://learn.benibix.com/term/ai/agent-teams)

> **A subagent reports back, a teammate talks back.** A subagent lives inside one session. It takes a task and returns one answer to the chat that started it. A teammate in an agent team is a whole session of its own. It shares a task list, messages the others, and you can talk to it directly. Pick subagents when only the result matters.

**Question:** Why send a big search to a subagent instead of doing it in the main chat?

**Answer:** Only the short answer comes back, so the main context window stays free. The subagent reads everything in its own context and returns just the answer. The main chat keeps its room for the real work.

---

Source: https://learn.benibix.com/learn/ai-claude-code/claude-code-subagents
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-18
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
