Git worktree para agentes em paralelo, sem colisão

Pedro Nauck
22 nov 20267 min de leitura
#git-worktree#agentes-em-paralelo

Dois agentes de código no mesmo diretório vão, mais cedo ou mais tarde, escrever no mesmo arquivo. O git worktree evita essa colisão dando a cada agente uma pasta e uma branch próprias, sem clonar o repositório de novo. Ele resolve só uma parte do problema: porta, dependências, .env e banco continuam compartilhados, e é neles que as execuções em paralelo costumam quebrar.

O que é um git worktree e como criar um?

Segundo a documentação do git, um repositório pode ter vários working trees, o que permite manter mais de uma branch com checkout ao mesmo tempo. Todos compartilham o histórico, e cada um tem o seu HEAD, o seu índice e os seus arquivos. No worktree secundário, o .git é um arquivo de uma linha que aponta para uma pasta dentro do .git do repositório principal. Como explica o Augusto Galego, é como ter dois clones do repositório sem o segundo clone, e sem o stash ou o commit pela metade que a troca de branch exige.

Esquema do git worktree: um histórico compartilhado e três pastas de trabalho independentes, cada uma com a própria branch.
Um git worktree dá a cada agente pasta e branch próprias, com o mesmo histórico.

bash
git worktree add -b agent/auth ../app-auth
git worktree add -b agent/api ../app-api
git worktree list
text
/home/dev/app       f6c2e9a [main]
/home/dev/app-api   f6c2e9a [agent/api]
/home/dev/app-auth  f6c2e9a [agent/auth]

A sintaxe é git worktree add -b <nova-branch> <caminho> [<commit>]. Sem o commit, a branch nasce do HEAD atual. O caminho fica fora do repositório (../app-auth) para a pasta não aparecer como conteúdo não rastreado.

O git também impede que duas pastas usem a mesma branch. Na versão 2.56, git worktree add ../outra agent/auth termina em fatal: 'agent/auth' is already used by worktree at .... Para um orquestrador, isso é uma trava de graça: dois workers não conseguem pegar a mesma branch por engano.

Para limpar, o ciclo é este:

bash
git worktree remove ../app-auth      # recusa se houver arquivo modificado ou não rastreado
git worktree remove --force ../app-auth
git worktree prune                   # esquece worktrees cuja pasta foi apagada na mão
git worktree add --detach ../app-teste HEAD   # experimento descartável, sem branch

Arquivos ignorados pelo .gitignore, como node_modules, não impedem o remove. Se alguém apagar a pasta com rm -rf, o git worktree list marca a entrada como prunable até o prune rodar. A branch continua existindo depois do remove, e apagá-la é um passo separado (git branch -d).

Como o orquestrador entrega um worktree para cada worker?

No padrão orchestrator-workers da Anthropic, descrito em Workflow ou agente? Os cinco padrões da Anthropic, um orquestrador divide a tarefa, delega para workers e junta os resultados. Quando os workers escrevem código, o worktree torna essa delegação segura: o orquestrador cria agent/<tarefa> a partir da main, aponta o worker para a pasta e é o único que integra. A analogia com container ajuda até certo ponto, porque o worktree isola só os arquivos rastreados de cada agente.

As ferramentas de agente já embalam esse fluxo, e os nomes abaixo são exemplos datados. Em vídeos de fevereiro de 2026, Matt Pocock e o canal Better Stack mostraram o flag claude --worktree <nome> do Claude Code. O Better Stack e o texto Loop Engineering, de Addy Osmani, citam também o campo isolation: worktree no frontmatter de um subagente, que dá a cada ajudante um checkout próprio. Flags mudam entre versões, então confira na sua.

No teste, Matt Pocock notou que, sem um nome de branch explícito no push, o agente enviaria o trabalho para a branch de onde o worktree saiu, no caso a main. Em git puro dá para reproduzir esse efeito. Uma branch criada a partir de origin/main passa a acompanhar origin/main. Num repositório de teste com git 2.56 e push.default=upstream, um git push dentro de agent/api enviou os commits para a main remota. Com o padrão simple, o git recusa o push, porque o nome da branch local não bate com o da remota. O remédio tem duas partes:

bash
git worktree add --no-track -b agent/api ../app-api origin/main
# no fim do trabalho do worker:
git push -u origin HEAD

O --no-track impede o vínculo com a main, e o push -u origin HEAD cria no remoto uma branch com o nome da local. Proteger a main no remoto fecha o resto da porta.

Porta, node_modules, .env e banco: o que o worktree não isola?

O git só faz checkout de arquivos rastreados. Tudo o que o .gitignore esconde (node_modules, .env, bancos locais) não aparece no worktree novo. E o que é da máquina, como as portas e o servidor de banco, nunca esteve no repositório.

Dois workers em worktrees separados isolam os arquivos, mas ainda disputam a mesma porta e o mesmo banco de dados.
O worktree isola arquivos; porta e banco continuam compartilhados.

RecursoDentro do worktreeO que fazer
Arquivos rastreadosisoladonada
node_modulesausenteinstalar na criação
.envausentecopiar e sobrescrever porta e banco
Portacompartilhadauma por worktree
Banco de dadoscompartilhadoum por worktree

As fontes convergem nesses pontos. Indy Dev Dan, em maio de 2025, descreve um prompt de setup que cria o worktree, copia o .env, instala as dependências e muda a porta no config do Vite. Cole Medin, em abril de 2026, lista conflito de porta e instalação de dependências entre os problemas de rodar agentes com validação de ponta a ponta em paralelo, e trata o banco à parte. Ele instala os node_modules antes de o agente começar e deriva a porta do nome do worktree a partir de uma base 4000.

A função abaixo junta essas peças. Um orquestrador a chamaria uma vez por tarefa:

ts
import { execFileSync } from "node:child_process";
import { createHash } from "node:crypto";
import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { basename, resolve } from "node:path";

function portFor(task: string, taken: Set<number>, base = 4000, range = 1000): number {
  const hash = createHash("sha1").update(task).digest().readUInt16BE(0);
  for (let i = 0; i < range; i++) {
    const port = base + ((hash + i) % range);
    if (!taken.has(port)) return port;
  }
  throw new Error("nenhuma porta livre no intervalo");
}

export function createWorkspace(repo: string, task: string, taken: Set<number>) {
  const run = (cwd: string, cmd: string, ...args: string[]) =>
    execFileSync(cmd, args, { cwd, stdio: "inherit" });
  const branch = `agent/${task}`;
  const path = resolve(repo, "..", `${basename(repo)}-${task}`);
  const database = `app_${task.replace(/\W/g, "_")}`;

  run(repo, "git", "fetch", "origin", "main");
  run(repo, "git", "worktree", "add", "--no-track", "-b", branch, path, "origin/main");

  const envFile = resolve(repo, ".env");
  const lines = existsSync(envFile) ? readFileSync(envFile, "utf8").split("\n") : [];
  const env = lines.filter(l => l !== "" && !/^(PORT|DATABASE_URL)=/.test(l));
  const port = portFor(task, taken);
  taken.add(port);
  env.push(`PORT=${port}`, `DATABASE_URL=postgres://localhost/${database}`);
  writeFileSync(resolve(path, ".env"), env.join("\n") + "\n");

  run(path, "npm", "install");
  return { path, branch, port, database };
}

A porta vem de um hash do nome da tarefa, e o conjunto taken, mantido pelo orquestrador, resolve a colisão de dois nomes com o mesmo hash. Como o worktree nasce sem .env, a função copia o do repositório principal sem PORT e DATABASE_URL, que são reescritas. Sem esse filtro, todos os agentes herdam a DATABASE_URL do desenvolvimento e escrevem no mesmo banco.

O banco é o ponto mais caro de descobrir tarde. Cole Medin observa que, se implementações diferentes mexem no banco, elas quebram umas às outras quando apontam para o mesmo, e propõe algo como um worktree para o banco: branching de banco, num serviço que ofereça isso, ou um SQLite local por worktree. Em PostgreSQL puro, dá para clonar um banco usando-o como template:

sql
CREATE DATABASE app_agent_auth TEMPLATE app_molde;
-- ao remover o worktree:
DROP DATABASE app_agent_auth;

A documentação do PostgreSQL avisa que nenhuma outra sessão pode estar conectada ao banco de origem durante a cópia, e que o CREATE DATABASE falha se houver alguma conexão quando ele começa. Por isso o template é um banco molde que nenhuma aplicação usa, e não o banco de desenvolvimento em que o seu servidor está conectado. Mesmo com um banco por worktree, duas migrations criadas por agentes diferentes só se encontram na hora do merge.

Esses comandos de setup o agente não adivinha. O lugar deles é o README do projeto, como mostra o post sobre README e rules para LLM.

Como o best-of-N usa o mesmo mecanismo?

Até aqui cada worktree recebe uma tarefa diferente. No best-of-N, todos recebem a mesma. Indy Dev Dan argumenta que, como os LLMs são não determinísticos, rodar vários agentes sobre o mesmo plano gera versões diferentes do código e permite escolher a melhor, e avisa que a técnica não é barata. Em código, o uso típico é gerar N implementações, rodar a suíte de testes e ficar com a que passa.

bash
for i in 1 2 3; do
  git worktree add --no-track -b try/ui-$i ../app-ui-$i origin/main
done

# o mesmo plano roda em cada pasta; depois a mesma suíte de testes avalia as três
git merge --no-ff try/ui-2
git worktree remove ../app-ui-2 && git branch -d try/ui-2
for i in 1 3; do
  git worktree remove --force ../app-ui-$i
  git branch -D try/ui-$i
done

O critério de escolha precisa ser verificável: com testes, a seleção é mecânica; com "qual parece melhor", o gargalo volta para você. Cole Medin acrescenta que quem revisa não deve ser a mesma sessão que escreveu, nem enxergar a conversa dela, porque quem acabou de fazer o trabalho tende a aprovar o próprio resultado. Um revisor em contexto limpo pega o que o autor deixou passar.

Quantos agentes em paralelo você consegue revisar?

O limite está fora da ferramenta. Addy Osmani escreve, em Loop Engineering, que o worktree remove a colisão mecânica, mas a banda de revisão de quem lê e aprova decide quantos agentes dá para rodar.

O paralelismo não compensa em alguns casos:

  • As tarefas mexem nos mesmos arquivos. O worktree só adia o conflito para o merge.
  • Uma tarefa depende do resultado da outra, o que pede execução em sequência.
  • O projeto não tem testes, e cada candidato exige revisão manual completa.
  • O custo de tokens já pesa. Cole Medin sugere modelos menores em etapas que pedem pouco raciocínio, como análise de código e pesquisa.

Se você passa muito tempo corrigindo o que os agentes entregam, Cole Medin trata isso como sinal para acrescentar validação automática. É o mesmo princípio de outras partes do ciclo de agentes, como a avaliação por tarefa, trial e grader: o que sustenta a escala é uma checagem que não depende da sua atenção.

Quem quiser aprofundar esse tipo de orquestração e de avaliação de agentes encontra o tema na Formação em Inteligência Artificial.

Referências

Saiba mais

Formação em Inteligência Artificial

Aprenda tudo, desde a criação de um processo de desenvolvimento, passando pela construção de aplicações até a automação de processos, tudo com inteligência artificial, do início ao fim.

// Artigos relacionados

Continue lendo.

  1. Inteligência Artificial21 nov 2026 8 min

    Accessibility tree ou screenshot para agentes de IA

    Accessibility tree ou screenshot? Veja as quatro formas de um agente de IA observar uma interface, onde cada uma falha e como combiná-las com um roteador.

  2. Inteligência Artificial21 nov 2026 7 min

    Autocorreção de LLM: o verificador deve ser externo

    Autocorreção de LLM em raciocínio piora a resposta sem feedback externo. Veja o que os papers mediram e como montar um loop gerar-verificar em TypeScript.

  3. Inteligência Artificial20 nov 2026 7 min

    Clustering de texto: embedding e LLM na zona cinzenta

    Clustering de texto com embedding e cosseno, mandando só os pares ambíguos a um classificador LLM, e por que o centróide cria grupos gigantes.

Cookies e privacidade

Utilizamos cookies para melhorar sua experiência, analisar o tráfego do site e personalizar conteúdo. Você pode aceitar todos, rejeitar ou personalizar suas preferências.