Git worktree para agentes de IA em paralelo

Desenvolvimento paralelo com git worktree é a forma mais limpa de tocar vários trabalhos em um mesmo repositório sem misturá-los. Com agentes de IA isso importa ainda mais: se dois agentes trabalham na mesma pasta, um sobrescreve as mudanças do outro, os testes rodam em código pela metade e ninguém sabe dizer qual mudança é de quem.

Este post explica o que são git worktrees, como usá-los com agentes e como manter cada turno de agente reversível.

O que é um git worktree?

Um git worktree abre uma branch diferente do mesmo repositório em uma pasta separada, ao mesmo tempo. Cada pasta tem seus próprios arquivos de trabalho, mas os dados do .git são compartilhados. Um commit feito em um worktree fica visível nos outros na hora.

Comparado com um clone:

Comandos básicos

Crie um worktree em uma branch nova:

git worktree add ../acme-web-auth -b auth-refactor

Abra um worktree a partir de uma branch existente:

git worktree add ../acme-web-billing billing-v2

Liste e remova worktrees:

git worktree list
git worktree remove ../acme-web-auth
git worktree prune

O prune limpa os registros de worktrees cujas pastas foram apagadas na mão.

Desenvolvimento paralelo com git worktree: uma árvore por agente

A regra para agentes em paralelo é simples: dê a cada agente com risco de conflito o seu próprio worktree.

Um exemplo de organização:

O Testador compartilha o worktree do Arquiteto porque testa a mudança do Arquiteto e trabalha só em tests/. O agente de frontend trabalha em algo totalmente diferente, na própria branch.

O que você ganha com isso:

• Os agentes nunca veem os arquivos pela metade uns dos outros.
• Cada trabalho entra pela própria branch e pelo próprio pull request.
• Descartar um trabalho é tão fácil quanto apagar a branch dele.

Gerenciando worktrees no AgentVera

Dá para gerenciar worktrees pela linha de comando, mas fica difícil acompanhar conforme os agentes se multiplicam. No AgentVera, a aba Worktrees do painel direito permite:

1. Criar um worktree a partir de uma branch nova ou existente.
2. Ver, para cada worktree, o número de mudanças, quanto ele está à frente ou atrás da branch principal e o último commit.
3. Iniciar um agente direto em um worktree.
4. Travar, fazer prune, forçar a remoção de um worktree e apagar a branch dele.

Ao criar um agente novo, você também pode escolher um worktree como espaço de trabalho, e o painel do agente mostra a branch em uma pequena etiqueta. Os arquivos Markdown que os agentes alteram nos worktrees aparecem no painel Specs como planos e documentos.

Mantenha cada turno reversível

Os worktrees separam os agentes entre si. Mas e se um agente seguir pelo caminho errado dentro do próprio worktree?

A resposta tradicional é fazer commit com frequência, mas fazer commit a cada passo do agente polui o histórico. Os turnos do AgentVera seguem outro caminho:

• No início de cada turno, um snapshot da pasta de trabalho vai para uma ref oculta do git.
• Sua branch, o index e o stash não são tocados.
• Os últimos 60 turnos são guardados por agente.
• Em Turns, no menu Options do painel, você vê os arquivos que um turno alterou.
• Undo this turn reverte as mudanças daquele turno, e você também pode desfazer o desfazer.

Assim você pode deixar o agente experimentar à vontade: se não gostar do resultado, está a um clique do estado anterior.

Antes do merge

Antes de levar o trabalho pronto das branches paralelas para a branch principal:

• Rode os testes em cada worktree.
• Revise os diffs; a revisão de código automática acelera isso.
• Organize as mensagens de commit. O painel Git do AgentVera pode escrever uma mensagem no estilo do seu repositório a partir do diff em stage, com o Claude Haiku.
• Faça push da branch e abra um pull request; o cartão do GitHub no painel Git mostra o pull request da branch atual ou abre um novo.

Erros comuns

• Abrir a mesma branch em dois worktrees. O git não deixa, e isso é uma proteção.
• Deixar registros de pastas apagadas. Limpe com git worktree prune.
• Esquecer o node_modules. Cada worktree precisa das próprias dependências instaladas.
• Tratar turnos de agente como commits. Turnos servem para desfazer; continue fazendo commit para ter um histórico duradouro.

Um dia de exemplo: três agentes, duas branches

Vamos deixar isso concreto com um dia de trabalho.

Manhã: preparação

A pasta principal está com main. Há dois trabalhos: uma reestruturação da autenticação e uma página de configurações. Você abre dois worktrees:

git worktree add ../acme-web-auth -b auth-refactor
git worktree add ../acme-web-settings -b settings-ui

Instale as dependências em cada um:

cd ../acme-web-auth && pnpm install
cd ../acme-web-settings && pnpm install

Arquiteto e Testador começam no worktree auth-refactor; o agente de frontend começa em settings-ui.

Meio-dia: um turno dá errado

Enquanto edita a página de configurações, o agente de frontend também muda o estilo de um componente compartilhado. Isso está fora do escopo. Na lista Turns você vê os arquivos que o último turno alterou, desfaz o turno e diz ao agente para não mexer no componente compartilhado. O histórico da branch continua limpo, porque desfazer não é um commit; é uma volta ao snapshot na ref oculta.

Noite: merge

Quando o trabalho de autenticação termina, você roda os testes, confere a revisão e faz push da branch. Se a página de configurações não estiver pronta, o worktree dela continua aberto e o agente segue na mesma pasta no dia seguinte. Quando você fecha e reabre o app, o AgentVera traz os agentes Claude e Codex de volta para a mesma conversa a partir do histórico da CLI.

Detalhes de ambiente para ficar de olho nos worktrees

Os tropeços mais comuns com worktrees em paralelo têm a ver com o ambiente, não com o código:

• Conflito de portas: se você roda um servidor de desenvolvimento em dois worktrees ao mesmo tempo, não deixe os dois pedirem a mesma porta. Defina portas diferentes por variáveis de ambiente.
• Arquivos env: arquivos que não estão no git, como o .env, não aparecem sozinhos em um worktree novo; copie-os.
• Banco de dados: se duas branches têm migrations diferentes, compartilhar um único banco local pode dar problema.

O painel Ports do AgentVera mostra as portas em escuta e qual agente iniciou cada uma, para você saber qual worktree abriu qual servidor.

Copiando um agente e bifurcando a conversa

Às vezes você quer tentar resolver o mesmo problema de dois jeitos. Ao copiar um agente no AgentVera, a ferramenta, a conta, o modelo, o esforço, o papel, o grupo e o worktree dele são copiados exatamente, e você também pode bifurcar o histórico da conversa (--fork-session no Claude, fork no Codex).

Junto com os worktrees, isso dá uma ótima configuração para experimentos: rode dois agentes bifurcados da mesma conversa em dois worktrees, compare os resultados e faça merge da branch de que gostar. Apagar a outra branch limpa o experimento sem deixar rastro.

Checklist

• Cada agente com risco de conflito tem o próprio worktree?
• As dependências estão instaladas em cada worktree?
• Os papéis dos agentes dizem em quais pastas eles trabalham?
• Os testes e uma revisão foram feitos antes do merge?

Conclusão

O desenvolvimento paralelo com git worktree mantém os agentes fisicamente separados, e os turnos mantêm reversíveis as mudanças de cada agente. Juntos, são a base para trabalhar com segurança com vários agentes.

O AgentVera reúne worktrees, turnos e o painel Git em uma única janela. Leia junto com agentes de código em paralelo ou comece no plano gratuito.