Skip to content
BENIBIX Learn

Claude Code Subagents

Level 5 · Growing past one chat

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 contentsLesson 15 of 16

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

11 mincovers 10 glossary entries

Worth reading first: Skills, Plugins and Styles

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.
Each helper works in its own context and sends back only a summary.

Worked 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.

The words for this lesson10

Check yourself

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

Finished this lesson?

Marking it complete also marks its 10 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.