Deepseek ArtifactsDeepseek Artifacts
Guia de worktrees

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

Assistir

I'm using claude --worktree for everything now

Canal: Matt Pocock7:57

Assistir

Worktrees — official documentation

Documentação oficial: code.claude.com/docs

Assistir

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. 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.

    Terminal running git init in a demo-app folder with Initialized empty Git repository output and touch index.html, the one-commit starting point Claude Code worktrees require
    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. 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.

    Worktrees diagram showing one Git repository fanning out into three folders labeled ../main, ../feature1 and ../feature2, each checked out on its own branch
    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. 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.

    Claude Code v2.1.50 welcome banner after launching claude --worktree in the demo-app repo, with the session working directory set to .claude/worktrees/bright-tumbling-rabbit
    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. 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

  1. 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.

    macOS Finder window listing .claude/worktrees with clever-munching-toast and spicy-napping-otter copies behind two browser tabs, each worktree holding its own git folder and index.html
    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
  2. 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.

    Claude Code permission prompt for an open command targeting .claude/worktrees/clever-munching-toast/index.html, showing the session working only inside its own worktree copy
    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
  3. 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

  1. 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.

    Claude Code spawning five Task agents in parallel after a single prompt requesting creative SaaS landing page variations with git worktree isolation
    Cinco agentes Task surgindo em paralelo, cada um anunciado como trabalhando no próprio worktree git isolado.Ver em 2:42
  2. 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.

    Claude Code task list with all five SaaS landing page subagents mid-run, each labeled with tool uses and token counts while isolated in its own worktree
    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
  3. 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.

    Claude Code summary listing five landing page variations with their .claude/worktrees/agent-prefixed index.html paths next to a rendered dark FlowSync preview
    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
  4. 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ê.

    Claude Code accepting a natural-language request to create a front-end developer subagent with Haiku that leverages work tree isolation
    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
  5. 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.

    Claude Code writing the .claude/agents/frontend-dev.md subagent file with isolation: worktree in its YAML frontmatter so every future run gets its own worktree
    A linha 8 do frontmatter — isolation: worktree — é o que dá a cada execução deste subagente seu próprio worktree.Ver em 6:42
  6. 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.

FAQ

Guias relacionados do Claude Code