Worktrees no Claude Code

Problema: Uma sessão de Claude Code está a decorrer bem numa branch de funcionalidade, e um bug de produção aterra na tua mesa. As opções são más: fazer stash e perder o estado de trabalho, abrir um segundo terminal e ver as duas sessões a lutar pelos mesmos ficheiros, ou abandonar a sessão completamente.

Solução Rápida: Abre uma segunda sessão de Claude Code dentro do seu próprio worktree:

claude --worktree bugfix-123

Um diretório de trabalho novo aparece em .claude/worktrees/bugfix-123/ na sua própria branch, worktree-bugfix-123. A primeira sessão fica intacta. Nada é feito stash. Nada colide. Duas sessões de Claude correm lado a lado, e nenhuma sabe que a outra existe.

Se estás a decidir entre padrões de agentes, mantém o limite simples: lê Agent Fundamentals quando precisares de sub-agentes, slash commands ou especialização leve dentro de uma sessão. Lê esta página quando o problema real é isolamento de filesystem, branches separadas e trabalho paralelo que não pode tocar no mesmo checkout. Para padrões de orquestração por cima desse isolamento, lê Agent Patterns.

Porque os Worktrees Mudam Tudo

Quem já empurrou Claude Code com sub-agentes ou agentes em background já chegou ao limite. Dois agentes começam a editar o mesmo ficheiro ao mesmo tempo. Um reescreve src/auth.ts enquanto o outro está a meio do mesmo módulo. O resultado são alterações parcialmente aplicadas, uma confusão de merges, ou algo pior.

Os worktrees resolvem isto ao nível do filesystem. Cada um é um checkout separado do repositório com a sua própria branch, diretório e índice. O suporte a worktrees tornou-se de primeira classe no Claude Code v2.1.50, cobrindo criação, gestão e limpeza a partir da CLI, da app Desktop e até de agentes personalizados.

A CLI: Flag --worktree

Lançar Claude Code com a flag --worktree é o caminho mais rápido.

Worktrees com nome

# Iniciar Claude num worktree com nome
claude --worktree feature-auth
 
# Cria:
# .claude/worktrees/feature-auth/  (diretório de trabalho)
# Branch: worktree-feature-auth    (a partir da branch remota padrão)

Cada worktree fica na sua própria pasta dentro de .claude/worktrees/ numa branch dedicada. Podes criar tantos quantos o teu disco suportar.

Worktrees com nome automático

# Deixa o Claude gerar um nome
claude --worktree

Útil para execuções descartáveis onde o nome da branch realmente não importa.

Múltiplas sessões em paralelo

# Terminal 1: a trabalhar em auth
claude --worktree feature-auth
 
# Terminal 2: a corrigir um bug
claude --worktree bugfix-123
 
# Terminal 3: a explorar um refactor
claude --worktree experiment-new-router

Três sessões. Três branches. Zero conflitos. Cada uma pode ler todo o histórico git, mas os ficheiros de cada sessão vivem na sua própria árvore.

Criação de worktree a meio de sessão

A flag não é obrigatória no arranque. Podes pedir dentro de qualquer sessão ativa:

You: work in a worktree
Claude: I'll create an isolated worktree for this session...

Claude configura o worktree e move a sessão para dentro dele. Isto salva-te quando percebes, a meio de uma conversa, que o trabalho devia ter sido isolado desde o início.

App Desktop: Isolamento Automático

A app Desktop de Claude Code vai um passo mais longe. Cada nova sessão tem o seu próprio worktree por padrão.

Por padrão, esses worktrees ficam em .claude/worktrees/. As Definições do Desktop permitem-te mudar o caminho e definir um prefixo de branch para que as branches criadas pelo Claude fiquem agrupadas. Terminaste com uma sessão? Clica no ícone de arquivo e o worktree mais a sua branch desaparecem.

Cada sessão Desktop é segura por padrão. As sessões não se sobrescrevem mutuamente, e não precisas de as coordenar.

Isolamento de Worktree em Sub-Agentes

É aqui que a funcionalidade se justifica. Cada sub-agente que Claude lança para uma tarefa distribuída pode ter o seu próprio worktree.

Pedir ao Claude para isolar agentes

A versão mais simples:

You: Use worktrees for your agents when doing this refactor

Cada sub-agente fica no seu próprio worktree. Um worktree que termina sem edições é removido automaticamente. Um worktree que realmente alterou algo fica para analisares.

Porque isto importa para execução paralela

Sem isolamento, sub-agentes paralelos só podem ler ficheiros ou escrever em caminhos que não se sobreponham. É uma fronteira fraca. No momento em que um agente se mete no caminho de outro, obténs conflitos silenciosos.

Com isolamento, cada agente vê toda a codebase por si mesmo. O Agente A pode tentar uma abordagem em src/auth.ts enquanto o Agente B tenta a mesma de outra forma. Abres as duas branches depois e escolhes a melhor (ou combinaças partes de ambas).

Isto brilha mesmo em migrações em lote. Tens 50 ficheiros para mover de uma API para outra? Lança cinco agentes, dez ficheiros cada, todos no seu próprio worktree. Trabalham em paralelo e ninguém tropeça em ninguém. O comando /batch integrado usa exatamente este mecanismo, lançando agentes isolados em worktrees a partir de um único prompt para correr migrações numa codebase.

Agentes Personalizados com Isolamento Integrado

Agentes personalizados em .claude/agents/ podem estar configurados para usar sempre um worktree:

---
name: refactor-agent
description: Agent that performs isolated refactoring work
isolation: worktree
---
You are a refactoring specialist. Analyze the target code,
plan the refactor, and implement changes.

isolation: worktree no frontmatter diz ao Claude para criar um worktree novo cada vez que este agente corre. O agente trabalha em total isolamento, e um worktree vazio elimina-se quando a execução termina.

Suporte a VCS Não-Git

Equipas em Mercurial, Perforce ou SVN não ficam de fora. O modo worktree ainda funciona, usando hooks personalizados. Regista hooks WorktreeCreate e WorktreeRemove nas tuas definições para que a lógica de isolamento do teu VCS substitua o comportamento padrão do git.

Com esses hooks em vigor, a flag --worktree e os pedidos de worktree em sessão passam pelos teus hooks em vez de chamar diretamente o git. Todo o resto do fluxo fica inalterado.

Três Padrões de Worktree que Vale a Pena Roubar

A maioria das equipas percebe a ideia básica quando a vê. O que normalmente precisam a seguir é um padrão funcional que possam copiar.

1. Hotfix sem arruinar o trabalho em funcionalidades

Estás a meio de uma branch de funcionalidade quando aparece um bug de autenticação em produção.

# Mantém a sessão de funcionalidade atual ativa
claude

# Abre uma segunda sessão isolada para o bugfix
claude --worktree hotfix-auth-timeout

Agora o hotfix pode ser entregue de forma limpa enquanto a sessão de funcionalidade mantém o seu estado, tarefas e histórico de conversa. Este é o uso mais simples e de maior valor dos worktrees e o primeiro que a maioria das equipas adota.

2. Implementações concorrentes para o mesmo refactor arriscado

Imagina que um refactor de routing tem duas formas possíveis. Uma mantém a superfície de API atual e move os internos. A outra simplifica também a API externa.

Corre as duas:

claude --worktree router-safe-path
claude --worktree router-clean-slate

Ambas as sessões podem tocar nos mesmos ficheiros porque não partilham um checkout. Revê as duas branches depois e fica com o design mais forte. Isto é muito melhor do que tentar forçar um agente a raciocinar por ambos os caminhos num único contexto.

3. Migrações em lote com sub-agentes isolados

Imagina que precisas de substituir uma API de logging em 80 ficheiros. Não queres cinco agentes a editar o mesmo checkout.

Pede a divisão explicitamente:

You: Use worktrees for agents. Split this migration into 5 batches of files.

Isso dá a cada worker:

• uma visão completa do repositório
• um lote restrito de ficheiros
• uma branch isolada
• um resultado revisável

É aqui que os worktrees deixam de ser uma funcionalidade conveniente e começam a comportar-se como infraestrutura paralela real.

Pequenas Regras que Mantêm os Worktrees Sensatos

A mecânica é fácil. Os hábitos da equipa são o que os mantém úteis:

• Nomeia worktrees pelo resultado, não apenas pelo ticket
• Apaga rapidamente worktrees vazios ou abandonados
• Usa um worktree por linha de pensamento ativa
• Mantém prefixos de branch consistentes para que a limpeza seja óbvia
• Revê diffs antes de fazer merge entre worktrees como qualquer outra branch

Se os worktrees começam a parecer confusos, geralmente não é porque há demasiados. É porque ninguém consegue dizer quais são descartáveis e quais importam.

Limpeza e Manutenção

Como um worktree é limpo depende de se houve alterações dentro dele:

• Sem alterações: O worktree e a sua branch são removidos automaticamente quando a sessão termina
• Com alterações: Claude pergunta se queres manter ou remover o worktree

Mantém as pastas de worktree fora do controlo de versão com uma linha em .gitignore:

echo ".claude/worktrees/" >> .gitignore

Worktrees a acumular? Comandos git normais listam-nos e limpam-nos:

git worktree list
git worktree prune

Quando Usar Worktrees

Regra de ouro: sempre que recorreres a uma branch separada para evitar conflitos, usa um worktree em vez disso. Tens a branch, e tens um diretório de trabalho separado junto com ela.

Lembra-te: Os worktrees transformam Claude Code de uma thread única num ambiente de desenvolvimento paralelo. Lança sessões isoladas. Despacha agentes isolados. Faz merge dos vencedores quando estiveres pronto.