Skip to main content

Subagents

📖 Lesson content

Video

Subagents

Claude can delegate tasks to subagents that break them down and run component tasks in parallel, improving your context management. Each subagent operates in its own isolated context window.

How It Works

Managing context in Claude Code is important. A lot of the context window gets consumed by things like tool calls exploring your codebase or running web searches for research. What Claude discovers during that exploration isn't always relevant to the main feature you're developing.

This is where subagents come in. Claude spawns a subagent to handle a task like "explore this codebase for me." The subagent runs in parallel with its own context window, does all the exploration work, and once finished, summarizes its findings and returns that summary back to Claude.

summary

summary

summary

Main Claude — main context

subagent-explorer

subagent-researcher

subagent-reviewer

The result: you get the answer you were looking for, without the entire journey it took to get there cluttering your main context.

Creating Your Own Subagent

Subagents are defined in Markdown files with YAML frontmatter. The easiest way to get started is to let Claude generate one for you. Run:

/agents

Then select "Create new agent." You'll walk through steps including choosing the scope of the agent, defining its purpose, selecting the tools it has access to, and even picking a color for it.

Claude will generate a name, description, and prompt for the subagent. This also tells Claude when to call the subagent based on the prompts you give it.

Further Customization

Subagents can be customized further. Here are some highlights:

  • Persistent memory lets your subagent retain memory across conversations. This is great if you're using it consistently on the same projects.
  • Preload skills into subagents by adding the skill key and listing skills by name. Note that unlike skills in your main conversation, the entire skill is loaded into context here.

Recap

Keeping your context window clean is one of the best ways to stay productive with Claude Code. With subagents, you can run an agent in the background to handle the heavy lifting and return just the answer to your main context window.

Want to go deeper? Check out our dedicated course: Introduction to subagents

🎬 Video transcript

Source video: jKErNxuxPXg

📜 Click to expand transcript (cleaned + AI-translated)

Introduction to Subagents in Claude Code

Subagents are specialized assistants that Claude Code can delegate tasks to. Each subagent runs in its own conversation context window with a custom system prompt that you define. When finished, it returns a summary to the main thread while all the intermediate work stays isolated.

How Subagents Work

The subagent receives two primary inputs: a custom system prompt from your configuration file and a task description written by the parent agent based on your request. Once activated, the subagent works autonomously. When it reads files, edits files, or uses tools, none of these actions appear in the main conversation; only a summary is returned. After the task is completed, the entire subagent conversation is completely discarded.

Managing Context Window Usage

One of the main advantages of subagents is that they help manage context window usage. When you chat with Claude Code, every interaction adds context to the main window. Every tool call and its results are stored there.

By using a subagent, a separate window is started. This prevents the main context window from being cluttered with intermediate steps. This is crucial for maintaining performance and efficiency during long sessions.

Practical Example: Codebase Investigation

Consider a task like investigating how the payment system works in an unfamiliar codebase. You might use Claude Code to figure out which service handles refunds.

  • Without a subagent: Claude might read 15 files, run several searches, and trace through multiple function calls. All of that context fills your main context window, even if you only needed one single fact: which service handles refunds.
  • With a subagent: You get the answer without the "journey." The subagent explores, discovers the answer, and returns a focused summary, keeping your main context clean.

However, it is important to note that the main window loses visibility into how the subagent reached its conclusions and what it discovered along the way.

Built-in and Custom Subagents

Claude Code includes several built-in subagents that you can use immediately:

  • General Purpose Subagent: Used for multi-step tasks that require both exploration and action.
  • Explore Subagent: Used for fast searching of codebases.
  • Plan Subagent: Used during "plan mode" for research and analysis of your codebase before presenting a plan.

Beyond these, you can also create your own subagents with custom system prompts and specific tool access. Subagents allow Claude Code to break work into focused pieces, keeping your main context window clean and bringing back exactly what you need. Whether you are using the built-in options or creating your own, they are a practical way to get more out of longer Claude Code sessions.

🔁 Related lessons

📚 Source & attribution

Was this lesson helpful?

Feedback / ReportSpotted an issue or have an improvement idea?