Agentes de código em paralelo com git worktrees

Rode dois agentes de código no mesmo checkout e você vai descobrir rapidinho por que times de software usam branches. Um agente está renomeando um módulo enquanto o outro roda a suíte de testes contra metade dessa renomeação. Um coloca no stage arquivos que o outro acabou de apagar. Nenhum dos dois está errado; eles só estão dividindo a mesma mesa.

O SuperDevSpace roda um manager e vários workers no mesmo repositório ao mesmo tempo. Este post explica o mecanismo que os mantém separados — as git worktrees — e as regras exatas que o app segue em torno delas.

O que é uma git worktree

Um repositório git normalmente tem um único diretório de trabalho. O git worktree permite que um mesmo repositório tenha vários, cada um num branch próprio, todos compartilhando o mesmo banco de objetos. Não há um segundo clone nem uma segunda cópia do histórico: uma worktree nova custa os arquivos de um checkout e nada mais.

Dá para testar à mão em qualquer repositório. Os comandos são os mesmos em todo lugar; só o shell muda:

git worktree add -b agent/frontend-demo ../myrepo-frontend
git worktree list
cd ../myrepo-frontend && git status
cd - && git worktree remove ../myrepo-frontend

git worktree add -b agent/frontend-demo ..\myrepo-frontend
git worktree list
cd ..\myrepo-frontend; git status
cd ..\myrepo; git worktree remove ..\myrepo-frontend

Cada worktree tem o próprio HEAD, o próprio índice e os próprios arquivos. Dois processos podem editar, buildar e testar em duas worktrees ao mesmo tempo sem ver as mudanças pela metade um do outro. É exatamente a propriedade de que um time de agentes precisa.

Como o SuperDevSpace as usa

As regras são simples e iguais para toda organização:

• O manager trabalha no seu checkout principal. Ele planeja, revisa e faz merge; é o único lugar onde os branches se encontram.
• Cada worker ganha a própria worktree no próprio branch. Quando o manager contrata um worker, o app roda git worktree add -b <branch> <caminho> para ele. O branch se chama agent/<nome-do-worker>-<marca>, a menos que você tenha dado um nome a ele.
• As worktrees ficam na pasta de dados do app, em worktrees/<organização>/<worker>, nunca dentro do seu repositório. Sua pasta de projeto não se enche de diretórios de agentes.
• Todo turno vira commit. Quando um worker termina um turno, o app faz commit de tudo o que mudou na worktree dele (agent(<nome>): turn). Nada do que um worker fez fica só num diretório de trabalho sem commit.
• O merge é um squash merge. Quando o manager aceita o relatório de um worker, o branch entra na sua linha com git merge --squash e um único commit. Se o merge der conflito, o app o aborta e deixa o repositório limpo para a próxima operação, em vez de te deixar no meio de um merge conflitante.
• Uma operação git por vez por repositório. Os diretórios das worktrees isolam os arquivos; uma fila por repositório serializa os próprios comandos git, então dois workers que terminam no mesmo instante nunca disputam os metadados do git.

O diagrama em texto

gitGraph
  commit id: "main"
  branch agent/frontend
  commit id: "frontend: turno 1"
  checkout main
  branch agent/qa
  commit id: "qa: turno 1"
  checkout agent/frontend
  commit id: "frontend: turno 2"
  checkout main
  merge agent/frontend id: "squash: frontend"
  merge agent/qa id: "squash: qa"

No quadro, isso aparece como várias tarefas em andamento ao mesmo tempo, cada uma de um worker diferente, cada uma com o próprio branch por baixo.

O que torna isso prático

Uma worktree recém-criada só contém o que o git rastreia. Isso geralmente não basta para rodar um projeto: node_modules, um .env local, arquivos gerados. Dois detalhes resolvem.

Um script de setup por repositório

Se o seu repositório tem .super/scripts/setup-worktree.sh, o app o executa dentro de cada worktree nova antes de o worker começar, com SUPERDEV_MAIN_REPO apontando para o seu checkout principal. A saída aparece ao vivo — uma instalação longa não é uma espera às cegas — e você pode cancelar.

#!/usr/bin/env bash
set -euo pipefail
# Copiar arquivos só locais do checkout principal
cp "$SUPERDEV_MAIN_REPO/.env" .env 2>/dev/null || true
# Instalar dependências (o pnpm cria links a partir de um store compartilhado, então é rápido)
pnpm install --frozen-lockfile

Submódulos

O git worktree add deixa os submódulos vazios. Se a worktree nova tem um arquivo .gitmodules, o app roda git submodule update --init --recursive nela, para que nenhum worker builde contra uma dependência que sumiu sem aviso.

Limpando sem perder trabalho

As worktrees se acumulam. O app as recupera, mas com cautela:

O diagrama em texto

flowchart TD
  start["O worker terminou"] --> clean{"Árvore de trabalho limpa?"}
  clean -->|"não"| keep["A worktree fica"]
  clean -->|"sim"| merged{"Branch mesclado na sua linha?"}
  merged -->|"não"| keep
  merged -->|"sim"| remove["A worktree é removida"]

Uma worktree com mudanças sem commit, ou com um branch que tem trabalho ainda fora da sua linha, fica onde está. Uma pasta apagada pode ser recriada; trabalho perdido, não. A mesma cautela vale para os branches: o app acompanha os branches que criou e só mexe neles.

O que muda para você

Com cada worker no próprio branch, "rodar quatro agentes de uma vez" deixa de ser uma aposta. Você pode:

• dar ao manager uma diretiva que se divide em tarefas independentes e deixar os workers rodarem em paralelo;
• ler o diff de qualquer worker isoladamente, ao lado da conversa que o produziu;
• rejeitar a mudança de um worker sem atrapalhar os outros;
• continuar usando o seu checkout principal enquanto o time trabalha.

É a mesma disciplina que um time humano usa, aplicada a agentes que não conseguem avisar que estão prestes a pisar no pé um do outro. Se você está se perguntando por que construímos um app inteiro em volta disso, o primeiro post conta essa história.

Experimente

O teste de 14 dias é Premium, sem cartão. Baixe o SuperDevSpace, aponte uma organização nova para um repositório e veja as worktrees aparecerem conforme o manager contrata os primeiros workers.