Worktrees no Claude Code: sessões paralelas sem conflitos de edição

Worktrees no Claude Code, explicadas

O git tem worktrees há anos: git worktree add faz checkout de uma branch em um segundo diretório, apoiado nos mesmos dados do .git. O Claude Code se baseia nisso. Com --worktree (ou -w), ele cria a worktree para você, inicia a sessão dentro dela, bloqueia edições que cairiam no seu checkout principal e oferece fazer a limpeza quando você sai.

As worktrees isolam arquivos, e nada mais. Para dividir uma tarefa entre vários workers dentro de uma única conversa, use subagentes; para comparar as opções, veja vários agentes do Claude Code.

• Local padrão: .claude/worktrees/<name>/, na raiz do repositório.
• Nome de branch padrão: worktree-<name>. Se você não der um nome, o Claude Code escolhe um, como bright-running-fox.
• Compartilhado com o seu checkout: o diretório .git (então commits e branches aparecem em todo lugar), os plugins do projeto e as aprovações de permissão de "não perguntar de novo".
• Não compartilhado: tudo o que está no .gitignore, como .env, node_modules e os artefatos de build. Uma worktree é um checkout novo.

O fluxo com worktrees, passo a passo

1. Ignore a pasta das worktrees

   Adicione .claude/worktrees/ ao .gitignore, para que os arquivos das worktrees não apareçam como não rastreados no seu checkout principal. Se você nunca rodou o Claude neste repositório, rode claude uma vez antes para aceitar o aviso de confiança do workspace; até lá, as execuções interativas com --worktree se encerram.

2. Inicie uma sessão por tarefa

   Rode claude --worktree <name> em um terminal para cada tarefa. Rodar de novo com um nome que já existe reabre essa worktree em vez de criar outra. Você também pode pedir ao Claude no meio da sessão para "trabalhar em uma worktree", e ele se move para uma com a ferramenta EnterWorktree.

   # Duas sessões isoladas, cada uma no próprio terminal
   claude --worktree feature-auth
   claude --worktree fix-flaky-test
   
   # Crie uma worktree a partir do pull request 1234 (coloque o # entre aspas)
   claude --worktree "#1234"
   
   # Deixe as worktrees fora do git status
   echo ".claude/worktrees/" >> .gitignore

3. Leve junto os arquivos não rastreados

   Liste os arquivos ignorados pelo git de que o projeto precisa, como .env e .env.local, em um arquivo .worktreeinclude na raiz do repositório, com a sintaxe do .gitignore. O Claude Code copia os arquivos que combinam para cada worktree que cria, inclusive as de subagentes e as do app desktop. Depois instale as dependências na worktree, ou configure isso nas configurações: este exemplo parte do seu trabalho atual, reaproveita um único node_modules e faz checkout só do pacote web.

   {
     "worktree": {
       "baseRef": "head",
       "symlinkDirectories": ["node_modules"],
       "sparsePaths": [".claude", "packages/web"]
     }
   }

4. Deixe as sessões trabalharem

   Enquanto uma sessão está isolada, o Claude Code recusa edições de arquivo que apontam para o checkout principal, comandos cujo diretório de trabalho é o checkout principal e comandos git redirecionados para ele (git -C, --git-dir, GIT_DIR). Ele não acompanha o que um comando de shell comum como cp escreve, então permissões e sandbox continuam importando.

5. Revise e faça o merge como qualquer branch

   Cada worktree é uma branch normal. Faça commit e push de dentro dela, abra um pull request e revise como faria com o de um colega. Como todas as worktrees compartilham o .git, a branch aparece no seu checkout principal na hora.

6. Saia e faça a limpeza

   Quando você sai, o Claude Code verifica a worktree. Uma worktree limpa de uma sessão sem nome é removida automaticamente junto com a branch; uma sessão com nome pergunta antes. Se houver alterações, arquivos não rastreados ou commits novos, ele pergunta se deve manter ou remover a worktree e mostra um comando claude --worktree <name> --resume para você voltar depois.

Fonte: documentação do Claude Code, Run parallel sessions with worktrees

Configurações de worktree no Claude Code

Todas ficam sob worktree em um arquivo de configurações (~/.claude/settings.json, .claude/settings.json ou .claude/settings.local.json).

Worktree do Claude Code vs branch vs git worktree

Fazendo à mão com git worktree

Use o git puro quando quiser uma branch específica que já existe ou uma pasta fora do repositório; o worktree.baseRef não consegue apontar para uma branch. O Claude Code continua compartilhando plugins e aprovações de permissão com essas worktrees.

1. Crie a worktree, inicie o Claude e remova quando terminar

   Troque feature-a pelo nome de uma branch nova, ou tire o -b para fazer checkout de uma branch que já existe.

   git worktree add ../app-feature-a -b feature-a
   cd ../app-feature-a && claude
   git worktree list
   git worktree remove ../app-feature-a

Subagentes e sessões em background em worktrees

• Peça ao Claude para "usar worktrees para os seus agentes", ou adicione isolation: worktree ao frontmatter de um subagente personalizado em .claude/agents/, e cada subagente edita na própria worktree temporária.
• A worktree de um subagente sem alterações é removida quando o subagente termina. Uma com alterações fica até que uma limpeza periódica consiga removê-la sem perder trabalho, depois de cleanupPeriodDays.
• Sessões em background (claude --bg) editam só dentro de uma worktree por padrão; inicie uma com claude --bg --worktree ou defina worktree.bgIsolation como "none".
• No app desktop, ative Worktree embaixo da caixa de prompt antes de iniciar uma sessão.

Limpeza de worktrees e problemas comuns

• Execuções com claude -p --worktree não têm o aviso de saída, então deixam as worktrees para trás. Remova-as com git worktree remove, depois de git worktree unlock se o git disser que ela está travada.
• Can only use --worktree in a git repository: rode git init e faça um primeiro commit, ou configure um hook WorktreeCreate para SVN, Perforce ou Mercurial.
• Arquivos do Git LFS aparecem como arquivos ponteiro quando o LFS foi instalado com --local: rode git lfs pull dentro da worktree.
• O Claude Code não cria uma worktree quando .claude ou .claude/worktrees é um symlink.
• Os hooks mantêm ${CLAUDE_PROJECT_DIR} apontando para o checkout principal; leia o campo cwd da entrada do hook para obter o caminho da worktree.
• Uma worktree com base "fresh" e sem commits próprios, ou cujo PR já passou pelo merge, volta para a branch padrão quando você a reabre pelo nome.

As worktrees mantêm as sessões separadas. O Crewmark as mantém ocupadas.

As worktrees resolvem o problema das colisões, mas cada sessão continua parada até você digitar. O Crewmark transforma uma sessão do Claude Code, Codex, DeepSeek Harness ou OpenCode em um funcionário de IA com um papel, uma meta e um horário de trabalho, e a acorda com um heartbeat para pegar a próxima issue de um quadro.

1. Um funcionário por worktree

   Dê a cada funcionário a própria worktree e um papel, como um programador e um revisor no mesmo repositório, como em vários agentes do Claude Code.

2. Deixe o heartbeat iniciar o trabalho

   Durante o horário de trabalho, cada funcionário acorda a cada 15, 30 ou 60 minutos na mesma conversa; veja como tornar o Claude Code proativo.

3. Atribua issues e revise as branches

   Coloque o trabalho no quadro; cada funcionário pega uma issue, faz commit na própria branch e avisa você quando precisa de uma decisão. Leia o que é um funcionário de IA.

Perguntas frequentes sobre worktrees no Claude Code