Worktrees são fáceis de criar e fáceis de esquecer. Você cria um para que um agente trabalhe em uma branch de forma isolada, o agente termina, você revisa o diff, e aí o diretório simplesmente fica lá, parado. Uma semana depois, git worktree list rola para fora da tela, du -sh no repositório acusa doze gigabytes, e três desses diretórios apontam para branches que foram mescladas e excluídas dias atrás. Ninguém escolheu mantê-los. Eles se acumularam porque criar era um comando e limpar era uma tarefa chata.
Essa é a parte do trabalho com agentes em paralelo sobre a qual ninguém te avisa. A primitiva de isolamento está bem documentada; nosso guia sobre git worktrees para agentes de codificação com IA aborda em profundidade a mecânica de criação e ramificação. O ciclo de vida depois do “pronto” é onde mora a dor, e ela piora rápido quando quem cria os worktrees é um agente capaz de abrir cinco em um minuto e sem nenhum instinto de arrumar a bagunça. Este artigo trata dessa segunda metade: a disciplina de limpeza, os comandos exatos, o modo de falha à espreita em cada etapa e o ponto em que um script feito à mão deixa de ser suficiente.
O Sharkly é uma resposta para o problema do “quem faz a limpeza”: ele executa cada Task em seu próprio worktree e trata esse worktree como parte do ciclo de vida da Task, em vez de um diretório que você precisa lembrar de gerenciar. Chegaremos lá. Primeiro, a mecânica, porque você precisa entender a versão manual antes de decidir parar de fazê-la à mão.
TL;DR
Um git worktree é um segundo diretório de trabalho vinculado a um único repositório, com sua própria branch, index e HEAD. Os agentes fazem com que eles se acumulem porque cada execução quer isolamento e nenhuma delas limpa o que deixou para trás. A trilha de limpeza tem quatro comandos: git worktree list para ver o que existe, git worktree remove para excluir um já finalizado, git worktree prune para limpar metadados obsoletos e git worktree lock para proteger um que você queira manter. Cada um tem um modo de falha que deixa diretórios órfãos, trabalho perdido ou branches travadas se você pular uma etapa. A versão manual funciona para um punhado de worktrees. Além disso, vincule cada worktree a um registro de tarefa para que a limpeza tenha um responsável, que é o que o Sharkly faz automaticamente.
Por que os worktrees se acumulam mais rápido com agentes
Um worktree tem um ciclo de vida que uma pessoa gerencia naturalmente: você o cria, trabalha, faz o merge, exclui. A etapa de exclusão depende de um humano se lembrar. Os agentes quebram essa premissa em duas frentes ao mesmo tempo.
Primeiro, o volume. Um desenvolvedor rodando quatro agentes em paralelo cria quatro worktrees por hora, não um por dia. Nosso artigo sobre executar vários agentes do Claude Code em paralelo explica por que essa contagem sobe tão rápido. Segundo, a ausência de instinto de limpeza. Um agente lê a tarefa, faz o trabalho, escreve o resultado e para. Ele não pensa “a branch foi mesclada, então esse diretório agora é peso morto”. Assim, os diretórios sobrevivem à própria utilidade, e os sobreviventes são o problema: checkouts obsoletos de branches excluídas, experimentos inacabados que o agente abandonou e árvores duplicadas de node_modules consumindo disco em cada um deles.
O custo não é abstrato. Cada worktree é um checkout completo mais tudo o que o agente instalou nele. Dez worktrees em um repositório JavaScript de porte médio são dez diretórios node_modules. O disco enche, o git status fica mais lento em todo o conjunto, e a próxima pessoa que rodar git worktree list não consegue distinguir quais diretórios são trabalho ativo e quais são entulho.
A trilha de limpeza, passo a passo
Aqui está todo o ciclo de vida em quatro comandos. Execute-os nesta ordem e os modos de falha ficam sob controle.
Veja o que existe. Comece toda rodada de limpeza por aqui:
git worktree list
# /repo a1b2c3d [main]
# /repo-auth-refactor 4d5e6f7 [auth-refactor]
# /repo-fix-logging 8g9h0i1 [fix-logging]
O modo de falha se você pular esta etapa: você exclui o diretório errado. Dois agentes em branches com nomes parecidos geram caminhos de worktree com nomes parecidos, e remover o que está ativo custa o trabalho não commitado. Leia a lista antes de mexer em qualquer coisa.
Remova um já finalizado. Depois que a branch de um worktree for mesclada e você tiver confirmado que não há nada pendente nele:
git worktree remove /repo-fix-logging
O modo de falha: o remove se recusa a agir se o worktree tiver alterações não commitadas ou arquivos não rastreados, o que é o padrão seguro. A jogada insegura é recorrer a --force para fazer o erro desaparecer. O --force em um worktree com alterações pendentes exclui trabalho real que um agente produziu mas nunca commitou. Se o remove reclamar, vá olhar o diretório primeiro; a reclamação geralmente está certa.
Faça o prune dos metadados obsoletos. Se um diretório de worktree foi excluído com rm -rf em vez de git worktree remove, o git ainda guarda um registro administrativo dele. Esse é o órfão clássico:
git worktree prune
git worktree prune --dry-run # preview first
O modo de falha: pular o prune deixa entradas fantasmas no git worktree list e, pior, o git pode se recusar a reutilizar uma branch que ele acha que ainda está com checkout em algum lugar. O prune limpa a contabilidade. Rode --dry-run primeiro para ver o que ele vai descartar antes de descartar. A documentação do git worktree detalha exatamente o que o prune considera obsoleto.
Bloqueie os que você quer manter. Um worktree em um drive externo lento, ou um que guarda um experimento de longa duração, não deve ser removido pelo prune de um script de limpeza agressivo:
git worktree lock /repo-experiment --reason "release repro, keep until 2.0 ships"
O modo de falha: sem um lock, uma rotina noturna de limpeza que faz prune de tudo que considera “obsoleto” pode remover um worktree que você deixou de lado de propósito. O lock mais uma string de motivo é a diferença entre um script de limpeza em que você confia e um que você desativa depois que ele engole algo importante.
Onde o script de limpeza deixa de escalar
Você pode automatizar todas as quatro etapas. Um cron job que lista os worktrees, verifica cada branch em relação ao histórico de merges e remove as que foram mescladas são trinta linhas de shell. Funciona, e para um desenvolvedor solo rodando alguns agentes é o suficiente. Use o script quando a quantidade de worktrees for pequena e uma única pessoa for dona do repositório.
Ele deixa de escalar por causa do julgamento, não da vazão. Um script consegue identificar que uma branch foi mesclada. Ele não consegue identificar que um worktree contém trabalho não commitado de um agente que você ainda não revisou, nem que uma branch “obsoleta” na verdade é uma tarefa pausada que alguém pretende retomar. No momento em que a limpeza exige saber a intenção por trás de um worktree, uma regra que só enxerga o estado do git vai acabar excluindo algo que importava. O outro limite é a coordenação: em uma máquina compartilhada, o script de limpeza de uma pessoa não sabe o que os agentes de outra estão fazendo, e a pergunta “é seguro remover isto?” deixa de ter resposta apenas com o git worktree list. Para saber mais sobre esse problema da máquina compartilhada, veja nossa seleção de ferramentas para gerenciar agentes de codificação com IA em paralelo.
O que um quadro de tarefas acrescenta
A solução é dar a cada worktree um responsável que sobrevive à sessão de shell. Vincule cada worktree a um registro de tarefa, e a limpeza deixa de ser “quais diretórios parecem obsoletos” e passa a ser “quais tarefas estão concluídas e revisadas”.
É nessa camada que o Sharkly atua. Você já tem agentes de codificação; o Sharkly os transforma em uma equipe ao fazer de cada execução uma Task. Quando uma Task começa, o serviço local no Computador conectado prepara um worktree isolado para ela. Quando o resultado da Task volta para revisão e uma pessoa o aceita, o ciclo de vida do worktree termina junto com a Task, em vez de ficar por aí como um diretório que ninguém lembra. A pergunta sobre a limpeza tem resposta porque o worktree nunca foi anônimo.
A divisão de trabalho continua honesta. Os agentes pegam tarefas, trabalham em worktrees isolados, rodam testes e devolvem o diff. As pessoas definem a direção e decidem a etapa de merge e release. O Sharkly não substitui o Claude Code, o Codex nem os comandos git acima; ele adiciona o registro compartilhado para que isolamento, progresso, resultados e limpeza permaneçam visíveis da solicitação até o release, em vez de se espalharem por vários terminais. Se você roda um agente e a limpeza manual leva dez segundos, você ainda não precisa disso. Quando a lista de worktrees rola para fora da tela, o problema de gestão passa a ser o problema de verdade, e nossa nota sobre manter humanos no loop entre execuções de agentes cobre o lado da revisão.
A checklist que você pode executar hoje
Faça essa rodada em qualquer repositório onde agentes estiveram trabalhando:
git worktree liste leia tudo com atenção antes de remover qualquer coisa.- Para cada worktree finalizado: confirme que a branch foi mesclada, verifique se o diretório está limpo e então rode
git worktree remove(nunca--forceem uma árvore com alterações pendentes). git worktree prune --dry-run, revise, e entãogit worktree prunepara limpar metadados órfãos.git worktree lockem qualquer worktree que você esteja mantendo de propósito, com uma string de motivo.- Confira o disco:
du -shem todo o conjunto de worktrees e exclua instalações duplicadas de dependências das árvores mortas. - Se você faz isso mais de uma vez por dia, pare de criar scripts de limpeza e dê a cada worktree um responsável de Task.
Você pode manter os quatro comandos e executá-los à mão, ou rodar seus agentes de codificação atuais pelo Sharkly para que o worktree seja criado, rastreado e aposentado junto com a Task à qual pertence.
