Como rodar vários agentes do Claude Code ao mesmo tempo

Quatro jeitos de rodar agentes do Claude Code em paralelo

Subagentes: ajudantes em paralelo dentro de uma sessão

Um subagente tem a própria janela de contexto, o próprio system prompt e as próprias ferramentas. Ele não vê a sua conversa, e só o resumo dele volta, o que mantém pequeno o contexto da sessão principal. O Claude Code já vem com alguns nativos, como Explore (somente leitura) e Plan, e você pode criar os seus.

1. Defina um subagente

   Crie um arquivo Markdown em .claude/agents/ (compartilhado com o projeto) ou em ~/.claude/agents/ (só para você). Apenas name e description são obrigatórios; tools limita o que ele pode usar e model escolhe o modelo.

   ---
   name: code-reviewer
   description: Reviews code for quality and best practices
   tools: Read, Glob, Grep
   model: sonnet
   ---
   
   You are a code reviewer. When invoked, analyze the code and give
   specific, actionable feedback on quality, security and best practices.

2. Deixe o Claude rodar vários de uma vez

   Peça o trabalho em paralelo, por exemplo: “revise os módulos de auth, billing e search em paralelo”. Os subagentes que o Claude cria começam em background por padrão, até 20 de cada vez, e informam o resultado quando terminam. Digite /tasks para vê-los.

3. Dê uma worktree própria aos subagentes que editam arquivos

   Adicione isolation: worktree ao frontmatter do subagente ou peça ao Claude que use worktrees para os agentes dele. Cada um passa a editar uma cópia temporária do repositório, que é removida se ele não fizer alterações.

Rode sessões paralelas do Claude Code em git worktrees

1. Ignore a pasta das worktrees

   O Claude Code cria as worktrees em .claude/worktrees/, na raiz do repositório. O repositório precisa ter pelo menos um commit.

   echo ".claude/worktrees/" >> .gitignore

2. Inicie uma sessão por tarefa

   Em cada terminal, rode claude --worktree (ou -w) com um nome diferente. Cada sessão ganha a própria pasta e uma branch chamada worktree-<name>, baseada na branch padrão.

   # terminal 1
   claude --worktree feature-auth
   
   # terminal 2
   claude --worktree bugfix-login

3. Copie os arquivos não versionados de que você precisa

   Uma worktree nova só tem os arquivos versionados. Liste arquivos como .env em um arquivo .worktreeinclude (com a sintaxe do gitignore) e o Claude Code os copia para lá.

   .env
   .env.local

4. Faça o merge e limpe

   Quando uma sessão termina, uma worktree sem alterações é removida junto com a branch; se houver alterações, ele pergunta se deve mantê-la. Faça o merge das branches como faria com qualquer outra. Execuções headless com -p não perguntam, então remova essas worktrees com git worktree remove.

5. Ou use o app desktop

   Pressione Cmd+N (Ctrl+N no Windows) para uma nova sessão e ative Worktree antes de iniciá-la; a opção vem desativada. As sessões podem ficar lado a lado na visualização dividida.

Fonte: documentação da Anthropic sobre worktrees

Sessões em background com --bg e o agent view

claude --bg "<prompt>" inicia uma sessão em background e retorna na hora, então você pode iniciar várias em sequência. Cada uma vai para a própria worktree antes de editar qualquer coisa. claude agents as lista; claude logs <id>, claude attach <id> e claude stop <id> gerenciam uma delas.

Elas continuam rodando depois que você fecha o terminal, mas não depois que o computador desliga. O agent view é um research preview. Para saber mais sobre execuções sem supervisão, veja como rodar agentes do Claude Code em segundo plano.

Agent teams: agentes que conversam entre si

Os agent teams são experimentais e vêm desativados. Ative-os com CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 no seu shell ou no bloco env do settings.json e depois peça ao Claude para “criar três colegas de equipe” para uma tarefa. Os colegas compartilham uma lista de tarefas e trocam mensagens; eles aparecem no terminal ou em painéis divididos com tmux ou iTerm2.

• Só em sessões interativas: -p e o Agent SDK não criam colegas de equipe.
• Um time por sessão, sem times aninhados, e colegas que rodam no mesmo processo não são restaurados pelo /resume.
• Os colegas compartilham um único checkout, então dê a cada um um conjunto diferente de arquivos.
• Eles custam bem mais: a documentação da Anthropic estima que um time gasta cerca de 7 vezes os tokens de uma única sessão quando os colegas rodam em plan mode.

Evite que agentes em paralelo sobrescrevam o trabalho uns dos outros

• Se dois agentes podem mexer nos mesmos arquivos, dê a cada um a própria worktree. Uma sessão em uma worktree não consegue editar o checkout principal, e os subagentes dela também não.
• Em um agent team, divida o trabalho por arquivos: dois colegas editando o mesmo arquivo sobrescrevem um ao outro.
• Todos os subagentes e sessões consomem os mesmos limites de uso, então rodar vários multiplica o consumo. Use model: haiku para subagentes simples.
• Agentes que rodam os mesmos testes ou o mesmo servidor de desenvolvimento podem disputar portas; dê a cada um a sua porta.

Transforme agentes paralelos em um time com cargos

Worktrees e agent teams dividem uma tarefa que você está acompanhando. O Crewmark roda várias sessões do Claude Code ou do Codex como funcionários, cada um com cargo, metas e horário de trabalho próprios, e passa trabalho para eles em um único quadro.

1. Um funcionário por cargo

   Um especialista em SEO, um engenheiro de software e um UI designer vivem cada um na própria conversa, com as próprias instruções e a própria meta.

2. Um quadro para todos eles

   Atribua as tarefas ao funcionário mais adequado. Cada um acorda no ritmo do seu heartbeat, pega a próxima tarefa e comenta enquanto avança, então você vê quem está fazendo o quê.

3. Eles perguntam a você, não uns aos outros

   Quando um funcionário precisa de uma revisão ou de uma permissão, ele manda mensagem para você e segue em frente. Leia o que é um funcionário de IA.

Perguntas sobre vários agentes do Claude Code