Git worktrees: a base para rodar vários agentes de IA sem conflitos

Você dispara dois agentes no mesmo repositório. Um edita o package.json, o outro também. Trinta segundos depois, seu código está num estado que ninguém consegue mesclar.

Isso não é um bug nos seus agentes. É que todos eles trabalham na mesma pasta.

A solução é uma ferramenta que o Git tem há anos e quase ninguém usa: o git worktree.

O problema: 3 agentes, 1 repositório, merge impossível

Um repositório Git normal é uma pasta com um branch ativo por vez. Você trabalha na main, troca de branch e a pasta inteira muda.

Agora jogue três agentes autônomos nessa pasta. Eles escrevem ao mesmo tempo. O agente A cria um arquivo, o agente B roda git checkout para começar do zero e apaga o trabalho em andamento do A. Você acaba com arquivos pela metade, um index bagunçado e conflitos que demoram mais para resolver do que se você tivesse programado tudo na mão.

O paralelismo só economiza tempo se os agentes não se esbarrarem.

O que é um git worktree

Um worktree é uma segunda pasta de trabalho ligada ao mesmo repositório.

Mesmo histórico, mesmo remote, mas cada worktree tem o seu próprio branch ativo e os seus próprios arquivos no disco. Você pode ter cinco lado a lado, cada um num branch diferente, sem que um atrapalhe o outro.

Um único .git, vários espaços de trabalho. É só isso.

Um worktree por agente, na prática

Aqui está a configuração. A partir do seu repositório:

git worktree add ../project-auth -b feature/auth
git worktree add ../project-billing -b feature/billing
git worktree add ../project-export -b feature/export

Você acabou de criar três pastas, cada uma no seu próprio branch. Aí você inicia um agente em cada uma:

cd ../project-auth && claude
cd ../project-billing && codex

Cada agente tem a sua pasta, o seu branch, os seus arquivos. O agente de auth nunca vai ver o que o agente de billing faz. Nenhuma colisão é possível.

Quando uma feature fica pronta, você revisa o branch dela e faz o merge. Depois você limpa:

git worktree remove ../project-auth

A pasta some, o branch continua no seu histórico. Limpinho.

As 3 armadilhas que você precisa conhecer

Primeira armadilha: o arquivo central compartilhado. Se duas features precisam mexer no mesmo routes.ts ou no mesmo schema do banco, os worktrees não te salvam, você vai pegar o conflito na hora do merge. Um agente mexe nos arquivos que todo mundo compartilha, os outros esperam ou contornam.

Segunda: branches que se distanciam. Enquanto seus agentes trabalham, a main segue em frente. Três dias depois seus branches estão atrasados e o merge vira sofrimento. Faça rebase cedo e com frequência, ou mantenha as sessões curtas.

Terceira: limpeza esquecida. Cada worktree é uma pasta de verdade no seu disco. Dez por dia sem limpar e a sua pasta pai vira um caos ilegível. O git worktree list mostra o que está largado por aí, e o git worktree prune remove os mortos.

A quarta armadilha: um worktree começa vazio

Um worktree só contém os arquivos que o Git rastreia. O git worktree add te dá o código-fonte, não o node_modules, não o .venv, não o .env com os seus segredos locais, não o cache de build. Um agente que começa em um worktree novo não consegue rodar os testes, não consegue subir o servidor de desenvolvimento, e muitas vezes não diz por quê: o npm test falha por um módulo que falta, o app falha por uma variável de ambiente ausente, e o agente gasta os primeiros dez minutos com encanamento em vez de cuidar do ticket.

Isso aconteceu com a gente. Um usuário apontou que a opção de worktree do AgentsRoom ficava escondida nas opções avançadas do formulário de agente, e que qualquer agente iniciado em um worktree não tinha nenhuma dependência e não conseguia rodar um único teste. As duas coisas eram verdade. O isolamento existia, mas era inutilizável sem uma etapa manual de que ninguém se lembrava.

Desde a versão 1.194.0, a opção fica em um bloco Isolamento do formulário de agente, visível sem expandir nada, e o primeiro agente iniciado em um worktree novo já o encontra preparado: o AgentsRoom copia da cópia de trabalho principal os arquivos ignorados que correspondem a um padrão (por padrão todos os .env*, sem nunca sobrescrever, nunca dentro de node_modules nem de .git), depois roda o comando de instalação detectado a partir do lockfile (bun, pnpm, yarn, npm, uv, poetry, pipenv, bundle, composer) ou o que você definiu nas configurações do projeto. O comando roda no próprio terminal do agente, então você o vê, e uma instalação que falha não impede o agente de iniciar. Isso acontece uma vez por worktree: um marcador na pasta git privada do worktree faz o próximo lançamento pular essa etapa.

Se você faz isso na mão, a receita é a mesma e cabe em um script: copiar os .env*, rodar a instalação e depois iniciar o agente. Envolva o git worktree add nele, senão você vai esquecer no terceiro agente.

A pergunta de verdade: quem fica de olho nas cinco pastas?

Os worktrees resolvem as colisões de arquivos. Eles não resolvem a sua carga mental.

Você tem cinco pastas, cinco agentes, cinco terminais. Qual deles está esperando a sua revisão? Qual terminou dez minutos atrás enquanto você olhava para outro lugar? Qual travou?

É aí que um worktree por agente bate no limite se você fica preso no terminal. Você resolveu o conflito técnico, mas multiplicou as janelas para vigiar.

O AgentsRoom coloca cada agente num bloco, com o status e a cor dele, não importa em qual worktree ele rode. Um agente que está esperando fica vermelho e te avisa. Leia como rodar de 3 a 8 agentes em paralelo sem se perder para o método completo em cima dos worktrees.

O que levar daqui

Um agente, um worktree, um branch. Essa é a regra básica de quem leva o trabalho multi-agente a sério.

Os comandos cabem em três linhas e o benefício é imediato: seus agentes param de sobrescrever uns aos outros. Adicione uma visão que te diz qual deles precisa de você e dá para segurar cinco frentes em paralelo de verdade, sem perder a cabeça.