What is a subagent — and why it saves context, not time

Here's the non-obvious part: you don't call a subagent for speed. You call one to keep your own memory clean.

Picture it. You ask the agent to find where order pricing gets calculated. It opens forty files, wanders into three dead ends, reads a pile of irrelevant code — and all of that now sits in your conversation forever. From here on you're working near the limit: it starts forgetting what you agreed at the start.

A subagent fixes exactly that. It reads the same forty files on its own side and hands you five lines: "pricing is assembled here, in this function." The forty files stay with it.

A subagent is an agent with a clean desk

Technically a subagent is an ordinary AI agent that the main agent launches as a helper. One thing sets it apart: it has its own context window, separate from your conversation.

In Claude Code a subagent is a file in .claude/agents/:

---
name: code-explorer
description: Finds where functionality is implemented in the project. Use when
  you need to understand how unfamiliar code is wired together.
tools: Read, Grep, Glob
model: sonnet
---

You are a code explorer. Find the relevant places and return a short report:
file, line, role in the overall design. Do not edit code.

Notice tools. This helper got reading and search only — it physically cannot write. That's not a polite request buried in text, it's a hard limit: handy when you don't want your "explorer" suddenly rewriting files.

What it returns — and what gets lost on the way

A subagent works alone, then hands back a result. Not its whole transcript, not thirty steps of reasoning — just the final answer.

Two consequences follow, and beginners learn the second one the hard way.

First, the good one. Your context stays clean. You can run five checks in a row and never approach the memory limit. That's what separates a subagent from simply asking again — it's context management, not multitasking.

Second, the painful one. A subagent cannot see your conversation. It doesn't know you decided to switch libraries half an hour ago, or that "that bug" means the cart bug. It starts from a blank page.

So brief it like a stranger: file names, conditions, and what "done" looks like. "Finish it the way we agreed" fails every single time.

When to call one, and when not to

A subagent wins where there's a lot of reading and a little output:

• scouting an unfamiliar project: "find where payments are handled";
• checking a hunch: "is this function still used anywhere?";
• reviewing changes before a commit;
• several independent checks at once — those can run in parallel.

A subagent loses when:

• the edit is small and you already know the file — handing off costs more than doing it;
• you need a back-and-forth — the helper answers once;
• the task leans on conversation history that would take ages to restate.

Simple rule: lots of noise in, short answer out — call a subagent. Otherwise, do it yourself.

Is a subagent the same as a multi-agent system?

Almost, but smaller in scale. A multi-agent system is an architecture where several agents talk and split roles. A subagent is the narrow case: one main agent, helpers for specific tasks, and you only ever talk to the main one.

Can several subagents run at once?

Yes, and that's a strength: one studies the backend while another looks at the frontend. But the moment they start editing files in the same folder, you get a race — two of them rewriting the same thing. Parallel editing needs a working directory each: how that's done is in the article on git worktree.

Does a subagent save money?

No — don't mix this up. It saves room, not spend. The subagent burns its own tokens reading those same forty files, just in its own window. The win is that your conversation stays short and the agent holds the whole task longer. It's a fee for a clear head, not a discount.

Why did the subagent return less than I expected?

Because it hands back a result, not a transcript. If you want detail, ask for it in the brief: "return the list of files with line numbers." Whatever you didn't order gets compressed — it has no idea what matters to you. Same principle as the agent loop: the output is shaped by the brief, not by guesswork.