💰 The real savings

Think of a newsroom. The editor-in-chief doesn't rush after every source: it reads, decides the agenda, delegates, and wraps up the edition. The one who goes out into the field, transcribes interviews, and checks spelling is the team — good people, cheaper and more numerous. If the boss did everything, the payroll would explode and the newspaper would come out late. Subagents work the same way: let one expensive model for thinking and a low-cost fleet work. The savings don’t come from cutting quality—they come from put each model where it performs best.

↑ The economics: one expensive lead decides, a fleet of cheap agents executes in parallel, and the lead wraps up the edit.

The money-saving design has two roles. At the top, an expensive model — Opus or Sonnet — which thinks: reads the problem, makes a plan, distributes the tasks, and brings it all together at the end. Underneath, a fleet of inexpensive models — Haiku — which does the heavy lifting: scans, searches, reads files, summarizes. You pay for the expensive once, for the hard part, and the cheap one often, for the mechanical part.

You can set the model for each subagent one by one, in the field model from the file. But when you want the entire fleet run it cheaply all at once, there's a shortcut: the environment variable CLAUDE_CODE_SUBAGENT_MODEL. It defines the model default for all subagents that haven't pinned down their own model — without you touching each file.

# toda a frota de subagentes passa a rodar em Haiku
export CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5

# abra o Claude Code já com a frota barata ligada
claude

# o chefe (a sessão principal) continua no modelo que
# você escolheu — só os subagentes herdam o Haiku.

The cost that should worry you isn’t the subagent that does the work — it’s the subagent that gets into a loop: tries, fails, tries again, and keeps running at your expense. The maxTurns is the cap on how many steps (tool turns) a subagent can take before stopping. It's a circuit breaker: when the limit is reached, shut it down—instead of burning tokens all night.

There's no magic: running a fleet of subagents consumes many more tokens that a single conversation — in the order of ~15×. Each subagent starts from scratch and gathers its own context before producing. This isn't a waste automatic: that's the price of parallelism and clean context. The right question isn't "is it expensive?", but "what do I get that makes this 15× worthwhile?".

↑ Illustrative recreation, not an actual measurement. The proportion is there to establish the order of magnitude.

The wrong instinct is "if it’s expensive, I need a stronger model." Almost never. The real gains come from combine: the right model for the right role, the right limit, the right parallelism. A well-orchestrated Haiku fleet led by a Sonnet chief delivers more for less than everything in Opus. Architecture beats brute force.

Real savings require look at the cost. How much did each subagent use? Which one hit the limit? Where did the time go? Without monitoring, you're optimizing in the dark — cutting what was cheap and leaving the expensive one running. Measure first, adjust later: that's how the boss/fleet split stops being a guess and becomes a number.

The two controls in this module fit in the frontmatter of a single file .md: model says who does (cheap model), and maxTurns says how far it can come before stopping. This log-scanner.md is a typical fleet worker: cheap, read-only, with a cap.

--- # frontmatter: a CONFIGURAÇÃO do subagente
name: log-scanner             # minúsculas e hífens
description: Vasculha logs e arquivos grandes em
  busca de erros e devolve só um resumo. Use para
  varreduras pesadas.          # o GATILHO
tools: Read, Grep, Glob       # só leitura: trabalho de frota
model: haiku                  # BARATO — é a frota, não o chefe
maxTurns: 12                  # TETO — disjuntor contra loop
---

# corpo: o CÉREBRO do subagente
You are a fast log scanner.

When invoked:
1. Grep the given files for errors and warnings.
2. Group what you find by type and file.
3. Stop as soon as you have the summary.

Return: a short report — counts per error type
and the 3 files with the most issues. Nothing else.
Do not open files line by line; do not loop.

Three prompts to apply these savings now: turn on the low-cost fleet, set a cap to prevent loops, and map out the lead/fleet split before spending. Notice the pattern: right model for the right role, with limit.

Quero que toda a frota de subagentes rode em Haiku,
mas que você (o chefe) continue em Sonnet. Me mostre
como ligar isso com CLAUDE_CODE_SUBAGENT_MODEL e
confirme quem ficou em qual modelo.

Crie um subagente de varredura de logs em Haiku,
read-only, com maxTurns 12 para ele não entrar em
loop. Quero o arquivo .md pronto, com model e maxTurns
no frontmatter.

Para este trabalho [descreva], me proponha a divisão
chefe/frota: o que fica no modelo caro (decidir/juntar)
e o que vai para a frota Haiku em paralelo. Diga qual
modelo e qual maxTurns para cada papel — e por quê.

This is how the savings show up when you observes: o boss in Opus barely does any work, because it only thinks; the Haiku fleet does the heavy lifting for a fraction of the cost; and there's a warning where an agent touched the maxTurns. This is the diagram that shows where cut — before guessing.

↑ Illustrative recreation of the cost panel (not a real screenshot). The lead thinks for a little while; the fleet carries the workload — and the cap stopped the stuck agent.