Worktrees no Claude Code: rode sessões paralelas sem conflitos
Um comando dá a cada sessão do Claude Code sua própria cópia completa do repositório. Aprenda claude --worktree, o layout .claude/worktrees, isolamento de worktree para subagentes, a limpeza na saída e onde o git worktree add manual ainda ganha.
A versão curta
- claude --worktree (forma curta -w) inicia a sessão dentro de uma cópia nova do repositório em .claude/worktrees/<name>, com checkout no branch worktree-<name>.
- Abra mais sessões em outros terminais para trabalhar em paralelo — cada sessão edita o próprio diretório enquanto compartilha o mesmo histórico e remoto do Git.
- Subagentes ganham worktrees também: peça em linguagem natural ou defina isolation: worktree no frontmatter de um .claude/agents/*.md para tornar permanente.
- Na saída, worktrees sem nome e limpos são removidos automaticamente e trabalho em andamento pergunta se você quer manter ou remover; faça o merge dos resultados com um git merge normal de worktree-<name>.
Claude Code Worktrees in 7 Minutes
Canal: Developers Digest7:10
I'm using claude --worktree for everything now
Canal: Matt Pocock7:57
Worktrees — official documentation
Documentação oficial: code.claude.com/docs
Cada flag, caminho e comportamento de limpeza desta página foi verificado contra a documentação oficial de worktrees; os vídeos acima são as fontes visuais e factuais, incluindo o prompt de manter/remover na saída e a pegadinha do push para main.
As capturas de tela pertencem aos seus criadores, com links diretos para os timestamps exatos. Nenhum quadro com rosto é usado.
Usar worktrees do Claude Code, passo a passo
Parte 1 — Sua primeira sessão isolada
- 1
Prepare um repositório Git com pelo menos um commit
Worktrees derivam de um histórico existente, então o recurso precisa de um repositório Git de verdade. Em uma pasta nova, rode git init, crie um arquivo (a demo apenas roda touch index.html) e faça o commit. Pule isso e o Claude Code não tem de onde derivar.

git init mais touch index.html — um commit é tudo de que o recurso de worktree precisa antes de rodar claude --worktree.Ver em 1:06 - 2
Entenda o que é um worktree de verdade
Um worktree do Git é um segundo diretório de trabalho com seus próprios arquivos e branch em checkout, que compartilha o histórico e o remoto do repositório. Diferente de trocar de branch, nada vai para stash: o checkout principal e cada worktree continuam utilizáveis ao mesmo tempo — exatamente o que agentes paralelos precisam.

Um repositório, muitas pastas de trabalho: ../main, ../feature1 e ../feature2 ficam cada um no seu branch, ao mesmo tempo.Ver em 0:30 - 3
Inicie o Claude Code com --worktree
De dentro do repositório, rode claude --worktree (ou a forma curta claude -w). O Claude Code cria .claude/worktrees/<name>, gera um nome como bright-tumbling-rabbit quando você não passa um, e joga a sessão direto dentro dessa cópia. No app desktop, você escolhe a opção de worktree ao iniciar uma sessão.

O banner de boas-vindas mostra que o diretório de trabalho da sessão já está dentro de .claude/worktrees — tudo a partir daqui acontece na cópia.Ver em 1:22 - 4
Abra uma segunda sessão para a segunda tarefa
Rode claude --worktree de novo em outro terminal. Sem nome você ganha outro worktree independente; passe o mesmo nome duas vezes para reabrir o mesmo. Dois agentes podem agora editar o mesmo projeto simultaneamente, porque cada um só enxerga o próprio diretório.
Parte 2 — Onde seus arquivos e comandos vivem
- 5
Inspecione a cópia completa sob .claude/worktrees
Abra a pasta no seu gerenciador de arquivos: cada worktree é um checkout completo, com o próprio index.html, o próprio .claude/settings.local.json e o próprio arquivo git, enquanto o banco de objetos pesado continua compartilhado no .git principal. É por isso que criar outra cópia custa quase nada.

Dois worktrees no disco — clever-munching-toast e spicy-napping-otter — cada um uma cópia completa do projeto com seu próprio diretório git e index.html.Ver em 1:50 - 6
Confirme que os comandos ficam dentro do worktree
Quando a primeira sessão abre a página no navegador, o prompt de permissão mostra que o caminho aponta para .claude/worktrees/clever-munching-toast — não para o seu checkout principal. O Claude Code também impede subagentes de editar o checkout principal diretamente, e uma dessas checagens de isolamento não pode ser desligada.

O diálogo de aprovação cita o caminho exato do worktree, provando que a sessão um só toca na própria cópia do projeto.Ver em 1:42 - 7
Dê nome aos worktrees ou derive de PRs (opcional)
claude --worktree feature-auth cria um worktree nomeado previsível, e rodar o mesmo nome de novo o reabre em vez de duplicar. Você também pode passar um número de PR entre aspas (claude --worktree "#1234") ou a URL de um PR do GitHub/GitLab para ganhar um worktree daquele pull request em .claude/worktrees/pr-<number>.
Parte 3 — Subagentes em paralelo e limpeza
- 8
Peça subagentes paralelos com isolamento de worktree
O isolamento escala além dos terminais. Um único prompt — "gere cinco subagentes diferentes para criar cinco variações, usando isolamento de git worktree" — faz o Claude Code spawnar agentes Task, cada um no próprio worktree isolado, trabalhando no mesmo repositório ao mesmo tempo sem colisões.

Cinco agentes Task surgindo em paralelo, cada um anunciado como trabalhando no próprio worktree git isolado.Ver em 2:42 - 9
Veja cada agente correr na própria pista
A lista de tarefas mostra as cinco variações com usos de ferramentas e contagem de tokens, então você acompanha o progresso sem abrir cinco terminais. As transcrições dos subagentes ficam fora do contexto do thread principal, o que mantém a sessão orquestradora enxuta enquanto os agentes fazem o trabalho pesado.

Os cinco subagentes no meio da execução — Variation 1 já concluída com 50.3k tokens enquanto os outros leem arquivos nos próprios worktrees.Ver em 3:42 - 10
Compare as variações e faça o merge da vencedora
Quando os agentes terminam, o Claude Code lista cada variação com o caminho em .claude/worktrees/agent-<id>/, para você abrir lado a lado no navegador. Envie a que preferir com um git merge normal do branch do worktree (ou um PR) — conflitos, se houver, se resolvem como em qualquer merge do Git.

O resumo cita cada variação e seu caminho em .claude/worktrees, com um resultado renderizado aberto ao lado da lista.Ver em 4:22 - 11
Salve o isolamento como um subagente reutilizável
Para tornar o isolamento de worktree permanente, basta pedir: "crie um subagente desenvolvedor front-end, use o modelo Haiku e faça ele aproveitar isolamento de worktree". O Claude Code pesquisa a própria documentação de agentes e escreve um novo arquivo em .claude/agents/ para você.

Linguagem natural basta — o Claude Code consulta os próprios docs sobre o formato de agente customizado antes de escrever o arquivo.Ver em 5:42 - 12
Confira o frontmatter isolation: worktree
O frontend-dev.md gerado traz name, description, model: haiku, uma lista de ferramentas e — a linha nova — isolation: worktree. Cada execução futura deste subagente agora acontece em um worktree temporário, removido automaticamente se terminar sem mudanças.

A linha 8 do frontmatter — isolation: worktree — é o que dá a cada execução deste subagente seu próprio worktree.Ver em 6:42 - 13
Faça o merge e deixe o Claude limpar
Ao sair de uma sessão, o Claude Code inspeciona o worktree: worktrees sem nome e limpos são removidos automaticamente, e qualquer um com trabalho pergunta se você quer manter ou remover — manter imprime o comando claude --worktree <name> --resume para depois. Execuções headless com -p nunca limpam, então remova essas com git worktree remove.
Worktrees do Claude Code vs. git worktree add manual
Worktrees fazem parte do Git há anos — o novo é o Claude Code gerenciar todo o ciclo de vida deles. As diferenças que importam:
- 1Criação: à mão você roda git worktree add ../project-feature -b feature, entra com cd e abre o Claude. Com claude --worktree a sessão aterrissa dentro de .claude/worktrees/<name> em um passo, nomeado por você ou para você.
- 2Commit de base: worktree.baseRef controla o ponto de partida — fresh (padrão) deriva do branch padrão do remoto, head carrega seus commits locais ainda sem push. A flag não mira um branch específico; os docs mandam usar git worktree add manual para isso.
- 3Dotfiles: um arquivo .worktreeinclude na raiz do projeto copia arquivos ignorados pelo git, como .env, para cada worktree novo. Worktrees feitos à mão não recebem esse tratamento.
- 4Limpeza: o Claude Code inspeciona o worktree na saída, remove sozinho os sem nome e limpos, pergunta antes de tocar em trabalho em andamento e varre worktrees abandonados de subagentes periodicamente. Worktrees manuais são inteiramente sua responsabilidade.
- 5Guardrails: checagens de isolamento impedem subagentes de editar o checkout principal, e retomar uma sessão te devolve ao worktree dela. O git worktree add puro não tem rede de segurança equivalente.
Por baixo, ainda é Git comum. O painel de controle de código-fonte do VS Code lista cada worktree com suas mudanças, os merges são merges normais do git, e worktrees manuais e criados pelo Claude coexistem no mesmo repositório — escolha a ferramenta por tarefa.
Quando um worktree não se comporta
A maioria das pegadinhas é fundamentos do Git aparecendo, não bugs do recurso. Essas cinco cobrem quase toda borda áspera que você vai encontrar:
- 1O push cai na main. Um branch de worktree novo rastreia o branch padrão do origin, então um git push sem qualificação pode mirar a main. Dê push explicitamente com git push origin worktree-<name> e mantenha a main protegida.
- 2Faltam arquivos ou ferramentas. Arquivos no .gitignore (.env, diretórios vendor) e filter drivers locais do repositório como o LFS não se propagam para um worktree novo. Liste-os no .worktreeinclude, ou rode git lfs pull e seus comandos de configuração dentro do worktree.
- 3A inicialização falha com erro de confiança. Em um diretório não confiável, o claude --worktree sai com erro pedindo que você aceite o workspace primeiro — aprove e rode de novo. (Execuções não interativas com -p pulam a checagem.)
- 4Dois worktrees colidem na hora do merge. Se as duas tarefas editam o mesmo arquivo — rotas, uma sidebar, o package.json — você resolve conflitos ao mesclar, como em qualquer fluxo Git. Worktrees eliminam colisões durante a execução, não intenções sobrepostas.
- 5Worktrees sobrando depois de execuções headless. Execuções -p nunca limpam depois de si; apague manualmente com git worktree remove (rode git worktree unlock antes se estiver travado).
Apagar um worktree por baixo de uma sessão também não é fatal: o próximo resume cai de volta no diretório de origem e o vínculo se dissolve. Nada mais na sessão quebra.
