A subagent is a separate helper that Claude Code can hand a task to. It runs in its own context window with its own instructions, does the work, and reports back. The key idea is separation: the messy details of a search or a review stay inside the subagent, and only the conclusion lands in your main session.
Why they help
Think about a task like "find every place we read the auth cookie." Doing that in your main session fills it with file dumps you will never look at again. A subagent can sweep those files, keep the noise in its own window, and return just the answer. Your main context stays clean and focused on the real work.
They are also good for parallel work. Because each subagent has its own context, you can send several off at once to investigate different parts of a problem.
When to reach for one
- Investigation that reads a lot of files but produces a short answer.
- Repeated, well-defined jobs like code review or test writing.
- Parallel research across separate areas of the codebase.
- Keeping the main session tidy during a long, focused task.
When to skip them
If the task is small and you already know the file, just do it in the main session. A subagent adds a round trip, so it pays off when the work is large or when you want to protect your main context.
Claude Code ships with a few built-in agents (Explore, Plan, and general-purpose), and you can define your own with a small Markdown file:
---
name: log-finder
description: Finds where a given error message is logged. Use for quick log lookups.
tools: Grep, Glob, Read
---
You locate logging call sites and report the file and line. Do not change anything.
The rest of this series shows how to build and use them.
Comments
Be the first to comment.