When Subagents Make More Sense Than a Single Agent

1. What subagents in Claude Code actually are

A subagent in Claude Code is a standalone agent instance started for a clearly scoped subtask, receiving its own context instead of inheriting the complete history of the main conversation. A main agent can task one or more subagents, wait for their result and then incorporate it into its own answer. This separation differs fundamentally from simply sending more messages to the same agent.

The key difference from a single, continuous agent lies in context management: while a single agent builds up its context across the entire session and thereby becomes fuller with every additional task, a subagent starts with a deliberately assembled, usually much smaller context. This makes subagents particularly suited for subtasks that require a lot of detail knowledge that is irrelevant to the rest of the conversation, for example searching a large codebase for a specific function.

Subagents in Claude Code can also be configured with their own, narrower tool permissions. A subagent that is only supposed to read files gets no write access, even if the main agent itself has write permissions. This property makes subagents not just a tool for context separation, but also a safety mechanism that allows permissions to be controlled more granularly than a single agent with one uniform permission profile.

{
  "main_agent": {
    "tools": ["read_file", "write_file", "run_tests", "grep", "list_directory"]
  },
  "subagent": {
    "name": "codebase_search_subagent",
    "tools": ["read_file", "grep", "list_directory"],
    "denied_tools": ["write_file", "run_tests"],
    "context": "fresh, no history from main agent session",
    "returns": "distilled result only, not raw file contents"
  }
}

2. Symptoms that a single agent is hitting its limits

Before deciding on subagents instead of a single agent, it is worth looking at typical warning signs. A clear symptom is when response quality noticeably declines as the session progresses, even though the task itself has not become harder. This suggests the context is overloaded with irrelevant details from earlier substeps and relevant information gets lost in the noise.

A second symptom is strongly fluctuating response times within the same session, which often correlate with growing context, since larger context windows require more processing time. A third symptom appears when an agent has to switch back and forth between functionally very different roles, for example between deep code understanding and superficial documentation work. Such role switches within a single agent frequently lead to inconsistent results, because the agent has to implicitly jump between different modes of thinking without this boundary being clearly marked in the context.

3. Criterion one: context size and topic switching

The first and most important decision criterion for subagents is the question of how strongly the required context differs between subtasks. If a subtask requires searching hundreds of files whose content is irrelevant to the actual main task, this search should happen in a subagent. The main agent only receives the distilled result at the end, not the full file contents it searched through.

A rule of thumb: if a subtask would consume more than roughly a quarter of the available context window purely on research steps that are no longer needed for subsequent steps, the numbers speak in favor of a subagent. This criterion can be checked objectively by estimating how many tokens the intermediate steps of a subtask need compared to the actually relevant result.

# Rough heuristic: estimate whether a subtask justifies a subagent
# Rule of thumb: if intermediate tokens >> final result tokens, use a subagent

estimate_subagent_benefit() {
  local intermediate_tokens="$1"
  local result_tokens="$2"
  local ratio
  ratio=$(echo "scale=1; $intermediate_tokens / $result_tokens" | bc)

  echo "Intermediate/result token ratio: ${ratio}x"
  if (( $(echo "$ratio > 5" | bc -l) )); then
    echo "Recommendation: use a subagent, discard intermediate context"
  else
    echo "Recommendation: keep it in the main agent context"
  fi
}

# Example: searching 40 files (~20000 tokens) to find one relevant function (~400 tokens)
estimate_subagent_benefit 20000 400

4. Criterion two: specialization and tool access

The second criterion for subagents concerns the functional specialization of a subtask. Some substeps benefit from their own system prompt tailored exactly to that one role, for example a subagent that exclusively checks code for security vulnerabilities and receives a specifically worded instruction focused on typical vulnerability classes for this purpose. Such a specialized system prompt would only dilute the main agent in its general role if it remained permanently part of the main context.

In addition, the required tool access plays a role. If a subtask needs access to a tool that the main agent should not permanently have available for safety reasons, for example running database queries, a subagent with tightly scoped tool access is the cleaner solution. This way the main agent remains restrictive in its base configuration, while the special task can still be completed.

#!/usr/bin/env bash
# Invoke a narrowly specialized subagent for a security-focused subtask
set -euo pipefail

claude --agent-config "subagents/security_reviewer.json" \
  --system-prompt "Check only for insecure deserialization, missing input \
validation and access control gaps. Ignore style and naming conventions." \
  --tools "read_file,grep" \
  --input "src/Model/Checkout/" \
  --output "reports/security-subtask.json"

echo "[main_agent] Security subagent finished, integrating distilled findings"

5. Criterion three: parallelizability of subtasks

The third criterion is the question of whether several subtasks can be worked on independently of each other. If, for example, three different modules of an application need to be checked for the same type of bug, three subagents can be started in parallel, each examining one module, instead of a single agent processing the modules one after another. For independent subtasks, this considerably shortens the overall runtime, while with a single agent the time increases linearly with the number of modules.

An honest check of independence is important here: if the result of checking module A should influence the approach to module B, for example because a shared pattern first needs to be discovered in module A, the task is not truly independent, and parallelizing with subagents brings no benefit here, only added complexity without any time savings.

6. Cost and latency: the price of splitting into subagents

Using subagents is not free. Every subagent needs its own system prompt, may need to inherit relevant context from the main agent, and produces its own result that the main agent has to integrate again. For very small subtasks, this coordination overhead can be larger than the actual savings from a smaller context, causing overall latency to rise rather than fall despite smaller individual contexts.

A practical rule: subagents only pay off once the context saved in the main agent clearly exceeds the additional overhead for starting, handoff and result integration. For very short, simple queries, for example quickly looking up a single constant, a dedicated subagent usually does not pay off, even if the topic mismatch criterion is formally met.

{
  "subagent_config": {
    "name": "security_scan_subagent",
    "trigger_condition": "task requires scanning more than 20 files for one pattern",
    "system_prompt": "Scan the given files for the specified vulnerability class only. Return findings as a compact JSON list, no prose explanation.",
    "tools": ["read_file", "grep"],
    "max_output_tokens": 2000
  },
  "estimated_cost_tradeoff": {
    "without_subagent_context_tokens": 45000,
    "with_subagent_main_context_tokens": 6000,
    "subagent_overhead_tokens": 1200,
    "net_savings_tokens": 37800
  }
}

7. Practical example: a refactor with and without subagents

A vivid example: a legacy module in a Magento extension needs to be migrated from an old to a new repository interface. Without subagents, the main agent would first have to search all call sites of the old interface across the entire repository, which for a large codebase easily loads several tens of thousands of tokens of file content into the context, of which only a handful of relevant lines of code actually end up being changed.

With subagents, a specialized search subagent takes over finding all call sites and returns only a compact list with file path and line number to the main agent. The main agent, whose context stays lean as a result, can then focus fully on the actual migration without being distracted by irrelevant search results. In this case, the benefit of subagents shows particularly clearly, because search and migration are functionally clearly separate activities.

#!/usr/bin/env bash
# Search subagent finds all call sites, main agent only migrates
set -euo pipefail

claude --agent-config "subagents/callsite_search.json" \
  --system-prompt "Find every call site of LegacyPriceRepositoryInterface. \
Return only file path and line number as a compact JSON list." \
  --tools "grep,read_file" \
  --input "app/code/Mironsoft/" \
  --output "state/callsites.json"

# Main agent context stays lean: it only receives the distilled list
echo "[main_agent] Migrating $(jq '. | length' state/callsites.json) call sites"

8. Common mistakes when deciding for or against subagents

A common mistake is reflexively using subagents for every subtask, regardless of whether the three criteria mentioned actually apply. This leads to unnecessary complexity, longer runtimes through coordination overhead, and workflows that are harder to trace, without any real benefit emerging. Subagents are a targeted tool, not a default procedure for every request.

The opposite mistake is just as common: a single agent gets loaded for hours with ever new, functionally different subtasks until the context is so overloaded that result quality visibly suffers. In this case, subagents introduced early for clearly scoped research steps would have significantly reduced the context load on the main agent and improved the overall quality of the session.

9. Single agent versus subagents compared

The following table summarizes which situations favor a single agent and which favor the use of subagents.

Deciding for or against subagents therefore cannot be made as a blanket rule, but depends on the concrete structure of the task. Whoever systematically checks the three criteria of context size, specialization and parallelizability makes a well founded decision rather than an intuitive one.

10. Summary

Subagents pay off whenever a subtask consumes significantly more context than is relevant to the final result, when it needs its own functional specialization or tighter tool permissions, or when several subtasks can be worked on independently in parallel. If none of these three criteria apply, a single agent remains the more efficient and simpler choice.

The choice between a single agent and subagents is not a fundamental question, but a question of task structure in each individual case. Whoever applies the three criteria consistently, and honestly accounts for the additional coordination overhead, avoids both unnecessary complexity and overloaded, increasingly slow single agents.

11. FAQ: When Subagents Make More Sense Than a Single Agent