Executar sessões paralelas com worktrees

Isole sessões paralelas do Claude Code em worktrees git separadas para que as alterações não colidam. Abrange o sinalizador --worktree, isolamento de subagentes, .worktreeinclude, limpeza e hooks de VCS não-git.

Uma git worktree é um diretório de trabalho separado com seus próprios arquivos e branch, compartilhando o mesmo histórico de repositório e remoto que seu checkout principal. Executar cada sessão do Claude Code em sua própria worktree significa que edições em uma sessão nunca tocam arquivos em outra, para que você possa ter Claude construindo um recurso em um terminal enquanto corrige um bug em um segundo.

Esta página aborda isolamento de worktree na CLI. Tudo abaixo assume um repositório git. Para outros sistemas de controle de versão, consulte Controle de versão não-git. O aplicativo desktop cria uma worktree para cada nova sessão automaticamente.

Worktrees são uma das várias maneiras de executar Claude em paralelo. Elas isolam edições de arquivo, enquanto subagentes e equipes de agentes coordenam o trabalho em si. Consulte Executar agentes em paralelo para comparar as abordagens, ou pule para Isolar subagentes com worktrees para usar worktrees e subagentes juntos.

Inicie Claude em uma worktree

Passe --worktree ou -w para criar uma worktree isolada e iniciar Claude nela. Por padrão, a worktree é criada em .claude/worktrees/<value>/ na raiz do seu repositório, em um novo branch nomeado worktree-<value>:

claude --worktree feature-auth

Para colocar worktrees em outro lugar, configure um hook WorktreeCreate. Execute o comando novamente com um nome diferente em outro terminal para iniciar uma segunda sessão isolada:

claude --worktree bugfix-123

Se você omitir o nome, Claude gera um como bright-running-fox:

claude --worktree

Você também pode pedir ao Claude para "trabalhar em uma worktree" durante uma sessão, e ele criará uma com a ferramenta EnterWorktree. Uma vez em uma worktree, Claude pode alternar diretamente para outra em .claude/worktrees/ chamando EnterWorktree com o caminho de destino. A worktree anterior permanece no disco intacta.

Antes de usar --worktree interativamente em um diretório pela primeira vez, aceite o diálogo de confiança do workspace executando claude uma vez nesse diretório. Se a confiança ainda não foi aceita, --worktree sai com um erro e solicita que você execute claude no diretório primeiro. Execuções não interativas com -p pulam a verificação de confiança, então claude -p --worktree prossegue sem ela.

Escolha o branch base

Worktrees fazem branch a partir do branch padrão do seu repositório, origin/HEAD, para que começem de uma árvore limpa correspondendo ao remoto. Se nenhum remoto estiver configurado ou a busca falhar, a worktree volta para seu HEAD local atual. Para sempre fazer branch a partir do HEAD local, defina worktree.baseRef como "head" em configurações. Definir baseRef como "head" faz com que novas worktrees carreguem seus commits não enviados e estado de branch de recurso, o que é útil ao isolar subagentes que precisam operar em trabalho em andamento. A configuração aceita apenas "fresh" ou "head", não refs git arbitrárias:

{
  "worktree": {
    "baseRef": "head"
  }
}

Para fazer branch a partir de um pull request específico, passe o número do PR prefixado com #, ou uma URL completa de pull request do GitHub. Claude Code busca pull/<number>/head de origin e cria a worktree em .claude/worktrees/pr-<number>:

claude --worktree "#1234"

Para controle total sobre como as worktrees são criadas, configure um hook WorktreeCreate, que substitui completamente a lógica padrão de git worktree.

Copie arquivos ignorados pelo git em worktrees

Uma worktree é um checkout fresco, então arquivos não rastreados como .env ou .env.local do seu repositório principal não estão presentes. Para copiá-los automaticamente quando Claude cria uma worktree, adicione um arquivo .worktreeinclude à raiz do seu projeto.

O arquivo usa sintaxe .gitignore. Apenas arquivos que correspondem a um padrão e também são ignorados pelo git são copiados, então arquivos rastreados nunca são duplicados.

Este .worktreeinclude copia dois arquivos env e uma configuração de segredos em cada nova worktree:

.env
.env.local
config/secrets.json

Isso se aplica a worktrees criadas com --worktree, worktrees de subagentes, e sessões paralelas no aplicativo desktop.

Isole subagentes com worktrees

Subagentes podem executar em suas próprias worktrees para que edições paralelas não entrem em conflito. Peça ao Claude para "usar worktrees para seus agentes", ou defina permanentemente em um subagente personalizado adicionando isolation: worktree ao frontmatter. Cada subagente obtém uma worktree temporária que é removida automaticamente quando o subagente termina sem alterações.

As worktrees de subagentes usam a mesma branch base que --worktree, portanto elas fazem branch da branch padrão do seu repositório, a menos que worktree.baseRef seja definido como "head".

Limpe worktrees

Quando você sai de uma sessão de worktree, a limpeza depende se você fez alterações:

• Sem alterações não confirmadas, sem arquivos não rastreados e sem novos commits: a worktree e seu branch são removidos automaticamente. Se a sessão tiver um nome, Claude solicita em vez disso para que você possa manter a worktree para depois
• Alterações não confirmadas, arquivos não rastreados ou novos commits existem: Claude solicita que você mantenha ou remova a worktree. Manter preserva o diretório e branch para que você possa retornar mais tarde. Remover exclui o diretório da worktree e seu branch, descartando todas as alterações não confirmadas, arquivos não rastreados e commits
• Execuções não interativas: worktrees criadas com --worktree junto com -p não são limpas automaticamente, pois não há prompt de saída. Remova-as com git worktree remove

Worktrees que Claude criou para subagentes e sessões em segundo plano são removidas automaticamente uma vez que são mais antigas que sua configuração cleanupPeriodDays, desde que não tenham alterações não confirmadas, nenhum arquivo não rastreado e nenhum commit não enviado. Worktrees que você cria com --worktree nunca são removidas por esta varredura.

Enquanto um agente está em execução, Claude executa git worktree lock em sua worktree para que a limpeza simultânea não possa removê-la. O bloqueio é liberado quando o agente termina. Para limpar uma worktree que a varredura mantém, execute git worktree remove, adicionando --force se a worktree tiver alterações não confirmadas ou arquivos não rastreados.

Gerencie worktrees manualmente

Para controle total sobre localização de worktree e configuração de branch, crie worktrees com Git diretamente. Isso é útil quando você precisa fazer checkout de um branch existente específico ou colocar a worktree fora do repositório.

Crie uma worktree em um novo branch:

git worktree add ../project-feature-a -b feature-a

Crie uma worktree a partir de um branch existente:

git worktree add ../project-bugfix bugfix-123

Inicie Claude na worktree:

cd ../project-feature-a && claude

Liste suas worktrees:

git worktree list

Remova uma quando terminar com ela:

git worktree remove ../project-feature-a

Consulte a documentação de git worktree para a referência completa de comandos. Lembre-se de inicializar seu ambiente de desenvolvimento em cada nova worktree: instale dependências, configure ambientes virtuais, ou execute o que quer que a configuração do seu projeto exija.

Controle de versão não-git

Isolamento de worktrees usa git por padrão. Para SVN, Perforce, Mercurial, ou outros sistemas, configure os hooks WorktreeCreate e WorktreeRemove para fornecer lógica de criação e limpeza personalizada. Como o hook substitui o comportamento padrão do git, .worktreeinclude não é processado quando você usa --worktree. Copie quaisquer arquivos de configuração local dentro do seu script de hook.

Este hook WorktreeCreate lê o nome da worktree de stdin, faz checkout de uma cópia de trabalho SVN fresca, e imprime o caminho do diretório para que Claude Code possa usá-lo como o diretório de trabalho da sessão:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Emparelhe-o com um hook WorktreeRemove para limpar quando a sessão terminar. Consulte a referência de hooks para o esquema de entrada e um exemplo de remoção.

Veja também

Worktrees lidam com isolamento de arquivo. As páginas relacionadas abaixo cobrem delegação de trabalho para esses checkouts isolados e alternância entre as sessões que você cria:

• Subagentes: delegue trabalho para agentes isolados dentro de uma sessão
• Equipes de agentes: coordene múltiplas sessões do Claude automaticamente
• Gerencie sessões: nomeie, retome e alterne entre conversas
• Sessões paralelas do desktop: sessões apoiadas por worktree no aplicativo desktop