Isole agentes de IA em paralelo com git worktree

Quem realmente precisa de um worktree por agente

Um agente sozinho no repositório não tem com quem colidir. O diretório de trabalho principal basta, e ativar o isolamento não traz nada.

O isolamento importa quando você roda dois ou mais agentes no mesmo repositório ao mesmo tempo. O Swarm Task Orchestrator do MXterm Pro traz dois presets feitos para isso. "Full Swarm Trio (Lead, QA, Docs)" dispara Claude Code, Codex e OpenCode juntos. "Feature Duo (Dev + Tester)" combina Claude Code com Codex. Os dois ativam o isolamento por worktree por padrão ao serem iniciados.

Você não precisa de um preset. Abra uma nova aba, escolha os agentes e marque você mesmo "Isolar funcionalidades em git worktrees" no Composer. A caixa vem desativada por padrão e só funciona em um repositório git. Os painéis que você dividir depois abrem na pasta do espaço de trabalho, não em um worktree próprio.

Como o MXterm Pro cria um worktree para cada painel de agente

A opção aparece em dois lugares que fazem a mesma coisa: a tela Novo espaço de trabalho ("Isolar funcionalidades em git worktrees") e o diálogo do Swarm Task Orchestrator ("Isolar recursos em Git Worktrees"), que você vê ao disparar um preset. A documentação de agentes e Control Room (antes War Room) descreve a mesma configuração.

Com a opção ligada, cada novo painel de agente ganha um checkout próprio dentro do diretório .worktrees/ do repositório. O branch é gerado na hora e se chama swarm/<adjective>-<noun>, por exemplo swarm/brave-otter. Um painel de terminal comum, sem agente, continua abrindo na raiz do repositório, sem alteração.

O nome é sorteado de um conjunto de cerca de 17.000 combinações, não de uma numeração sequencial, então duas execuções não reaproveitam um worktree antigo por coincidência. Se o nome já estiver em uso, o MXterm tenta de novo com um sufixo numérico (swarm/brave-otter-2, depois -3 e assim por diante), com no máximo cinco nomes no total antes de desistir daquele painel.

Na primeira vez que cria o diretório .worktrees/, o MXterm o adiciona automaticamente ao .gitignore do próprio repositório. Esses checkouts descartáveis nunca aparecem como alterações não rastreadas na sua árvore de trabalho principal.

Se a pasta que você indicou ao MXterm não for um repositório git, o isolamento é ignorado em vez de forçado. Até a 1.0.21, o app rodava git init, git add . e um commit nessas pastas, o que podia levar um .env ou uma chave privada para um histórico que ninguém pediu. Desde a 1.0.22, ele não roda mais git init nelas.

O Composer agora avisa: "Esta pasta não é um repositório git, então os agentes vão compartilhá-la diretamente (sem isolamento de worktree)". Os painéis abrem sem isolamento, na raiz da pasta, e cada um mostra um aviso dispensável com o motivo. Rode git init e faça seu próprio primeiro commit se quiser o isolamento.

Uma exceção: em um repositório existente sem nenhum commit, o Composer de Novo espaço de trabalho e o diálogo do Swarm Task Orchestrator criam um .gitkeep vazio e fazem commit só desse arquivo, como "Initial commit", antes de criar os worktrees (os outros arquivos que já estão na pasta não entram no stage), porque um worktree precisa de um commit como ponto de partida.

O cabeçalho de cada painel mostra o nome do branch do worktree em um selo pequeno. Dá para saber em que branch um agente está sem abrir o painel do git.

A criação é serial, de propósito. Chamadas simultâneas de git worktree add no mesmo repositório disputam o arquivo de lock do git, e uma falha passageira tiraria o isolamento de um painel. Se não for possível criar um worktree (erro de lock do git, falta de espaço em disco ou qualquer outra causa, depois de repetidas as tentativas por conflito de nome), só aquele painel volta para a raiz do repositório e registra um aviso. O resto do espaço de trabalho abre normalmente.

O que o isolamento evita (e o que não evita)

Veja o caso concreto: ao disparar o "Feature Duo", o Claude Code fica em um branch e um worktree próprios, e o Codex em outro.

Sem isolamento, os dois agentes dividiriam um único diretório de trabalho. Se o Codex rodar git checkout ou git stash no meio de uma tarefa, os arquivos que o Claude Code tem abertos em disco mudam debaixo dele. Nenhum dos agentes sabe, na próxima chamada de ferramenta, por que o arquivo que acabou de gravar não bate com o que lê de volta.

Com worktrees separados, cada agente tem a própria cópia de todos os arquivos, em um checkout do próprio branch. Isso reduz a chance de o checkout de um agente reescrever os arquivos que outro tem abertos.

O isolamento não elimina todo tipo de conflito. Dois agentes que editam a mesma funcionalidade por ângulos diferentes ainda podem gerar branches que exigem depois um merge de verdade, revisado por uma pessoa, e o MXterm não automatiza essa parte. O que o isolamento remove é mais estreito e puramente mecânico: a briga no nível do sistema de arquivos por um diretório de trabalho compartilhado.

Um worktree não é um sandbox. O painel continua sendo um shell normal, então um agente pode sair da pasta dele e rodar qualquer comando que o seu usuário rodaria. Além disso, todos os worktrees compartilham o mesmo .git do repositório. O isolamento separa os arquivos dos agentes, mas não limita o que eles podem fazer.

Adicionar, fazer merge e remover worktrees durante a sessão

O isolamento não se decide só na criação do espaço de trabalho. Um agente pode abrir no meio da sessão um novo painel de trabalho isolado para uma subtarefa delegada, com a ferramenta worktree.spawn. Isso só funciona em um espaço de trabalho criado com o isolamento por worktree ligado,.

O merge continua manual, de propósito. Quando o branch de um agente estiver pronto, faça o merge do jeito normal: git merge swarm/brave-otter a partir do worktree principal, ou faça push e abra um pull request, o que sua equipe já usa. O trabalho do MXterm termina em criar e, depois, limpar o worktree. Ele não decide o que acontece com o código que está lá dentro.

A remoção é conservadora de propósito, e há dois caminhos separados: um para o agente e outro para você, pela interface. Um agente só pode remover um worktree sem nenhuma alteração não commitada. Caso contrário, ele recusa de vez, sem opção de forçar.

Limpar pela interface funciona de outro jeito. "Limpar worktrees…" fica ao lado da lista de worktrees do painel Git. Ele remove as entradas obsoletas (worktrees cujo diretório sumiu) sem pedir confirmação e, em seguida, abre um diálogo.

No diálogo, os worktrees com arquivos não commitados aparecem listados por branch, com o número de arquivos de cada um. Eles vêm desmarcados por padrão, então você marca cada um que quer remover. Os worktrees sem nada não commitado aparecem só como uma contagem e são removidos quando você confirma.

O diálogo só conta commits à frente do upstream de um branch, e os branches que o MXterm cria não têm upstream, então para eles a contagem é zero. Confira você mesmo os commits de um branch antes de confirmar, porque a remoção apaga o branch com git branch -D.

Nenhum dos dois caminhos roda sozinho. Fechar um painel, um espaço de trabalho ou o app inteiro nunca apaga um worktree por conta própria. A limpeza só acontece quando você, ou um agente dentro dos próprios limites rígidos, a faz de propósito.

Uma restrição para saber de antemão: o diretório de um worktree nunca é renomeado depois de criado, porque o estado de sessão de um agente está preso a esse caminho absoluto. Você pode renomear à vontade o branch git dentro dele, mas não a pasta.

Free vs Pro: o que realmente tem limite

O isolamento por worktree não é um recurso exclusivo do Pro. Ele funciona do mesmo jeito nos dois planos.

O que tem limite é o tamanho de uma Control Room. Por padrão, o plano Free não tem limite de painéis, mas limita qualquer Control Room (agentes agrupados para compartilhar contexto entre agentes) a 2 membros. Os outros limites do Free, 5 hosts SSH salvos e 1 Máquina salva, não têm relação com worktrees. O plano Pro remove esses limites.

O preset "Feature Duo" (2 agentes, 2 worktrees) cabe com folga no limite de 2 membros da Control Room do Free. O "Full Swarm Trio" tem três agentes, então uma Control Room com os três exige o Pro.

Git worktree vs. iTerm2, Warp, Termius e MobaXterm

A alternativa gratuita à automação do MXterm não é outro app. É um git worktree por agente de IA montado à mão, com os comandos git worktree add e git worktree remove no terminal que você já usa. Isso funciona bem para um ou dois agentes.

O que o MXterm Pro tira da sua mão é a parte burocrática que cresce junto com o número de agentes: escolher um nome de branch único, criar o worktree, apontar o diretório de trabalho do painel para ele e se recusar a apagar por engano um worktree com trabalho não commitado.

O iTerm2 é um emulador de terminal para macOS excelente e muito programável. Como outros terminais comuns, ele não cria worktrees git para você. Seguir esse fluxo ali significa digitar git worktree add à mão para cada painel e depois lembrar de rodar git worktree remove e apagar o branch por conta própria.

O Warp também coloca um agente de IA em primeiro plano no terminal. Ele consegue rodar vários agentes ao mesmo tempo em abas ou painéis separados, e o próprio guia multiagente dele recomenda um git worktree por agente (veja MXterm Pro vs Warp). A proposta do MXterm Pro é mais estreita: com o isolamento ligado, ele mesmo cria o branch e o worktree de cada painel de agente.