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 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.