Claude Code Sub-agents: what they are and what they are NOT

Sub-agents in Claude Code sound powerful, and the name alone can make them seem like a breakthrough. In reality, they’re a useful feature in a small set of cases, not a gamechanger. If you want to get value from them, you need to understand what they actually are, what they’re not, and when it makes sense to use them.

What they are

A sub-agent is an isolated and opaque conversation thread. Isolated means it has no connection to the main conversation (other than sending the initial message and receiving the final response). Opaque means that neither you nor the main agent can see what happens inside while it runs; you only get the final result once it’s done.

Technically, a sub-agent is a prompt (exactly like a Command). I do not know for sure, but it probably uses a “Developer Prompt,” a type of prompt that sits below the global Claude Code system prompt and above the user messages. The sub-agent always runs under that Developer Prompt, and its “User Message” does not come directly from you but from the main Claude Code agent. In other words, you write a message to the main agent, and the main agent writes the prompt that the sub-agent receives to start its work.

What they are NOT

Sub-agents don’t “compound” on their own. They don’t improve magically over time. If one fails, the only way it gets better is if you refine its prompt and run it again. That’s the work: inspect, adjust, repeat.

They’re also not like a teammate who picks up your standards naturally. They’re closer to a static prompt template: they’ll keep repeating the same mistakes until you explicitly tell them otherwise. Exactly the same as a Command.

And most importantly, they’re not free from constraints. Sub-agents come with three features that are also hard limitations: 1) lack of context, 2) lack of visibility, and 3) lack of direct prompt control. These define when they actually work and when they don’t. We’ll look at those next.

Key limitations

Three considerations are essential to keep in mind:

Chain of thought visibility is cumbersome. By default, you don’t see how a sub-agent reasons step by step (not even the final summary it sends back to the main agent). To inspect it, you must toggle into detailed transcript mode (Ctrl + R). That mode is not live and floods you with raw outputs (long DB queries, full file reads, irrelevant noise…). Following the reasoning becomes a slog instead of the clean, human-readable output you get with the main agent. For example, if a sub-agent skipped checking a critical file, you’d only catch it by digging through the detailed mode afterwards; a tedious process, and often too late or never done.

No direct prompt control. You don’t craft the prompt the sub-agent receives; the main agent generates it, and it can be suboptimal. For workflows where prompt precision matters, this is a serious limitation.

No access to main context. A sub-agent runs isolated by design: it does not inherit the ongoing conversation unless information is explicitly passed. This is a feature when you want to avoid prompt overload, but it also means you can’t rely on shared context.

These aren’t minor considerations, they’re structural trade-offs. They’re features in some situations and handicaps in others. Knowing the difference is what makes sub-agents usable.

Observed behavior

One more thing I’ve consistently noticed in practice: sub-agents tend to drift. Even when you assign them a relatively small task, they often run for minutes, burn through tokens, and produce bloated traces full of detours. The main Claude Code agent, when running Commands, usually completes tasks with the minimum number of steps. Sub-agents, by contrast, seem biased toward over-exploration, as if their underlying prompt were nudging them to be overly comprehensive.

I can’t confirm exactly why this happens. It may be due to differences in the system prompt Anthropic applies to sub-agents, but the effect is clear. Unless the task is extremely narrow, or unless you explicitly constrain the main agent to tell the sub-agent to stay focused, you’ll see runaway behaviors. This adds latency, cost, and noise, and takes away the agility you normally get with the main agent.

Commands vs. Sub-agents

Most of the time, Commands are the right tool. You can prompt directly, you keep full visibility, and you’re in control of the workflow.

Sub-agents are essentially an extension of Commands, worth using only when three conditions hold:

1. The task does not require a finely crafted prompt.

2. The task does not need the main conversation context.

3. The task does not require step-by-step supervision.

That’s roughly 10% of cases. In the other 90%, Commands will give you more control and better results.

But when those three conditions are met, sub-agents give you one big advantage: the main agent gets a single, clean report back in the conversation, with no need to juggle multiple terminals, intermediate files, or manual orchestration. That’s the real feature.

Use cases: good and bad

• Executor/evaluator loop: A bad fit. This pattern requires visibility into both agents’ reasoning and careful prompting. Doing it with sub-agents hides too much and guarantees poor results. The better solution is simply to run two main Claude Code instances with different Commands.

• Opponent processors: A good fit. Here you only care about the final arguments. For example, one sub-agent can over-engineer a design proposal while another strips it down to the simplest viable version. The main agent compares them and balances the trade-offs.

• Log investigator: Mixed. Parsing messy logs is valuable, but supervision matters. The safer pattern is to spin up another main agent instance, have it generate a structured report, and let the primary agent read that document. That keeps you in control without clogging context.

An alternative workflow

If what you really want is multi-agent collaboration—executor/evaluator, Dev + Log investigator, or any “division of roles” setup—you don’t have to rely on sub-agents. There’s a simple way to do it with main agents that avoids all their drawbacks.

Open two (or more) main agents in separate terminals. Each keeps full benefits: visible reasoning, precise prompts, and access to the main context. When one agent completes its task, have it write the final report into a working file (Markdown in a /working directory, optionally ignored by Git). Then the second agent reads that file as input and continues the process.

From there, the agents can iterate through the same document, or maintain separate files that both read and extend. They effectively “talk” to each other through these artifacts. The extra friction is minimal, a couple of working files, but the payoff is huge: you get real multi-agent collaboration without giving up control, visibility, or prompt precision.

tl;dr: where sub-agents really fit?

Sub-agents are a convenience feature. That’s the right mental model: they solve a small slice of problems where isolation and opacity are acceptable trade-offs.

If you try to use them everywhere, two things will happen. Either you let them run unchecked, and you’ll get suboptimal results: wrong assumptions, hallucinations, skipped steps you never saw. Or you try to control them as tightly as you would a main agent, and you’ll end up with a slow, clumsy workflow that defeats the purpose.

Their real value is in the narrow set of cases where those three conditions align. In those moments, sub-agents can remove a bit of friction and give you a clean final result in your main thread. Outside of that, you’re better off with Commands or the multi-agent patterns I’ve outlined above.