Orquestre equipes de sessões Claude Code

Equipes de agentes são experimentais e desabilitadas por padrão. Ative-as adicionando CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS ao seu settings.json ou ambiente. Sem essa variável, nenhuma equipe é configurada no início da sessão, nenhum diretório de equipe é escrito, e Claude não gera ou propõe companheiros de equipe. Equipes de agentes têm limitações conhecidas em torno de retomada de sessão, coordenação de tarefas e comportamento de encerramento.

Equipes de agentes permitem que você coordene múltiplas instâncias Claude Code trabalhando juntas. Uma sessão atua como o líder da equipe, coordenando o trabalho, atribuindo tarefas e sintetizando resultados. Os companheiros de equipe trabalham independentemente, cada um em sua própria context window, e se comunicam diretamente uns com os outros. Diferentemente de subagents, que são executados dentro de uma única sessão e podem apenas relatar de volta ao agente principal, você também pode interagir com companheiros de equipe individuais diretamente sem passar pelo líder.

Esta página descreve equipes de agentes a partir da v2.1.178. Com CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS definido, gerar um companheiro de equipe não requer mais uma etapa de configuração, e a limpeza acontece automaticamente quando a sessão sai. Antes da v2.1.178, você pedia ao Claude para criar e nomear uma equipe primeiro, e Claude usava as ferramentas TeamCreate e TeamDelete para configurá-la e removê-la. Ambas as ferramentas não existem mais. A entrada team_name na ferramenta Agent é aceita mas ignorada, e o campo team_name em TaskCreated, TaskCompleted, e TeammateIdle payloads de hook carrega o nome derivado da sessão e está descontinuado.

Quando usar equipes de agentes

Equipes de agentes são mais eficazes para tarefas onde a exploração paralela adiciona valor real. Veja exemplos de casos de uso para cenários completos. Os casos de uso mais fortes são:

Pesquisa e revisão: múltiplos companheiros de equipe podem investigar diferentes aspectos de um problema simultaneamente, depois compartilhar e desafiar as descobertas uns dos outros
Novos módulos ou recursos: companheiros de equipe podem possuir cada um uma peça separada sem se atrapalharem
Depuração com hipóteses concorrentes: companheiros de equipe testam diferentes teorias em paralelo e convergem para a resposta mais rapidamente
Coordenação entre camadas: mudanças que abrangem frontend, backend e testes, cada uma de propriedade de um companheiro de equipe diferente

Equipes de agentes adicionam sobrecarga de coordenação e usam significativamente mais tokens do que uma única sessão. Funcionam melhor quando os companheiros de equipe podem operar independentemente. Para tarefas sequenciais, edições no mesmo arquivo ou trabalho com muitas dependências, uma única sessão ou subagents são mais eficazes.

Comparar com subagents

Tanto equipes de agentes quanto subagents permitem que você paralelizar o trabalho, mas operam de forma diferente. Escolha com base em se seus trabalhadores precisam se comunicar uns com os outros:

Diagrama comparando arquiteturas de subagent e equipe de agentes. Subagents são gerados pelo agente principal, fazem trabalho e relatam resultados de volta. Equipes de agentes coordenam através de uma lista de tarefas compartilhada, com companheiros de equipe se comunicando diretamente uns com os outros.

	Subagents	Agent teams
Context	Context window própria; resultados retornam ao chamador	Context window própria; totalmente independente
Communication	Relatam resultados de volta apenas ao agente principal	Companheiros de equipe se mensageiam diretamente
Coordination	Agente principal gerencia todo o trabalho	Lista de tarefas compartilhada com auto-coordenação
Best for	Tarefas focadas onde apenas o resultado importa	Trabalho complexo que requer discussão e colaboração
Token cost	Menor: resultados resumidos de volta ao contexto principal	Maior: cada companheiro de equipe é uma instância Claude separada

Use subagents quando você precisa de trabalhadores rápidos e focados que relatem de volta. Use equipes de agentes quando os companheiros de equipe precisam compartilhar descobertas, desafiar uns aos outros e coordenar por conta própria.

Ativar equipes de agentes

Equipes de agentes são desabilitadas por padrão. Ative-as definindo a variável de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS como 1, seja no seu ambiente de shell ou através de settings.json:

settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Inicie sua primeira equipe de agentes

Após ativar equipes de agentes, descreva a tarefa e os companheiros de equipe que você deseja em linguagem natural. Claude os cria e coordena o trabalho com base no seu prompt. Este exemplo funciona bem porque os três papéis são independentes e podem explorar o problema sem esperar um pelo outro:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

A partir daí, Claude popula uma lista de tarefas compartilhada, cria companheiros de equipe para cada perspectiva, faz com que explorem o problema e sintetiza descobertas quando terminar. O terminal do líder lista companheiros de equipe no painel do agente abaixo da entrada do prompt. A partir do painel:

Setas para cima e para baixo: selecione um companheiro de equipe
Enter: abra a transcrição do companheiro de equipe selecionado e envie uma mensagem diretamente
Escape: interrompa o turno atual do companheiro de equipe selecionado

A partir da v2.1.181, a linha de um companheiro de equipe ocioso se oculta após 30 segundos e reaparece em seu próximo turno. O companheiro de equipe continua em execução e endereçável enquanto oculto. Se você quiser cada companheiro de equipe em seu próprio painel dividido, veja Escolha um modo de exibição.

Controle sua equipe de agentes

Diga ao líder o que você quer em linguagem natural. Ele lida com coordenação de equipe, atribuição de tarefas e delegação com base em suas instruções.

Escolha um modo de exibição

Equipes de agentes suportam dois modos de exibição:

In-process: todos os companheiros de equipe são executados dentro do seu terminal principal. Use as teclas de seta para cima e para baixo no painel de agentes para selecionar um companheiro de equipe, depois pressione Enter para visualizá-lo e digite para enviar mensagens para ele diretamente. Funciona em qualquer terminal, nenhuma configuração extra necessária.
Split panes: cada companheiro de equipe recebe seu próprio painel. Você pode ver a saída de todos de uma vez e clicar em um painel para interagir diretamente. Requer tmux ou iTerm2.

tmux tem limitações conhecidas em certos sistemas operacionais e tradicionalmente funciona melhor no macOS. Usar tmux -CC no iTerm2 é o ponto de entrada sugerido para tmux.

O padrão é "in-process". Antes da v2.1.179, o padrão era "auto", portanto sessões atualizadas que anteriormente abriam split panes agora permanecem em um terminal, a menos que você defina o modo explicitamente. Defina "auto" para ativar split panes quando você já estiver executando dentro de uma sessão tmux ou seu terminal for iTerm2, voltando para in-process caso contrário. A configuração "tmux" ativa o modo split-pane e detecta automaticamente se deve usar tmux ou iTerm2 com base no seu terminal. A partir da v2.1.186, defina "iterm2" para usar explicitamente split panes nativos do iTerm2. Este modo requer o CLI it2 e mostra um erro com o comando de instalação se it2 estiver faltando. O prompt de configuração que oferece instalar it2 ou mudar para tmux aparece em "auto" ou "tmux" quando seu terminal é iTerm2 e tmux está disponível como fallback. Para substituir o padrão, defina teammateMode em ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

Para definir o modo para uma única sessão, passe como um sinalizador:

claude --teammate-mode auto

O modo split-pane requer tmux ou iTerm2 com o CLI it2. Para instalar manualmente:

tmux: instale através do gerenciador de pacotes do seu sistema. Veja o wiki tmux para instruções específicas da plataforma.
iTerm2: instale o CLI it2, depois ative a API Python em iTerm2 → Settings → General → Magic → Enable Python API.

Especifique companheiros de equipe e modelos

Claude decide o número de companheiros de equipe a gerar com base em sua tarefa, ou você pode especificar exatamente o que deseja:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Os companheiros de equipe não herdam a seleção /model do líder por padrão. Para alterar o modelo usado quando o prompt não especifica um, defina Default teammate model em /config. Escolha Default (leader’s model) para que os companheiros de equipe sigam o modelo atual do líder. Os companheiros de equipe herdam o nível de esforço do líder. No modo split-pane isso se aplica a partir da v2.1.186; versões anteriores não passavam o esforço da sessão do líder para companheiros de equipe em split-pane.

Exigir aprovação de plano para companheiros de equipe

Para tarefas complexas ou arriscadas, você pode exigir que os companheiros de equipe planejem antes de implementar. O companheiro de equipe trabalha em modo de plano somente leitura até que o líder aprove sua abordagem:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

Quando um companheiro de equipe termina o planejamento, ele envia uma solicitação de aprovação de plano ao líder. O líder revisa o plano e o aprova ou o rejeita com feedback. Se rejeitado, o companheiro de equipe permanece em modo de plano, revisa com base no feedback e resubmete. Uma vez aprovado, o companheiro de equipe sai do modo de plano e começa a implementação. O líder toma decisões de aprovação autonomamente. Para influenciar o julgamento do líder, dê a ele critérios no seu prompt, como “apenas aprove planos que incluam cobertura de testes” ou “rejeite planos que modifiquem o esquema do banco de dados”.

Fale com companheiros de equipe diretamente

Cada companheiro de equipe é uma sessão Claude Code completa e independente. Você pode enviar mensagens para qualquer companheiro de equipe diretamente para dar instruções adicionais, fazer perguntas de acompanhamento ou redirecionar sua abordagem.

Modo in-process: use as teclas de seta para cima e para baixo no painel de agentes para selecionar um companheiro de equipe, depois pressione Enter para visualizar sua sessão e digite para enviar uma mensagem. Pressione x em um companheiro de equipe selecionado para interrompê-lo. Pressione Ctrl+T para alternar a lista de tarefas.
Modo split-pane: clique em um painel de companheiro de equipe para interagir com sua sessão diretamente. Cada companheiro de equipe tem uma visualização completa de seu próprio terminal.

Atribuir e reivindicar tarefas

A lista de tarefas compartilhada coordena o trabalho em toda a equipe. O líder cria tarefas e os companheiros de equipe as trabalham. As tarefas têm três estados: pendente, em progresso e concluída. As tarefas também podem depender de outras tarefas: uma tarefa pendente com dependências não resolvidas não pode ser reivindicada até que essas dependências sejam concluídas. O líder pode atribuir tarefas explicitamente ou os companheiros de equipe podem auto-reivindicar:

Líder atribui: diga ao líder qual tarefa dar a qual companheiro de equipe
Auto-reivindicar: após terminar uma tarefa, um companheiro de equipe pega a próxima tarefa não atribuída e desbloqueada por conta própria

A reivindicação de tarefas usa bloqueio de arquivo para evitar condições de corrida quando múltiplos companheiros de equipe tentam reivindicar a mesma tarefa simultaneamente.

Encerrar companheiros de equipe

Para encerrar graciosamente a sessão de um companheiro de equipe, refira-se a ele pelo nome. Por exemplo, com um companheiro de equipe chamado pesquisador:

Ask the researcher teammate to shut down

O líder envia uma solicitação de encerramento. O companheiro de equipe pode aprovar, saindo graciosamente, ou rejeitar com uma explicação. Os diretórios compartilhados da equipe são limpos automaticamente quando a sessão termina, portanto não há uma etapa de limpeza separada. Veja Architecture para saber quais diretórios são removidos e quais persistem para sessões retomadas.

Aplicar gates de qualidade com hooks

Use hooks para aplicar regras quando os companheiros de equipe terminam o trabalho ou as tarefas são criadas ou concluídas:

TeammateIdle: é executado quando um companheiro de equipe está prestes a ficar ocioso. Saia com código 2 para enviar feedback e manter o companheiro de equipe trabalhando.
TaskCreated: é executado quando uma tarefa está sendo criada. Saia com código 2 para evitar criação e enviar feedback.
TaskCompleted: é executado quando uma tarefa está sendo marcada como concluída. Saia com código 2 para evitar conclusão e enviar feedback.

Como funcionam as equipes de agentes

Esta seção cobre a arquitetura e a mecânica por trás das equipes de agentes. Se você quiser começar a usá-las, veja Controle sua equipe de agentes acima.

Como Claude inicia equipes de agentes

Uma equipe de agentes se forma quando o primeiro companheiro de equipe é gerado, com a sessão principal atuando como líder. Existem duas maneiras pelas quais os companheiros de equipe são gerados:

Você solicita companheiros de equipe: dê ao Claude uma tarefa que se beneficie do trabalho paralelo e peça explicitamente por companheiros de equipe. Claude os gera com base em suas instruções.
Claude propõe companheiros de equipe: se Claude determinar que sua tarefa se beneficiaria do trabalho paralelo, pode sugerir gerar companheiros de equipe. Você confirma antes que ele proceda.

Em ambos os casos, você permanece no controle. Claude não gerará companheiros de equipe sem sua aprovação.

Arquitetura

Uma equipe de agentes consiste em:

Componente	Papel
Team lead	A sessão Claude Code principal que gera companheiros de equipe e coordena o trabalho
Teammates	Instâncias Claude Code separadas que cada uma trabalha em tarefas atribuídas
Task list	Lista compartilhada de itens de trabalho que os companheiros de equipe reivindicam e completam
Mailbox	Sistema de mensagens para comunicação entre agentes

Veja Escolha um modo de exibição para opções de configuração de exibição. As mensagens dos companheiros de equipe chegam ao líder automaticamente. O sistema gerencia dependências de tarefas automaticamente. Quando um companheiro de equipe completa uma tarefa da qual outras tarefas dependem, as tarefas bloqueadas são desbloqueadas sem intervenção manual. Equipes e tarefas são armazenadas localmente sob um nome derivado da sessão. O nome é session- seguido pelos primeiros oito caracteres do ID da sessão:

Team config: ~/.claude/teams/{team-name}/config.json
Task list: ~/.claude/tasks/{team-name}/

Claude Code gera ambas automaticamente na inicialização da sessão e as atualiza conforme os companheiros de equipe entram, ficam ociosos ou saem. O diretório de configuração da equipe é removido quando a sessão termina. O diretório da lista de tarefas persiste localmente e nunca é carregado, portanto as sessões retomadas mantêm suas tarefas. A retenção é governada pelo mesmo cleanupPeriodDays que você já controla para transcrições de sessão. A configuração da equipe contém estado de tempo de execução, como IDs de sessão e IDs de painel tmux, portanto não a edite manualmente ou a crie previamente: suas alterações são sobrescritas na próxima atualização de estado. Para definir papéis de companheiros de equipe reutilizáveis, use definições de subagent em vez disso. A configuração da equipe contém um array members com o nome de cada companheiro de equipe, ID do agente e tipo de agente. Os companheiros de equipe podem ler este arquivo para descobrir outros membros da equipe. Não há equivalente em nível de projeto da configuração da equipe. Um arquivo como .claude/teams/teams.json no seu diretório de projeto não é reconhecido como configuração; Claude o trata como um arquivo ordinário.

Use subagent definitions for teammates

Ao gerar um companheiro de equipe, você pode referenciar um tipo de subagent de qualquer escopo de subagent: projeto, usuário, plugin ou definido por CLI. Isso permite que você defina um papel uma vez, como um revisor de segurança ou executor de testes, e o reutilize tanto como um subagent delegado quanto como um companheiro de equipe de equipe de agentes. Para usar uma definição de subagent, mencione-a pelo nome ao pedir ao Claude para gerar o companheiro de equipe:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

O companheiro de equipe honra a lista de permissão tools dessa definição e model, e o corpo da definição é anexado ao prompt do sistema do companheiro de equipe como instruções adicionais em vez de substituí-lo. Ferramentas de coordenação de equipe como SendMessage e as ferramentas de gerenciamento de tarefas estão sempre disponíveis para um companheiro de equipe, mesmo quando tools restringe outras ferramentas.

Os campos frontmatter skills e mcpServers em uma definição de subagent não são aplicados quando essa definição é executada como um companheiro de equipe. Os companheiros de equipe carregam skills e MCP servers de suas configurações de projeto e usuário, assim como uma sessão regular.

Permissões

Os companheiros de equipe começam com as configurações de permissão do líder. Se o líder for executado com --dangerously-skip-permissions, todos os companheiros de equipe também. Após gerar, você pode alterar modos de companheiros de equipe individuais, mas não pode definir modos por companheiro de equipe no tempo de geração. Quando um agente envia uma mensagem para outro sobre SendMessage, o agente receptor é informado de que veio de outra sessão Claude, não de você. Um companheiro de equipe não pode aprovar um prompt de permissão ou fornecer consentimento em seu nome, e um companheiro de equipe que foi negado uma ação não pode retransmiti-la para outro companheiro de equipe para contornar a verificação. Em modo automático, o classificador trata uma reivindicação de aprovação retransmitida de outro agente como entrada não confiável em vez de confirmação de você. Os prompts de permissão de companheiros de equipe aparecem na sessão líder, portanto aprove-os lá você mesmo.

Context e comunicação

Cada companheiro de equipe tem sua própria context window. Quando gerado, um companheiro de equipe carrega o mesmo contexto de projeto que uma sessão regular: CLAUDE.md, MCP servers e skills. Ele também recebe o prompt de geração do líder. O histórico de conversa do líder não é transferido. Como os companheiros de equipe compartilham informações:

Entrega automática de mensagens: quando os companheiros de equipe enviam mensagens, elas são entregues automaticamente aos destinatários. O líder não precisa fazer polling para atualizações.
Notificações de ociosidade: quando um companheiro de equipe termina e para, ele notifica automaticamente o líder.
Lista de tarefas compartilhada: todos os agentes podem ver o status da tarefa e reivindicar trabalho disponível.
Mensagens de companheiros de equipe: envie uma mensagem para um companheiro de equipe específico pelo nome. Para alcançar todos, envie uma mensagem por destinatário.

O líder atribui a cada companheiro de equipe um nome quando o gera, e qualquer companheiro de equipe pode enviar mensagens para qualquer outro por esse nome. Para obter nomes previsíveis que você possa referenciar em prompts posteriores, diga ao líder como chamar cada companheiro de equipe em sua instrução de geração.

Uso de tokens

Equipes de agentes usam significativamente mais tokens do que uma única sessão. Cada companheiro de equipe tem sua própria context window, e o uso de tokens escala com o número de companheiros de equipe ativos. Para pesquisa, revisão e trabalho de novos recursos, os tokens extras geralmente valem a pena. Para tarefas rotineiras, uma única sessão é mais econômica. Veja custos de token de equipe de agentes para orientação de uso.

Exemplos de casos de uso

Estes exemplos mostram como as equipes de agentes lidam com tarefas onde a exploração paralela adiciona valor.

Executar uma revisão de código paralela

Um único revisor tende a gravitar em torno de um tipo de problema por vez. Dividir critérios de revisão em domínios independentes significa que segurança, desempenho e cobertura de testes recebem atenção completa simultaneamente. O prompt atribui a cada companheiro de equipe uma lente distinta para que não se sobreponham:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Cada revisor trabalha a partir do mesmo PR, mas aplica um filtro diferente. O líder sintetiza descobertas em todos os três após terminarem.

Investigar com hipóteses concorrentes

Quando a causa raiz é incerta, um único agente tende a encontrar uma explicação plausível e parar de procurar. O prompt combate isso tornando os companheiros de equipe explicitamente adversários: o trabalho de cada um não é apenas investigar sua própria teoria, mas desafiar as dos outros.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

A estrutura de debate é o mecanismo-chave aqui. A investigação sequencial sofre de ancoragem: uma vez que uma teoria é explorada, a investigação subsequente é enviesada em relação a ela. Com múltiplos investigadores independentes tentando ativamente desprovar uns aos outros, a teoria que sobrevive é muito mais provável de ser a causa raiz real.

Melhores práticas

Dê aos companheiros de equipe contexto suficiente

Os companheiros de equipe carregam contexto de projeto automaticamente, incluindo CLAUDE.md, MCP servers e skills, mas não herdam o histórico de conversa do líder. Veja Context e comunicação para detalhes. Inclua detalhes específicos da tarefa no prompt de geração:

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

Escolha um tamanho de equipe apropriado

Não há limite rígido no número de companheiros de equipe, mas restrições práticas se aplicam:

Custos de token escalam linearmente: cada companheiro de equipe tem sua própria context window e consome tokens independentemente. Veja custos de token de equipe de agentes para detalhes.
Sobrecarga de coordenação aumenta: mais companheiros de equipe significa mais comunicação, coordenação de tarefas e potencial para conflitos
Retornos decrescentes: além de um certo ponto, companheiros de equipe adicionais não aceleram o trabalho proporcionalmente

Comece com 3-5 companheiros de equipe para a maioria dos fluxos de trabalho. Isso equilibra o trabalho paralelo com coordenação gerenciável. Os exemplos neste guia usam 3-5 companheiros de equipe porque esse intervalo funciona bem em diferentes tipos de tarefas. Ter 5-6 tasks por companheiro de equipe mantém todos produtivos sem alternância de contexto excessiva. Se você tiver 15 tarefas independentes, 3 companheiros de equipe é um bom ponto de partida. Escale apenas quando o trabalho genuinamente se beneficiar de ter companheiros de equipe trabalhando simultaneamente. Três companheiros de equipe focados frequentemente superam cinco dispersos.

Dimensione tarefas apropriadamente

Muito pequeno: sobrecarga de coordenação excede o benefício
Muito grande: companheiros de equipe trabalham muito tempo sem check-ins, aumentando o risco de esforço desperdiçado
Bem dimensionado: unidades auto-contidas que produzem um entregável claro, como uma função, um arquivo de teste ou uma revisão

O líder divide o trabalho em tarefas e as atribui aos companheiros de equipe automaticamente. Se não estiver criando tarefas suficientes, peça a ele para dividir o trabalho em pedaços menores. Ter 5-6 tarefas por companheiro de equipe mantém todos produtivos e permite que o líder reatribua trabalho se alguém ficar preso.

Espere os companheiros de equipe terminarem

Às vezes, o líder começa a implementar tarefas em vez de esperar pelos companheiros de equipe. Se você notar isso:

Wait for your teammates to complete their tasks before proceeding

Comece com pesquisa e revisão

Se você é novo em equipes de agentes, comece com tarefas que têm limites claros e não requerem escrever código: revisar um PR, pesquisar uma biblioteca ou investigar um bug. Essas tarefas mostram o valor da exploração paralela sem os desafios de coordenação que vêm com a implementação paralela.

Evite conflitos de arquivo

Dois companheiros de equipe editando o mesmo arquivo leva a sobrescrita. Divida o trabalho para que cada companheiro de equipe possua um conjunto diferente de arquivos.

Monitore e direcione

Verifique o progresso dos companheiros de equipe, redirecione abordagens que não estão funcionando e sintetize descobertas conforme chegam. Deixar uma equipe executar sem supervisão por muito tempo aumenta o risco de esforço desperdiçado.

Troubleshooting

Companheiros de equipe não aparecem

Se os companheiros de equipe não aparecerem depois que você pedir ao Claude para criar uma equipe:

No modo in-process, os companheiros de equipe aparecem no painel de agentes abaixo da entrada de prompt. Use as teclas de seta para cima e para baixo para selecionar um e pressione Enter para visualizá-lo.
Uma linha de companheiro de equipe que desapareceu após ficar inativa foi ocultada, não interrompida. As linhas inativas se ocultam após 30 segundos e reaparecem na próxima vez do companheiro de equipe. Envie uma mensagem ao companheiro de equipe pelo nome para trazê-lo de volta.
Verifique se a tarefa que você deu ao Claude era complexa o suficiente para justificar uma equipe. Claude decide se deve gerar companheiros de equipe com base na tarefa.
Se você explicitamente solicitou split panes, certifique-se de que tmux está instalado e disponível no seu PATH:
```
which tmux
```
Para iTerm2, verifique se o CLI it2 está instalado e a API Python está ativada nas preferências do iTerm2.

Muitos prompts de permissão

Solicitações de permissão de companheiros de equipe surgem para o líder, o que pode criar atrito. Pré-aprove operações comuns nas suas configurações de permissão antes de gerar companheiros de equipe para reduzir interrupções.

Companheiros de equipe parando em erros

Os companheiros de equipe podem parar após encontrar erros em vez de se recuperar. Verifique sua saída selecionando o companheiro de equipe no painel de agentes e pressionando Enter no modo in-process, ou clicando no painel no modo split, depois:

Dê a eles instruções adicionais diretamente
Gere um companheiro de equipe de substituição para continuar o trabalho

Líder encerra antes do trabalho estar pronto

O líder pode decidir que a equipe terminou antes de todas as tarefas estarem realmente completas. Se isso acontecer, diga a ele para continuar. Você também pode dizer ao líder para esperar os companheiros de equipe terminarem antes de prosseguir se ele começar a fazer trabalho em vez de delegar.

Sessões tmux órfãs

Se uma sessão tmux persistir após a equipe terminar, pode não ter sido totalmente limpa. Liste as sessões e mate a criada pela equipe:

tmux ls
tmux kill-session -t <session-name>

Limitações

Equipes de agentes são experimentais. Limitações atuais a serem observadas:

Sem retomada de sessão com companheiros de equipe in-process: /resume e /rewind não restauram companheiros de equipe in-process. Após retomar uma sessão, o líder pode tentar enviar mensagens para companheiros de equipe que não existem mais. Se isso acontecer, diga ao líder para gerar novos companheiros de equipe.
Status da tarefa pode ficar atrasado: os companheiros de equipe às vezes falham em marcar tarefas como concluídas, o que bloqueia tarefas dependentes. Se uma tarefa parecer presa, verifique se o trabalho está realmente pronto e atualize o status da tarefa manualmente ou diga ao líder para dar um empurrão ao companheiro de equipe.
Encerramento pode ser lento: os companheiros de equipe terminam sua solicitação atual ou chamada de ferramenta antes de encerrar, o que pode levar tempo.
Uma equipe por sessão: uma sessão tem exatamente uma equipe, com escopo para essa sessão. Você não pode criar equipes nomeadas adicionais ou compartilhar uma equipe entre sessões.
Sem equipes aninhadas: os companheiros de equipe não podem gerar seus próprios companheiros de equipe. Apenas o líder pode gerenciar a equipe.
Líder é fixo: a sessão principal é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.
Permissões definidas no tempo de geração: todos os companheiros de equipe começam com o modo de permissão do líder. Você pode alterar modos de companheiros de equipe individuais após gerar, mas não pode definir modos por companheiro de equipe no tempo de geração.
Split panes requerem tmux ou iTerm2: o modo in-process padrão funciona em qualquer terminal. O modo split-pane não é suportado no terminal integrado do VS Code, Windows Terminal ou Ghostty.

CLAUDE.md funciona normalmente: os companheiros de equipe leem arquivos CLAUDE.md de seu diretório de trabalho. Use isso para fornecer orientação específica do projeto a todos os companheiros de equipe.

Próximos passos

Explore abordagens relacionadas para trabalho paralelo e delegação:

Delegação leve: subagents geram agentes auxiliares para pesquisa ou verificação dentro de sua sessão, melhor para tarefas que não precisam de coordenação entre agentes
Sessões paralelas manuais: Git worktrees permitem que você execute múltiplas sessões Claude Code você mesmo sem coordenação de equipe automatizada
Comparar abordagens: veja a comparação subagent vs agent team para um detalhamento lado a lado

​Quando usar equipes de agentes

​Comparar com subagents

​Ativar equipes de agentes

​Inicie sua primeira equipe de agentes

​Controle sua equipe de agentes

​Escolha um modo de exibição

​Especifique companheiros de equipe e modelos

​Exigir aprovação de plano para companheiros de equipe

​Fale com companheiros de equipe diretamente

​Atribuir e reivindicar tarefas

​Encerrar companheiros de equipe

​Aplicar gates de qualidade com hooks

​Como funcionam as equipes de agentes

​Como Claude inicia equipes de agentes

​Arquitetura

​Use subagent definitions for teammates

​Permissões

​Context e comunicação

​Uso de tokens

​Exemplos de casos de uso

​Executar uma revisão de código paralela

​Investigar com hipóteses concorrentes

​Melhores práticas

​Dê aos companheiros de equipe contexto suficiente

​Escolha um tamanho de equipe apropriado

​Dimensione tarefas apropriadamente

​Espere os companheiros de equipe terminarem

​Comece com pesquisa e revisão

​Evite conflitos de arquivo

​Monitore e direcione

​Troubleshooting

​Companheiros de equipe não aparecem

​Muitos prompts de permissão

​Companheiros de equipe parando em erros

​Líder encerra antes do trabalho estar pronto

​Sessões tmux órfãs

​Limitações

​Próximos passos

Quando usar equipes de agentes

Comparar com subagents

Ativar equipes de agentes

Inicie sua primeira equipe de agentes

Controle sua equipe de agentes

Escolha um modo de exibição

Especifique companheiros de equipe e modelos

Exigir aprovação de plano para companheiros de equipe

Fale com companheiros de equipe diretamente

Atribuir e reivindicar tarefas

Encerrar companheiros de equipe

Aplicar gates de qualidade com hooks

Como funcionam as equipes de agentes

Como Claude inicia equipes de agentes

Arquitetura

Use subagent definitions for teammates

Permissões

Context e comunicação

Uso de tokens

Exemplos de casos de uso

Executar uma revisão de código paralela

Investigar com hipóteses concorrentes

Melhores práticas

Dê aos companheiros de equipe contexto suficiente

Escolha um tamanho de equipe apropriado

Dimensione tarefas apropriadamente

Espere os companheiros de equipe terminarem

Comece com pesquisa e revisão

Evite conflitos de arquivo

Monitore e direcione

Troubleshooting

Companheiros de equipe não aparecem

Muitos prompts de permissão

Companheiros de equipe parando em erros

Líder encerra antes do trabalho estar pronto

Sessões tmux órfãs

Limitações

Próximos passos