🤖 What is a subagent

Imagine you are a general contractor working on a project. You don't lay every brick: you call the electrician, the plumber, the painter — each one does their part and hands you the finished work. Claude Code works the same way. You talk to the orchestrator (the main chat). When a heavy task comes up, the orchestrator launches subagents: specialists who do the work in a separate window and return only the summary. This is the design you need to remember.

↑ The subagent flow: one launches, many work in parallel, one summary comes back.

The chat you’re talking to is orchestrator — the orchestrator. It understands the request, decides what needs to be done, and, when the task is large, delegates to a specialist. You never stop talking to the conductor: it’s your point of contact from beginning to end.

The heart of the subagent is the separate context. When the conductor delegates, the subagent opens a own window — a clean session, isolated from your conversation. It does the work there, creates whatever mess it needs, and returns only a report. The maestro reads that report and communicates back to you. Your window never sees the mess.

The classic example: you ask the conductor to review a book under five different perspectives. Instead of doing five readings in a row, it opens five subagents in parallel — each with one lens own. They run at the same time, each in its own window. And you can enter each session and see exactly the prompt the orchestrator sent to that specialist.

This is where the most common confusion lies. The subagent isn't the main chat and you doesn't talk to it directly. It doesn't answer you — it answers to the orchestrator. Thinking of it as "another chat where I type" is the mistake that makes everything seem broken.

Each subagent speaks only with the maestro. Subagents don't talk to each other. It's a star model: the conductor at the center, each specialist connected to it by a direct line, and no lines between the specialists. This keeps everything predictable — no "telephone game" between workers.

You don’t need to create anything to get started. Claude Code already comes with subagents built-in (such as the general-purpose, which researches and reads files). To invoke one, just natural language: you describe the service and the orchestrator decides whether to delegate. No special command, no difficult syntax.

você > Pesquise a ferramenta "ripgrep" e me traga só
        um resumo de 5 bullets, sem encher meu contexto.

# o maestro decide delegar a um subagente built-in,
# que abre a janela dele, faz a pesquisa pesada,
# e devolve ao maestro só os 5 bullets pedidos.

maestro > Pronto — 5 pontos sobre o ripgrep:
        1) busca recursiva ultrarrápida em texto …

A custom subagent is just a file .md: a configuration header (frontmatter) and a body with the instructions. You’ll examine each field in the following tracks — for now, read this code-reviewer.md just enough to get a feel for it.

--- # frontmatter: a CONFIGURAÇÃO do subagente
name: code-reviewer            # minúsculas e hífens
description: Revisa o diff atual em busca de bugs,
  falhas de segurança e testes faltando. Use após
  qualquer mudança de código.   # isto é o GATILHO
tools: Read, Grep, Glob       # só leitura: não edita nada
model: sonnet                 # bom o bastante para revisar
---

# corpo: o CÉREBRO do subagente
You are a senior code reviewer.

When invoked:
1. Run git diff to see what changed.
2. Read the changed files and understand the intent.
3. Review for correctness, security and missing tests.

Flag: bugs, security holes, and missing tests.
Be concise. Do not rewrite the code — only report.

Two prompts for you to invoke a built-in subagent right now, without configuring anything. Notice the pattern: ask the summary and protect the context.

Abra um subagente pra pesquisar a ferramenta X e me
traga só um resumo de 5 bullets. Não cole o conteúdo
bruto aqui — só a conclusão.

Use o general-purpose pra ler estes arquivos e me
resumir o que importa, sem encher meu contexto.
Devolva no máximo 1 parágrafo + os caminhos relevantes.

This is how the demo with the 5 personas appears in the terminal: the lead launched five subagents, and you can see them running side by side, each with its own model and progress. Below, the status line shows how much of the your context is in use — and it barely changes, because the heavy work is happening in their windows.

↑ Illustrative recreation of the terminal (not a real screenshot). Note the 5 subagents working at full speed while your context barely moves.