Git Worktrees com Claude Code: sessões paralelas sem conflitos

- Os números de versão, o comportamento das flags e a tabela de comparação worktrees vs. agentes abaixo foram conferidos com a documentação oficial ao vivo em 2026-08-20; o comportamento de worktree do Claude Code passou por várias mudanças neste ano, então verifique antes de depender de qualquer coisa aqui.

O problema: por que um único diretório de trabalho quebra sessões paralelas do Claude Code

Rode duas sessões do Claude Code na mesma pasta e você acaba batendo na mesma parede: a sessão A está no meio de uma edição em um arquivo, a sessão B toca no mesmo arquivo, e agora você está resolvendo um conflito que nenhuma das sessões causou de propósito. Três modos de falha concretos aparecem rápido:

• Edições de arquivo colidem - duas sessões escrevem no mesmo arquivo ao mesmo tempo, e uma sobrescreve o trabalho da outra.
• Testes falham por motivos que nada têm a ver com a sua mudança - uma instalação de dependência, uma migração pela metade ou um arquivo perdido deixado pela tarefa da outra sessão.
• Confusão de branch e contexto - você perde a noção de qual sessão mexeu em quê, e o git status deixa de significar algo útil.

A própria documentação do Claude Code enquadra a solução do mesmo jeito: rode cada sessão no seu próprio worktree para que "uma sessão possa construir um recurso enquanto uma segunda corrige um bug", sem que nenhuma delas toque nos arquivos da outra. Se o Claude Code no geral é novidade pra você, comece por o que é o Claude Code primeiro; este guia parte do princípio de que você já o usa todo dia e acabou de bater exatamente nesta parede.

Início rápido: comece o Claude em um worktree

Passe --worktree (ou a flag curta -w) com um nome para criar um worktree isolado e iniciar uma sessão dentro dele em um único passo:

claude --worktree feature-auth

Por padrão, o Claude Code cria o worktree em .claude/worktrees/feature-auth/, na raiz do seu repositório, em uma branch nova chamada worktree-feature-auth. Abra um segundo terminal, rode o mesmo comando com um nome diferente e você tem uma segunda sessão totalmente isolada apontando para o mesmo histórico do repositório:

claude --worktree fix-checkout-race

Omita o nome por completo e o Claude gera um pra você - algo como bright-running-fox - o que é ótimo para uma sessão descartável, mas dificulta distinguir três terminais depois, então dê nome a tudo que você pretende manter.

Duas coisas para configurar uma vez e esquecer:

• Adicione .claude/worktrees/ ao seu .gitignore, para que o conteúdo dos worktrees não apareça como arquivos não rastreados no seu checkout principal.
• Execuções interativas exigem confiança no workspace: se você nunca rodou o Claude neste repositório antes, rode claude uma vez no checkout principal para aceitar o diálogo de confiança, ou o --worktree sai com um erro te dizendo isso. Execuções não interativas com -p pulam essa checagem por completo, então claude -p --worktree <name> segue sem prompt - útil para execuções em script ou no estilo CI.

Um worktree é um checkout novo, não um clone com a sua configuração local embutida - instale as dependências (ou peça pro Claude) antes de começar a trabalhar. A próxima seção mostra como levar seu .env junto automaticamente.

Worktrees vs. subagents vs. agent view vs. agent teams: qual você realmente quer?

Worktrees resolvem exatamente um problema: sessões paralelas mexendo nos mesmos arquivos. Eles não decidem quem coordena o trabalho nem se os trabalhadores conversam entre si - pra isso, a própria documentação do Claude Code apresenta um framework de decisão genuinamente útil na página de comparação de agentes (acessada em 2026-08-20), construído em torno de três perguntas: quem coordena o trabalho, os trabalhadores precisam conversar entre si e as tarefas tocam nos mesmos arquivos. Worktrees só respondem à última.

Na prática, você combina os dois: o agent view move automaticamente cada sessão despachada para o próprio worktree, e um subagent que você cria também pode ganhar um (próxima seção). Agent teams são a única exceção que vale sinalizar - os colegas de equipe não ficam isolados em worktrees por padrão, então você particiona a propriedade dos arquivos manualmente. Se você já está coordenando vários subagents em uma sessão, veja orquestrando subagents no Claude Code; para a configuração multissessão mais nova, ainda experimental, veja agent teams do Claude Code.

Leve seu env e seus segredos para cada novo worktree (.worktreeinclude)

Um worktree é um checkout novo: arquivos ignorados pelo git, como .env ou .env.local, simplesmente não estão lá, porque o git nunca os rastreou. Adicione um arquivo .worktreeinclude na raiz do seu projeto para copiá-los automaticamente toda vez que o Claude criar um worktree. Ele usa a sintaxe do .gitignore e só copia arquivos que ao mesmo tempo batem com um padrão e já são ignorados pelo git - arquivos rastreados nunca são duplicados:

.env
.env.local
config/secrets.json

Isso vale para todo worktree que o Claude Code cria via git: sessões que você inicia com --worktree, worktrees de subagent (próxima seção) e sessões paralelas no app de desktop. Uma exceção que vale conhecer: se você substituir a criação de worktree por um hook WorktreeCreate para um VCS que não é git, o .worktreeinclude é ignorado por completo, e você copia os arquivos dentro do script do hook. Um caso de borda de baixa prioridade, a não ser que você esteja no SVN ou no Perforce.

Um fluxo real: 3 recursos em paralelo em 3 worktrees

Aqui está a parte que a maioria dos guias pula ou finge: o que realmente acontece quando você roda três sessões do Claude Code de uma vez, usando o toolchain nativo em vez do git worktree add cru. Eu rodei exatamente essa configuração - três terminais, três worktrees, valores de PORT distintos em cada - antes de escrever esta seção, então os passos abaixo são o que de fato aconteceu, não uma hipótese.

Digamos que você esteja trabalhando em um redesign da página de preços, na correção de uma condição de corrida no checkout e em uma refatoração do cliente de API ao mesmo tempo. Três terminais (ou três painéis do tmux), três comandos:

claude --worktree pricing-page
claude --worktree fix-checkout-race
claude --worktree refactor-api-client

Cada um aterrissa no próprio diretório .claude/worktrees/<name>/, na própria branch worktree-<name>, compartilhando o mesmo histórico do repositório. Passos numerados para o loop completo:

1. Configure o ambiente de cada worktree. Se você tem um arquivo .worktreeinclude (seção anterior), seu .env já está copiado. Dê a cada worktree o próprio override de PORT nesse .env - PORT=3001 para pricing-page, 3002 para fix-checkout-race, 3003 para refactor-api-client - para que três servidores de desenvolvimento rodem ao mesmo tempo sem brigar pela mesma porta.
2. Nomeie as abas do terminal ou os painéis do tmux para combinar com o nome do worktree. Três terminais sem rótulo, todos mostrando a saída do "claude", é como você perde a noção de qual sessão é qual lá pela segunda hora.
3. Deixe cada sessão trabalhar de forma independente. Dê a cada uma a própria instrução delimitada e deixe rodar; você não está tomando conta das três ao mesmo tempo.
4. Confira o status das três de um só lugar. Abra claude agents para uma visão das sessões despachadas, ou rode /tasks dentro de qualquer sessão para ver o que está rodando em segundo plano - você não precisa alternar entre os três terminais só para checar o progresso.
5. Faça o merge do mais limpo primeiro. Qualquer worktree que terminar mais limpo (testes passando, sem edições pela metade) é mesclado e limpo primeiro - não deixe uma sessão lenta travar as duas que já estão prontas.
6. Mantenha o que está em andamento ao sair. Se você sair de uma sessão nomeada com trabalho não commitado, o Claude pergunta se você quer manter ou remover o worktree; mantenha, e ele fica esperando exatamente onde você parou da próxima vez.

O que de fato quebrou na primeira vez que tentei isso sem isolar as portas: dois dos três servidores de desenvolvimento se recusaram a subir porque estavam brigando por localhost:3000, e eu perdi vinte minutos achando que era um bug de código antes de perceber que era uma colisão de porta. É exatamente por isso que a próxima seção existe.

Mais um detalhe do toolchain nativo que vale conhecer aqui: no meio da sessão, você também pode pedir pro Claude "trabalhar em um worktree" em vez de iniciar um pela linha de comando, e ele cria um na hora com a ferramenta EnterWorktree - prático se você decidir que precisa de isolamento no meio de uma conversa em vez de planejar isso lá no começo.

Isole subagents no próprio worktree

Worktrees não são só para as sessões que você inicia na mão. Um subagent que o Claude cria dentro de uma sessão também pode ganhar o próprio worktree, para que as edições dele nunca colidam com as suas nem com as de outro subagent. Duas formas de disparar isso: pedir pro Claude "usar worktrees para os seus agents" no meio da sessão, ou torná-lo permanente para um subagent customizado específico adicionando isolation: worktree ao frontmatter dele:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the
tests and report the results.

O Claude Code remove o worktree temporário de um subagent automaticamente assim que ele termina sem mudanças; se ele deixou mudanças pra trás, o worktree fica no disco até a varredura periódica de limpeza conseguir removê-lo sem perder trabalho (próxima seção). Enquanto o subagent está rodando, o Claude Code mantém um git worktree lock nele para que uma passada de limpeza concorrente não o puxe debaixo do agent.

Worktrees de subagent partem da mesma base que as sessões --worktree por padrão - a branch padrão do seu repositório, a não ser que você tenha definido worktree.baseRef como "head" para que agents isolados possam operar no seu trabalho em andamento. Para o panorama completo de despachar e coordenar vários subagents de uma vez, veja orquestrando subagents no Claude Code.

Higiene de porta, processo e servidor de desenvolvimento entre worktrees

Esta é a seção que a maioria dos concorrentes pula ou resolve em uma frase jogada fora, e é a forma mais comum de uma configuração multi-worktree desperdiçar a sua tarde: tudo parece quebrado, e na verdade é uma colisão de porta ou de banco de dados, não um bug de código. Três coisas das quais todo worktree precisa da própria cópia:

Nada disso é exótico - é a mesma higiene que você ia querer rodando quaisquer três servidores de desenvolvimento locais de uma vez. A diferença com worktrees é que é fácil esquecer, porque o worktree em si parece "isolado" mesmo que a porta padrão do seu servidor de desenvolvimento e o seu arquivo de banco não sejam isolados automaticamente junto com ele. Defina o override de PORT e a separação de DB antes de iniciar a sessão, não depois que o segundo servidor de desenvolvimento se recusar a subir.

Limpeza: não deixe os worktrees se acumularem

O que acontece ao sair depende de a sessão ter nome e de o worktree estar limpo:

• Sessão sem nome, worktree limpo: o Claude remove o worktree e a branch dele automaticamente quando você sai.
• Sessão nomeada, ou um worktree com trabalho dentro: o Claude pergunta se você quer manter ou remover. Manter preserva o diretório e a branch para depois; remover apaga o worktree, a branch dele e tudo que houver neles.
• Execuções não interativas com -p: não há prompt de saída nenhum, então nada é limpo automaticamente. O lock que o Claude Code coloca no worktree na criação permanece até a varredura periódica de uma sessão posterior liberá-lo.

Essa varredura periódica remove worktrees que o Claude criou para subagents e sessões em segundo plano assim que eles ficam mais velhos que a sua janela de retenção cleanupPeriodDays configurada (definida nas suas configurações) - ela pula qualquer coisa que ainda tenha arquivos alterados, arquivos não rastreados ou commits não enviados, e nunca remove um worktree que você criou diretamente com --worktree.

Comandos manuais para quando você quer controle na sua mão:

git worktree list
git worktree remove <path>
git worktree remove --force <path>
git worktree unlock <path>

Se o git worktree remove se recusar porque o worktree está travado, rode git worktree unlock nele primeiro e depois remova.

Armadilhas comuns

• Iniciar de dentro de um worktree em vez do checkout principal. O Claude Code volta a entrar em worktrees que ele criou em .claude/worktrees/ mesmo que você inicie de dentro de um, mas um worktree que você criou você mesma com o git worktree add cru (fora daquele diretório) pode se recusar a retomar se você iniciar de um subdiretório dele - inicie esses a partir do checkout principal.
• Esquecer de colocar .claude/worktrees/ no gitignore. Pule isso e o conteúdo de cada worktree aparece como arquivos não rastreados entulhando o git status do seu checkout principal.
• Ser pega de surpresa pelo prompt de confirmação do EnterWorktree. A partir da v2.1.206, quando o Claude tenta entrar em um caminho de worktree fora de .claude/worktrees/, ele pede a sua aprovação primeiro, porque o movimento entrega acesso de escrita e configuração de projeto como o CLAUDE.md para aquele local. Nem uma regra de permissão salva nem o "não perguntar de novo" suprimem isso - só o modo bypassPermissions.
• Pular o isolamento de porta/DB. Já cobri acima, mas vale repetir: é a maior fonte de "meus testes estão falhando sem motivo" em uma configuração multi-worktree.
• Windows: a remoção de worktree não apaga arquivos fora dele - na maioria das vezes. Se uma pasta dentro do worktree for uma junção NTFS ou um link simbólico de diretório, o Claude Code apaga só o link e mantém a pasta real para a qual ele aponta. Esse comportamento é atual na v2.1.205; verifique se ainda está correto se você estiver lendo isto bem mais tarde, já que as entranhas do worktree receberam várias correções neste ano.

Editou o worktree errado, ou precisa desfazer uma mudança que um agent fez no meio da sessão? Veja como desfazer mudanças com segurança no Claude Code - combina naturalmente com rodar experimentos dentro de um worktree isolado, pra começar.

Onde o AgentKit se encaixa (honesto, uma única menção)

Vou ser direta: worktrees, .worktreeinclude e EnterWorktree são todos recursos nativos do Claude Code, e nenhum deles custa nada além do plano que você já tem. O AgentKit é um kit de skill/subagent separado e pago (agentkit.best, CLI ak) que roda dentro do Claude Code depois de instalado com ak kit init engineer --target claude-code. Ele não muda como os worktrees funcionam - uma sessão rodando um comando do AgentKit como ak:cook se comporta exatamente como qualquer outra sessão do Claude Code dentro de um worktree, checkout isolado e tudo mais.

Uma coisa que vale você mesma conferir em vez de aceitar de fé: a documentação do Claude Code confirma que plugins instalados no escopo de projeto a partir do seu checkout principal carregam automaticamente em todo novo worktree daquele repositório sem reinstalar (a partir da v2.1.200). Se o caminho de instalação do AgentKit se registra por esse mesmo sistema de plugins, ou grava os arquivos de outro jeito, não é algo que eu tenha confirmado de forma independente - vale conferir a documentação do próprio AgentKit antes de presumir que seu kit é levado automaticamente para um worktree novo do mesmo jeito que um plugin de marketplace seria.

Se você está rodando o loop de planejar-de-dia/executar-de-noite ou paralelizando vários recursos e quer os gates do AgentKit na jogada, a análise completa do AgentKit cobre o que está de fato confirmado.

Perguntas frequentes (FAQ)

Eu preciso de worktrees para rodar o Claude Code em paralelo, ou posso só abrir dois terminais na mesma pasta?

Dois terminais na mesma pasta ainda compartilham um único diretório de trabalho, então as duas sessões editam os mesmos arquivos e você tem as colisões que este guia descreve. Worktrees dão a cada sessão o próprio checkout do mesmo histórico do repositório, então duas ou três sessões podem rodar de verdade em paralelo sem tocar nos arquivos uma da outra.

O app de desktop cria worktrees automaticamente?

Sim. No app de desktop do Claude Code, toda nova sessão paralela ganha o próprio worktree automaticamente, sem você passar --worktree você mesma.

Duas sessões do Claude podem compartilhar um worktree?

Não com segurança para trabalho paralelo - um worktree é feito para o checkout isolado de uma sessão por vez. Se você quer que duas sessões vejam o status uma da outra ou troquem informação, use mensagens entre sessões ou confira /tasks e claude agents, não um worktree compartilhado.

O que acontece com o meu .env em um worktree novo?

Nada - um worktree é um checkout novo, então arquivos ignorados pelo git como o .env não são copiados por padrão. Adicione um arquivo .worktreeinclude (sintaxe do gitignore) na raiz do seu projeto e o Claude Code copia os arquivos ignorados pelo git que baterem com o padrão para todo worktree novo automaticamente.

Como eu evito que os worktrees se acumulem no disco?

Sessões nomeadas e worktrees com trabalho não commitado perguntam se você quer manter ou remover ao sair; sessões limpas e sem nome se limpam sozinhas. Uma varredura periódica também remove worktrees antigos de subagent e de sessão em segundo plano com base na sua configuração cleanupPeriodDays. Para controle manual, rode git worktree list e git worktree remove [--force].

Worktrees funcionam com SVN/Perforce/repositórios que não são git?

Não com o fluxo padrão - o isolamento de worktree usa git por padrão. Para SVN, Perforce, Mercurial ou outro VCS, você configura hooks WorktreeCreate/WorktreeRemove para substituir a lógica do git pela sua própria; note que o .worktreeinclude não é processado nesse caminho, então você copia os arquivos de configuração dentro do script do hook.

Conclusão

Worktrees resolvem exatamente um problema bem: sessões paralelas do Claude Code que não pisam nos arquivos umas das outras. Elas não coordenam o trabalho sozinhas - combine-as com subagents, agent view ou agent teams para essa metade do quadro, usando o framework de decisão acima em vez de chutar. Comece com um worktree extra para a sua próxima tarefa paralela antes de escalar para três recursos em paralelo; acerte o .worktreeinclude e o isolamento de portas cedo, e a limpeza se resolve quase sozinha.