Executar sessões de Claude Code uma após a outra é um hábito, não uma exigência. Quando suas tarefas são genuinamente independentes, não há motivo para uma ter que esperar pela outra. Git worktrees oferecem a cada sessão de Claude seu próprio diretório verificado em seu próprio branch, todos usando o mesmo armazenamento de objetos .git. Sem clones duplicados, sem conflitos de arquivos, merge git padrão quando você terminar. Este post apresenta o fluxo de trabalho completo: quando usar um worktree, como configurar um, qual isolamento você realmente obtém (e qual não obtém), e como fazer limpeza sem perder trabalho que ainda não foi commitado.
Quando um Worktree Ajuda
Nem toda tarefa justifica um. Resposta honesta: worktrees brilham em uma banda bastante específica de situações.
Um passo a passo no YouTube por bri (junho de 2026) descreve bem. Use um worktree quando você tem duas ou mais tarefas que não compartilham os mesmos arquivos, ou quando uma tarefa é arriscada o suficiente para que você queira ver duas abordagens diferentes antes de se comprometer com qualquer uma. Se uma única tarefa abrange toda a base de código, mantenha-se em uma sessão. O mesmo vale para trabalho exploratório onde você quer que o agente se mova livremente.
O outro bom caso de uso: trabalho especulativo. Configure três worktrees, dê a cada um um prompt ligeiramente diferente para o mesmo problema e escolha a versão que você gosta. Zylos Research observa que esse padrão se tornou comum em equipes executando quatro ou mais sessões de IA concorrentes, precisamente porque você está se protegendo contra saída de modelo não determinística em vez de confiar em uma única passagem.
Por outro lado, se seu projeto envolve um grande monorepo TypeScript com PostgreSQL, Redis, múltiplos pacotes internos e um frontend Remix, worktrees sozinhos não resolverão seus problemas de coordenação. Trigger.dev escreveu sobre exatamente isso e eventualmente migrou para uma abordagem diferente. O isolamento do sistema de arquivos é real. O isolamento de serviço não é automático.
Crie Checkouts de Tarefas Isoladas
Comece em seu branch base e puxe as atualizações mais recentes. Em seguida, adicione .claude/worktrees ao seu .gitignore uma vez:
echo ".claude/worktrees" >> .gitignore
Claude coloca worktrees dentro do diretório do seu repositório por padrão. Sem essa entrada .gitignore, eles aparecem como arquivos não rastreados e poluem seu git status. Adicione-a, faça commit, esqueça.
Agora configure uma sessão por tarefa. Abra dois terminais:
claude --worktree feature-payments
``
claude --worktree bugfix-auth
De acordo com o artigo de Dan Does Code, Claude cria o worktree em .claude/worktrees/feature-payments/, verifica um novo branch e limita a sessão a esse diretório. Sua árvore de trabalho principal fica intocada o tempo todo. Você também pode usar a forma de flag curta claude -w feature-payments se preferir. Pule o nome inteiramente e Claude gera um automaticamente.
Cada sessão agora opera em isolamento completo do sistema de arquivos. O agente no Terminal 1 não pode tocar nos arquivos que o agente no Terminal 2 está trabalhando, porque estão em diretórios diferentes em branches diferentes. Esse é o truque todo. É separação em nível de infraestrutura, não lógica de coordenação entre agentes. (O guia de subagentes do Claude Code cobre o lado da orquestração se for isso que você está procurando em vez disso.)
Dando a Cada Sessão Sua Tarefa
Assim que ambas as sessões estiverem em execução, dê a cada uma suas instruções. Trate cada instância de Claude como um contexto novo. Seja específico quanto ao escopo. Se o Terminal 1 está construindo um recurso de pagamentos, diga quais arquivos tocar e quais deixar em paz. O mesmo para o Terminal 2.
Quando uma sessão termina, peça a Claude para fazer push da branch e abrir um pull request antes de fechar o terminal. Assim o trabalho fica seguro fora da sua máquina local e pronto para revisão.
Gerenciar Dependências, Portas e Configuração Local
É aqui que as coisas ficam delicadas. O isolamento do sistema de arquivos é automático. Tudo o mais requer um pouco de configuração manual.
Portas. Se ambas as worktrees iniciarem um servidor de desenvolvimento, elas colidirão na mesma porta por padrão. A solução é dar a cada worktree seu próprio arquivo .env com uma atribuição de porta diferente. Algo como PORT=3001 em uma e PORT=3002 na outra. Ou passe o override inline na inicialização. Qualquer uma das duas funciona.
Bancos de dados. SQLite é fácil: aponte o .env de cada worktree para um caminho de arquivo diferente. PostgreSQL ou MySQL requer mais reflexão. Você precisa de uma instância de banco de dados separada por worktree, ou no mínimo um schema/banco de dados separado dentro da mesma instância. Configure a string de conexão através de variáveis de ambiente no .env de cada worktree. Não compartilhe um banco de dados entre dois agentes escrevendo migrações simultaneamente. Isso é pedir por corrupção ou race conditions.
Arquivos de configuração local. Se seu projeto usa um arquivo de configuração local que não é commitado (coisas como .env.local, config/local.yml), você precisará criar um por worktree. Eles não herdam da árvore de trabalho principal automaticamente.
O guia da MindStudio sobre agentes de IA em codificação paralela cobre esses padrões de isolamento com mais detalhes. A versão resumida: worktrees oferecem isolamento de branch e diretório por design. Isolamento de banco de dados e porta requerem que você configure explicitamente, antecipadamente.
Mais uma coisa que vale a pena sinalizar aqui. Se você está trabalhando em um projeto com setup de serviço local caro ou complicado e está rodando múltiplas worktrees, considere se o custo de setup vale a aceleração paralela. Para uma biblioteca ou ferramenta CLI, absolutamente. Para um monorepo full-stack com seis serviços, talvez menos. Se você quer ajuda para escopear isso, um desenvolvedor Claude Code pode avaliar se worktrees ou uma estratégia paralela diferente se encaixa na sua stack.
Revisar e Integrar Ambas as Branches
Ambos os agentes terminaram. Ambas as branches foram feitas push. Agora você revisa.
O workflow aqui é git padrão. A configuração paralela não muda o processo de merge. Uma sequência numerada para um repositório típico com duas tarefas:
- Faça checkout de
maine puxe o mais recente. - Revise a primeira branch.
git diff main..feature-paymentsoferece uma visão completa do que mudou. - Se você está satisfeito com isso, faça merge ou rebase em
main. Resolva quaisquer conflitos com a branch base do jeito usual. - Puxe
mainnovamente para obter essas mudanças. - Revise a segunda branch.
git diff main..bugfix-auth. - Faça merge. Se os dois agentes tocaram em arquivos sobrepostos (o que não deveria acontecer se você escopou as tarefas corretamente, mas às vezes acontece), resolva conflitos aqui.
- Execute sua suite de testes contra
mainuma vez que ambos os merges estejam dentro.
A vantagem de revisar sequencialmente assim, em vez de fazer merge de ambas simultaneamente, é que conflitos de um merge não se compõem no próximo. Diffs mais simples, raciocínio mais fácil.
Limpar Sem Perder Trabalho Não Commitado
Limpeza é onde desenvolvedores ficam nervosos. E se houver trabalho em uma worktree que nunca foi commitado?
A resposta: faça stash disso antes de remover a worktree.
Se você tem mudanças não commitadas numa worktree que quer preservar, navegue para o diretório dessa worktree e execute:
git stash push -m "wip: payments feature - pre-cleanup"
Esse stash vive no object store .git compartilhado, o que significa que é acessível da sua working tree principal ou de qualquer outra worktree após a worktree original ser removida. Depois que fez stash, você pode deletar com segurança:
git worktree remove .claude/worktrees/feature-payments
Então, de volta na sua working tree principal, faça pop do stash:
git stash pop
Se o experimento falhou completamente e você não quer nada dele, apenas delete sem fazer stash. git worktree remove com a flag --force remove a worktree mesmo que tenha mudanças não commitadas. Tenha certeza antes de usar --force. Não há caminho de recuperação.
Depois de remover todas as worktrees, faça prune da lista para manter as coisas organizadas:
git worktree prune
Isso remove referências administrativas obsoletas de .git/worktrees/.
Recursos Compartilhados Que Worktrees Não Isolam
Vale ser explícito sobre isso, porque o modelo mental de "isolamento" pode enganá-lo.
O que worktrees isolam:
- O diretório de trabalho e todos os arquivos nele
- O branch em que cada sessão opera
- Mudanças staged e unstaged
O que worktrees não isolam:
- O object store
.git(compartilhado por design) - Memória auto da máquina local (a documentação oficial de memória confirma que worktrees do mesmo repositório compartilham isso)
- Serviços externos: bancos de dados, filas, caches, qualquer dependência em rede
- Credenciais de ambiente e chaves de API a menos que você defina explicitamente valores diferentes por worktree
- Qualquer coisa no seu ambiente shell de nível de SO que ambas as sessões herdam
Isso importa também para segurança. Worktrees não são um limite de tenant. Se ambas as sessões compartilham a mesma chave de API ou credenciais de banco de dados, elas compartilham acesso. Não trate uma worktree como uma forma de isolar uma sessão do Claude de configuração local sensível. Não é isso.
Para orquestrar múltiplos agentes em um fluxo de trabalho mais amplo em vez de apenas isolamento de sistema de arquivos, o post de superpoderes do Claude Code entra nos padrões mais amplos.
FAQ
`claude --worktree` funciona igual a executar `git worktree add` manualmente?
Funcionalmente similar mas não idêntico. claude --worktree faz o git worktree add, cria o branch e limita a sessão do Claude para aquele diretório num único passo. Se você executar git worktree add manualmente e depois iniciar Claude dentro do diretório resultante, você obtém o mesmo resultado de sistema de arquivos mas sem o scoping integrado do Claude. A flag --worktree é o caminho mais rápido para o caso comum.
Posso executar mais de duas worktrees ao mesmo tempo?
Sim. Não há limite rígido imposto por git ou Claude Code no número de worktrees. O limite prático é a RAM e CPU da sua máquina. Cada sessão do Claude é um processo separado com seu próprio contexto. Três ou quatro sessões simultâneas numa máquina dev moderna é tranquilo. Mais que isso e você provavelmente está atingindo limites de recursos antes de atingir qualquer limitação de git.
O que acontece com o branch de uma worktree se eu deletar a worktree?
O branch sobrevive. git worktree remove deleta o diretório de trabalho e a referência administrativa em .git/worktrees/. O branch em si permanece e é acessível a partir da sua árvore de trabalho principal ou de qualquer outra worktree. Você deleta o branch separadamente com git branch -d branch-name quando não precisar mais dele.
As worktrees afetam como Claude lê ou escreve `CLAUDE.md` memória do projeto?
Worktrees no mesmo repositório compartilham memória automática local da máquina de acordo com a documentação oficial de memória. Se você tiver um arquivo CLAUDE.md commitado no repo, cada worktree o lê a partir de sua própria cópia verificada. Edições que um agente faz em CLAUDE.md na sua worktree permanecem isoladas naquele branch até ser feito merge. Mas a camada local da máquina é compartilhada, então instruções escritas lá por uma sessão são visíveis para outra.
Existe custo de performance em executar worktrees versus clones separados?
Worktrees são mais baratas que clones. Elas compartilham o object store do .git, então não há duplicação de todo o histórico do repositório no disco. O custo principal é o diretório de trabalho em si, que é um checkout completo de todos os arquivos rastreados no estado atual do branch. Para repositórios grandes com assets binários ou arquivos gerados, esse tamanho de checkout pode se acumular. Mas as operações git (fetch, log, diff) todas rodam contra um único object store, então são rápidas.
A razão mais clara para preferir worktrees a clones separados: stashes e refs criados em uma worktree são imediatamente acessíveis em todos os outros lugares no mesmo repo. Esse estado compartilhado é exatamente o que torna o fluxo de limpeza acima funcionar.