Como Executar Múltiplos Agentes do Claude Code em Paralelo

TL;DR: Para executar múltiplos agentes do Claude Code em paralelo, atribua a cada sessão seu próprio git worktree (claude -w <name> faz isso com uma única flag), envie para segundo plano as sessões que você não estiver monitorando com claude --bg e defina a ordem de merge antes que os agentes terminem, já que branches isoladas ainda podem entrar em conflito ao serem integradas. Duas sessões compartilhando o mesmo checkout é a receita para que o commit de um agente acabe levando código incompleto de outro. Este guia foi feito para desenvolvedores que já usam o Claude Code e querem rodar de duas a cinco sessões ao mesmo tempo.

Tudo começa com um segundo terminal. O Claude Code está refatorando o módulo de autenticação no primeiro terminal, então você abre outro e pede a uma nova sessão para corrigir aquele teste intermitente de data. Em seguida, abre um terceiro para a documentação. Vinte minutos depois, três sessões estão escrevendo no mesmo diretório de trabalho, o git status lista arquivos que você nem se lembra de ter pedido e ninguém sabe dizer qual sessão alterou o config.ts.

Executar múltiplos agentes do Claude Code é fácil: basta abrir mais terminais. Já executá-los sem que as sessões corrompam o trabalho umas das outras exige três decisões: onde os arquivos de cada sessão ficam armazenados, como acompanhar as sessões que você não está visualizando e em qual ordem fazer o merge de suas branches. Este artigo aborda esses três pontos usando os comandos nativos do Claude Code e demonstra dois erros que reproduzimos em um repositório de teste. Se worktrees são novidade para você, leia primeiro o nosso guia de git worktrees com agentes de programação por IA ou consulte a documentação do git worktree.

Por que múltiplos agentes do Claude Code quebram um checkout compartilhado

Executar múltiplos agentes do Claude Code em paralelo significa ter duas ou mais sessões trabalhando no mesmo repositório simultaneamente, cada uma com sua própria tarefa e sua própria janela de contexto. As sessões não sabem da existência umas das outras. Cada uma lê arquivos, faz edições, executa testes e cria commits como se estivesse trabalhando sozinha.

Um checkout tem apenas um diretório de trabalho, uma única staging area (index) e um único HEAD; portanto, a premissa de agir "como se estivesse sozinha" falha rapidamente. Reproduzimos a versão mais comum desse problema em um repositório Python simples, usando dois scripts em shell simulando os agentes. O Agente B salvou uma função truncate() incompleta em textutils.py. O Agente A conclui sua respectiva tarefa em um arquivo diferente e faz o commit como muitos prompts o instruem a fazer, via git add -A && git commit:

$ git show --stat --format='%an: %s' HEAD
agent-a: add slugify
 slug.py      | 2 ++
 textutils.py | 4 ++++
 2 files changed, 6 insertions(+)

$ python3 -m pytest -q
1 error in 0.09s

O commit do Agente A inclui a função inacabada do Agente B, e a suíte de testes agora quebra logo no import. Nada foi sobrescrito. O index era compartilhado, então o commit de A absorveu o trabalho em andamento de B, e o histórico agora indica que o Agente A gerou código quebrado. A versão desse problema ocorrendo no mesmo arquivo é detalhada em o que acontece quando dois agentes de programação editam o mesmo arquivo.

Execute múltiplos agentes do Claude Code com uma worktree para cada

A solução é manter um diretório de trabalho por sessão, e o Claude Code já oferece suporte a isso por meio de uma flag:

# interactive sessions, one task each, each in its own worktree
claude -w auth-refactor
claude -w flaky-date-test --tmux   # opens the session in its own tmux or iTerm2 pane

# fire-and-forget work: starts in the background and prints an id
claude --bg "update the README examples for the new config format"

De acordo com a documentação de worktrees, o comando claude -w <name> cria uma worktree em .claude/worktrees/<name>/ em uma nova branch chamada worktree-<name>, e um segundo terminal com um nome diferente recebe uma segunda sessão isolada. Em nossos testes, o git marcou a nova worktree como locked, o que impede que o comando git worktree prune a exclua por baixo de uma sessão ativa. Sessões em segundo plano iniciadas com --bg ou /bg são movidas para sua própria worktree dentro de .claude/worktrees/ antes de editarem qualquer arquivo, conforme detalhado na página do agent view.

Três detalhes de configuração evitam dores de cabeça:

1. Ignore a pasta. As worktrees ficam dentro do repositório, portanto o git status no checkout principal exibirá .claude/ como arquivo não rastreado até que você adicione .claude/worktrees/ ao .gitignore, prática que a documentação também recomenda.
2. Espere um checkout limpo. Uma nova worktree não terá node_modules, virtualenv ou .env. Liste os arquivos ignorados pelo git que precisam ser copiados, como o .env, em um arquivo .worktreeinclude, e planeje uma etapa de instalação de dependências para cada worktree.
3. Faça a limpeza manual de execuções headless. Sessões interativas oferecem a opção de remover sua respectiva worktree ao sair. Já execuções iniciadas com claude -p nunca fazem essa limpeza automaticamente; portanto, remova-as utilizando git worktree unlock seguido de git worktree remove.

Sessões em segundo plano são gerenciadas diretamente pelo terminal. Estas descrições foram extraídas do claude --help na versão 2.1.283:

A flag --bg não pode ser combinada com -p. Para um fluxo de paralelização via scripts, o guia de boas práticas com Claude Code da Anthropic apresenta um loop em shell iterando sobre claude -p com as opções --allowedTools e --permission-mode dontAsk. Combine isso com -w para garantir que cada execução tenha seu próprio diretório.

Agentes isolados do Claude Code ainda colidem na hora do merge

As worktrees impedem que as sessões interfiram umas nas outras enquanto trabalham, mas não garantem que as alterações sejam compatíveis. Aplicamos o mesmo tipo de mudança em duas branches de worktree diferentes, adicionando uma função ao final de textutils.py em cada uma, e então fizemos o merge de ambas:

$ git merge agent/slugify
Fast-forward
$ git merge agent/truncate
Auto-merging textutils.py
CONFLICT (content): Merge conflict in textutils.py
Automatic merge failed; fix conflicts and then commit the result.

Nenhum dos agentes cometeu um erro. Ambos adicionaram código no mesmo local e o git não tem como definir uma ordem sozinho. Em uma base de código real com quatro ou cinco sessões, isso é o comportamento padrão para qualquer arquivo compartilhado: tabelas de rotas, exports em __init__.py, changelogs e lockfiles. A diferença em relação ao checkout compartilhado é que agora o conflito é evidente, visível e atribuível. Três práticas ajudam a minimizar o impacto:

1. Divida as tarefas por arquivo, não por funcionalidade. Duas tarefas que precisam alterar o roteador devem ser tratadas como uma única tarefa, ou executadas em sequência.
2. Faça o merge em uma ordem definida e aplique rebase nas demais. Integre a primeira branch e, em seguida, oriente a próxima sessão a executar um rebase em relação à main e rodar os testes novamente antes do seu code review. A sessão que escreveu o código possui todo o contexto necessário para resolver os próprios conflitos.
3. Nomeie cada worktree de acordo com sua tarefa. claude -w fix-date-test é infinitamente melhor do que claude -w agent2 quando você examinar o git worktree list uma hora depois.

O gargalo real geralmente não é o git, mas sim a capacidade humana de revisar cinco diffs. Nosso artigo sobre por que a revisão humana é o gargalo para agentes paralelos mostra como dimensionar essa fila de forma eficiente.

Subagentes, equipes de agentes ou sessões separadas para múltiplos agentes do Claude Code

O Claude Code agora oferece diversas maneiras de executar tarefas em paralelo, e a visão geral de agentes paralelos lista cada uma lado a lado. Elas não são intercambiáveis, e o critério mais importante é o nível de isolamento:

Para tarefas independentes, utilize sessões separadas com worktrees. Use equipes de agentes quando as partes dependerem umas das outras e os integrantes precisarem alinhar decisões — designando arquivos diferentes para cada membro, já que a página sobre agent teams é enfática: "Dois colaboradores editando o mesmo arquivo causam sobrescritas." Seja qual for a escolha, o consumo de cota é compartilhado. Como a documentação do agent view pontua com clareza: "executar dez agentes em paralelo consome cota aproximadamente dez vezes mais rápido do que executar um só."

Como o Sharkly se encaixa ao rodar múltiplos agentes do Claude Code

Se você executa duas ou três sessões na sua própria máquina e revisa cada diff por conta própria, os comandos mostrados acima são suficientes e você talvez não precise do Sharkly. A equação muda quando as sessões pertencem a mais de uma pessoa, ou quando responder à pergunta "em qual sessão está o ajuste do teste de data?" leva mais tempo do que a correção em si.

Você já conta com agentes de código. O Sharkly os transforma em uma equipe colaborativa. Cada demanda se torna uma Task. Você a atribui a um Agent executado no Claude Code Runtime em um de seus Computers, e definir o Assignee inicia a execução. Com a configuração padrão de diretório de trabalho, Create temporary directory, cada Task ganha seu próprio diretório e execuções vinculadas a repositórios recebem uma git worktree isolada: o mesmo isolamento de claude -w, mas sem precisar nomear worktrees manualmente. Quando um Agent precisa reaproveitar um ambiente já existente em um Computer local, a opção Run in isolated worktrees entrega o resultado de cada Task em sua própria branch agent/<agent>/<task>. A configuração Max concurrency (assigned tasks) no Agent limita quantas execuções ocorrem simultaneamente, tornando explícito para todo o time o limite de capacidade de revisão mencionado anteriormente.

O progresso, o histórico de execução e os resultados retornam para a Task, e qualquer etapa que dependa de intervenção humana é direcionada para a Inbox. Nada sofre merge de forma autônoma: uma pessoa revisa as alterações da worktree, aprova, faz o merge ou descarta o código, marcando a Task como Done. O consumo continua sendo faturado no seu próprio plano do Claude Code, pois o Sharkly não vende tokens. A página de recursos de Agents detalha essa configuração, e o artigo sobre como o Sharkly executa agentes em paralelo aborda o funcionamento prático da execução.

Se você já superou o limite de três terminais abertos e precisa centralizar os resultados de cada sessão do Claude Code em um único local para revisão, esse é exatamente o desafio que o Sharkly resolve.

Perguntas Frequentes (FAQ)

Quantos agentes do Claude Code posso executar ao mesmo tempo? A documentação não impõe um limite estrito para sessões separadas. Para subagentes, o padrão é de até 20 execuções simultâneas, enquanto a página de agent teams sugere começar com 3 a 5 membros. Os limites práticos são a cota do seu plano, o uso de CPU e memória da sua máquina e a quantidade de resultados que você consegue revisar por dia; vale a pena calcular sua capacidade de revisão antes de abrir uma sexta sessão.

Sessões paralelas do Claude Code compartilham os limites de uso? Sim. Nos planos Pro e Max, os limites de uso são compartilhados entre o Claude e o Claude Code, com uma janela móvel de cinco horas e um teto semanal, e todas as sessões paralelas consomem da mesma cota. Se a variável ANTHROPIC_API_KEY estiver configurada, o Claude Code cobrará o consumo diretamente via API.

O comando claude --worktree copia meu .env e minhas dependências? Não. Cada worktree funciona como um checkout novo e limpo. Adicione os arquivos ignorados pelo git necessários (como o .env) ao arquivo .worktreeinclude e execute o comando de instalação de dependências em cada worktree.

Posso executar o Claude Code e o Codex em paralelo no mesmo repositório? Sim, adotando a mesma regra: uma worktree dedicada por sessão e uma ordem bem definida de merge. Nosso guia sobre como rodar Claude Code e Codex juntos na mesma base de código aborda as estratégias de roteamento e fluxo de trabalho.