Executar sessões paralelas com worktrees

​

Inicie Claude em uma worktree

claude --worktree feature-auth

​

Configure o ambiente da worktree

​

Peça ao Claude para criar uma worktree

​

Limpe worktrees

• A worktree está limpa: para uma sessão sem nome, Claude remove a worktree e seu branch automaticamente. Uma sessão nomeada solicita primeiro para que você possa manter a worktree para depois
• A worktree tem trabalho nela: Claude solicita que você mantenha ou remova a worktree. Manter preserva o diretório e branch para que você possa retornar depois. Remover deleta o diretório da worktree e seu branch, junto com todo o trabalho neles
• O estado da worktree não pode ser verificado: quando Claude Code não consegue contar as alterações da worktree ou não consegue inspecionar seus checkouts de submódulo, ele solicita em vez de remover a worktree automaticamente. O prompt nomeia o que não conseguiu verificar

​

Retome uma sessão de worktree

• Diretório de inicialização: retome do checkout principal ou outro diretório do repositório. Claude Code re-entra em uma worktree que criou com git em .claude/worktrees/ mesmo quando você inicia de dentro dela. Quando você inicia de dentro de qualquer outra worktree, Claude Code re-entra nela apenas se puder garantir por ela de lá: uma worktree que é seu próprio repositório, uma sem metadados git, ou um início de um subdiretório de uma worktree que você criou com git worktree add recusa, então inicie aquelas do checkout principal.
• --fork-session: a sessão bifurcada começa no diretório de onde você iniciou Claude, e Claude Code deixa a worktree da sessão original intacta.
• Worktree deletada: se o diretório da worktree não existe mais, Claude Code retoma a sessão no diretório de onde você iniciou Claude. Ele diz que a worktree se foi e limpa a vinculação de worktree da sessão.

​

Como Claude Code impõe isolamento

• Edições de arquivo: Claude Code bloqueia um Edit, Write, ou NotebookEdit que visa um caminho no checkout principal.
• Diretório de trabalho do comando: Claude Code bloqueia um comando Bash, PowerShell, ou Monitor cujo diretório de trabalho resolve para o checkout principal, ou cujo diretório de trabalho não pode verificar que fica fora dele.
• Redirecionamentos git: Claude Code bloqueia um comando Bash ou Monitor que redireciona git para o checkout principal. O redirecionamento pode vir através de git -C, --git-dir, uma variável GIT_DIR ou GIT_WORK_TREE, ou um cd para o checkout principal antes de executar git.
• Forma do comando: Claude Code bloqueia um comando Bash ou Monitor quando não pode verificar do texto do comando que qualquer git que o comando executa fica dentro da worktree. Isso acontece, por exemplo, quando o nome do comando é computado em tempo de execução, quando a sintaxe não pode ser analisada, ou quando uma expansão como ${!name} ou ${ command; } poderia executar um comando que o texto não especifica. Claude Code diz a Claude como reescrever o comando recusado, como dividi-lo em comandos simples e separados. Você não pode desativar essa verificação.

​

Isole subagentes com worktrees

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

​

Limpe worktrees de subagente e sessão em segundo plano

• A worktree ainda contém trabalho: arquivos alterados ou não rastreados, ou commits não enviados.
• Um submódulo verificado na worktree contém arquivos alterados ou não rastreados, ou Claude Code não consegue inspecionar os submódulos da worktree. Esta verificação requer Claude Code v2.1.274 ou posterior.
• Um dos quatro casos que também bloqueiam a criação de worktree se aplica: Claude Code não pode determinar quais drivers de filtro a configuração do repositório define, ou encontra uma configuração lá que não pode desativar.
• A worktree pertence a uma sessão --worktree que você não colocou em segundo plano, qualquer que seja sua idade.
• Você criou a worktree você mesmo com git worktree add, mesmo que depois tenha executado uma sessão --worktree <name> nela e colocado essa sessão em segundo plano.

​

Customize a criação de worktree

​

Escolha a branch base

• "fresh" (padrão): faz branch da branch padrão do repositório no remoto, geralmente main, para que a worktree comece de uma árvore limpa correspondendo ao remoto.
• "head": faz branch do seu HEAD local atual, para que a worktree carregue seus commits não enviados e estado de branch de recurso. Use isso ao isolar subagentes que precisam operar em trabalho em andamento. Dentro de uma worktree, "head" resolve para o HEAD dessa worktree, não para o checkout principal.

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

​

Faça branch de um pull request

claude --worktree "#1234"

• github.com: busca pull/<number>/head
• gitlab.com: busca merge-requests/<number>/head
• GitHub Enterprise, GitLab auto-hospedado, ou qualquer outro host: tenta pull/<number>/head primeiro, depois merge-requests/<number>/head

​

Copie arquivos ignorados pelo git em worktrees

.env
.env.local
config/secrets.json

​

Reutilize um nome de worktree

• Não tem alterações não confirmadas ou arquivos não rastreados.
• Ainda está na branch que Claude Code criou para ela.
• Não tem commits próprios, ou seu pull request ou merge request foi mesclado e sua branch remota foi deletada.

• A worktree falha em qualquer uma das condições.
• Claude Code não pode verificar o estado da worktree.
• worktree.baseRef é "head".
• O nome é uma referência de pull request ou merge request.

​

Substitua a criação de worktree com um hook

​

O que worktrees compartilham com o checkout principal

• O diretório .git do repositório: comandos git em uma worktree escrevem no diretório .git compartilhado do repositório principal, e sandboxing permite essas escritas, então comandos como git commit funcionam de dentro de uma worktree com a sandbox ativada.
• Plugins: plugins instalados em escopo de projeto do checkout principal também carregam em worktrees do mesmo repositório, então você não precisa reinstalá-los por worktree. Requer Claude Code v2.1.200 ou posterior.
• Aprovações de permissão: escolher “Sim, e não pergunte novamente” para um comando Bash em uma sessão de worktree salva a regra no .claude/settings.local.json do checkout principal, para que se aplique no checkout principal e em cada outra worktree do repositório, e sobreviva à remoção da worktree. No Windows e nos outros casos onde Claude Code não usa a raiz do repositório, a regra fica com essa worktree. Antes da v2.1.211, uma aprovação concedida em uma worktree era salva dentro dessa worktree, não se aplicava em outro lugar, e era perdida quando a worktree era removida. Consulte onde as aprovações são salvas.
• Skills, agentes e comandos não rastreados: quando o checkout da worktree não tem um diretório .claude/skills em sua raiz, por exemplo porque seu .claude/skills é gitignored, Claude Code carrega as skills de projeto do checkout principal na sessão da worktree. Em uma worktree com seu próprio diretório .claude/skills, apenas essa cópia carrega. A mesma leitura abrange .claude/agents e .claude/commands. Para skills, a leitura requer Claude Code v2.1.277 ou posterior.

​

Gerencie worktrees manualmente

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

git worktree add ../project-bugfix fix-issue-456

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

Controle de versão não-git

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

​

Troubleshooting

​

Claude Code não consegue entrar na worktree na inicialização

​

A criação de worktree falha em um caminho symlinked

​

Arquivos Git LFS são arquivos de ponteiro em uma worktree que Claude Code criou

• Could not read the repository git config to neutralize filter drivers: Claude Code não conseguiu ler o .git/config do repositório, por exemplo por causa de suas permissões. Corrija isso e tente novamente.
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): renomeie ou remova esse driver de filtro em .git/config e tente novamente.
• The repository git config has a conditional include (includeIf): mova as configurações que o includeIf em .git/config puxa diretamente para esse arquivo, remova o includeIf, e tente novamente. Um includeIf em sua configuração git global não dispara isso.
• Git was not run: the repository's own git config sets <key>: a mensagem nomeia uma chave que aponta Git LFS para um programa a executar, como lfs.customtransfer.<name>.path ou lfs.standalonetransferagent. Se essa configuração é sua, mova-a para sua configuração git global. Se você não a reconhecer, remova-a da configuração git do repositório, já que uma ferramenta ou checkout que você não confia pode tê-la escrito. Tente novamente uma vez que a chave tenha desaparecido da configuração do repositório.

​

Claude Code recusa usar uma worktree

• Diz launch from the parent checkout ou Run the resume from the project checkout: você iniciou Claude Code de dentro da worktree. Inicie do checkout principal em vez disso; a worktree não precisa de recriação.
• Diz it cannot be resumed or re-entered: nada nesta sessão garante a worktree de onde você iniciou. Recrie-a; o diretório e seu trabalho permanecem no disco para recuperação manual, e quando a worktree tem um checkout pai, retomar de lá também funciona.
• Diz it contains the protected checkout: o diretório recusado é um pai do seu checkout principal, como seu diretório home. Não o delete. Altere o caminho da worktree, como o caminho que seu hook WorktreeCreate retorna ou o alvo EnterWorktree, para que a worktree não contenha o checkout.
• Diz the protected checkout <path> has a .git entry that could not be examined ou has git metadata that could not be resolved: o problema é os metadados git do checkout principal, não da worktree. Não delete a worktree, e ignore o conselho final da mensagem para recriá-la, que não se aplica a esses dois finais. Repare o checkout principal, por exemplo um problema de permissões ou uma recusa git dubious ownership em seu .git, e tente novamente.
• Diz its recorded path has a network spelling: Claude Code nunca retoma em uma worktree em um caminho de rede. Recrie a worktree em um caminho local.
• Qualquer outro final: a mensagem nomeia o problema e sua correção, como remover um redirecionamento core.worktree ou recriar a worktree; siga-a. Antes de deletar um diretório cuja mensagem diz que sua identidade git não pôde ser verificada, aborde a causa nomeada primeiro, por exemplo um link simbólico no caminho da worktree ou git em si falhando em executar, já que o diretório pode estar saudável. Quando você recriar, salve quaisquer mudanças que você precisa do diretório antigo primeiro; ele fica no disco.

​

A sessão retoma fora de sua worktree

• Error: cannot resume into worktree <path>: ...This session was not started. para uma recusa que a tabela mostra como Did not re-enter. Claude Code limpa a vinculação de worktree antes de sair, e o erro diz assim; a próxima vez que você retomar a conversa, a sessão continua no diretório atual sem isolamento de worktree. Antes da v2.1.260, Claude Code não escrevia a vinculação limpa, então cada retentativa da mesma retoma falhava com o mesmo erro. Se você suprimir escritas de transcrição, a limpeza não pode ser salva. O erro então diz que o mesmo comando será recusado novamente, e nomeia --fork-session e iniciar uma nova conversa como formas de continuar sem a worktree.
• Error: could not verify worktree <path> for this resume, so the resume was aborted... para Could not verify
• Error: ...The worktree binding is kept. para Could not re-enter
• Notice: the worktree <path> for this session no longer exists... para uma worktree desaparecida; Claude Code imprime-a e continua a sessão, como uma retoma interativa faz

​

Veja também

• Subagentes: delegue trabalho para agentes isolados dentro de uma sessão
• Mensagens entre sessões: deixe as sessões em suas worktrees passarem descobertas uma para a outra
• 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