Algumas semanas atrás, escrevi sobre git worktrees — o que são, como criá-los e por que são melhores do que clonar o repositório três vezes. O básico.

Mas o básico é só metade da história. Porque o Claude Code não apenas funciona com worktrees — ele tem suporte nativo para eles. Flags dedicadas, isolamento automático, integração com tmux. E a diferença entre saber que worktrees existem e saber como o Claude Code os aproveita é como ter um carro e descobrir que ele tem modo esportivo.

Boris Cherny, criador do Claude Code, publicou uma thread com cinco dicas para aproveitá-los ao máximo. Testei todos. Alguns mudaram meu fluxo de trabalho. Outros me pouparam as gambiarras que vinha fazendo desde janeiro. Vamos explorá-los.

Dica 1: --worktree — um worktree com um único flag

O fluxo clássico para trabalhar com um worktree é assim:

1
2
3

git worktree add ../meu-projeto-feature -b feature/alguma-coisa
cd ../meu-projeto-feature
claude

Três passos. Não é o fim do mundo, mas exige pensar em nomes de diretórios, lembrar a sintaxe, e depois navegar até o novo diretório. Se você faz isso cinco vezes por dia, cansa.

Claude Code reduz tudo isso a um único comando:

1

claude --worktree

E pronto. Claude cria um worktree temporário em um diretório com nome gerado automaticamente, muda para ele e inicia uma sessão ali. Quando você termina, ele limpa o worktree.

Quando eu uso isso? Sempre que quero testar algo sem contaminar minha branch atual. Experimentar com uma refatoração agressiva, explorar uma alternativa de design, fazer um spike. Se der certo, faço merge. Se não, desaparece sem deixar rastros.

É como abrir um rascunho no seu editor de texto. Sem compromisso, sem cerimônia.

Dica 2: subagentes em worktrees isolados

Se você já usa subagentes no Claude Code (com Task em um custom agent ou com o próprio agente principal delegando), sabe que eles compartilham o diretório de trabalho. Isso significa que dois subagentes podem sobrescrever arquivos, competir pelo index do git ou deixar o staging area uma bagunça.

A solução: subagentes que executam cada um no próprio worktree.

Quando um agente lança um subagente com isolamento de worktree, o Claude Code:

  1. Cria um worktree temporário para o subagente.
  2. O subagente trabalha lá, em sua própria branch.
  3. Quando ele termina, as mudanças podem ser mescladas ao worktree pai.
  4. O worktree temporário é limpo.

Explicado de forma simples: cada subagente tem sua própria estação de trabalho. Eles podem estar serrando madeira ao mesmo tempo sem arrancar os dedos uns dos outros.

O benefício não é só evitar conflitos. É que você pode paralelizar de verdade. Enviar um subagente para escrever testes enquanto outro implementa a funcionalidade. Um traduzindo documentação enquanto o outro refatora o módulo de autenticação. Sem esperas, sem bloqueios.

Dica 3: custom agents com isolation: worktree

Agora é onde as coisas ficam realmente interessantes. Os custom agents no Claude Code são definidos com um arquivo Markdown em .claude/agents/. E no frontmatter desse arquivo você pode colocar:

1
2
3
4

---
name: refatorar-modulo
isolation: worktree
---

isolation: worktree diz ao Claude Code: “toda vez que você invocar esse agente, dê automaticamente a ele o próprio worktree”. Você não precisa passar a flag --worktree. Não precisa criar nada manualmente. O isolamento faz parte da definição do agente.

Para que isso é útil? Para agentes que, por design, deveriam sempre trabalhar isolados. Alguns exemplos:

Um agente de refatoração agressiva. Você quer um agente que mova arquivos, renomeie funções e altere a estrutura de diretórios. Se fizer isso na sua branch de trabalho, qualquer erro será um desastre. Com isolation: worktree, o agente faz as mudanças em sua própria cópia. Você revisa o diff. Se aprovar, faz o merge. Se não, git worktree remove e pronto — é como se nada tivesse acontecido.

Um agente de tradução. Uso literalmente para este blog. Um agente que traduz posts para quatro idiomas, gera o frontmatter e faz os commits. Ele precisa alterar muitos arquivos ao mesmo tempo. Se trabalhasse no meu diretório de desenvolvimento, isso me atrapalharia. Com seu próprio worktree, ele traduz enquanto continuo escrevendo o próximo post.

Um agente de migração de banco de dados. Ele gera arquivos SQL, valida contra o schema atual e executa testes. Tudo em um worktree isolado, onde pode quebrar coisas sem consequências.

A chave é que isolation: worktree transforma o isolamento em um atributo do agente, e não em uma decisão que você toma a cada vez que o executa. É a diferença entre um carro que tem airbags e um carro onde você precisa se lembrar de ativar a segurança toda vez que o liga.

Dica 4: --tmux — sessões realmente paralelas

Até agora, “paralelo” significava abrir várias abas de terminal manualmente. Terminal 1 para um worktree, terminal 2 para outro, terminal 3 para o principal. Funciona, mas é artesanal.

--tmux automatiza isso:

1

claude --worktree --tmux

Claude Code cria o worktree, inicia a sessão em um painel do tmux e retorna o controle ao seu terminal. Você pode iniciar três, quatro, cinco sessões assim:

1
2
3

claude --worktree --tmux  # sessão 1: implementar funcionalidade A
claude --worktree --tmux  # sessão 2: escrever testes para o módulo B
claude --worktree --tmux  # sessão 3: refatorar o CLI

Cada uma em seu próprio worktree, cada uma em seu painel do tmux, todas executando em paralelo. Você alterna entre elas com Ctrl-b + número da janela (ou seu atalho favorito do tmux).

Isso é um divisor de águas para sprints de produtividade. Imagine uma segunda-feira de manhã: você abre seu backlog, seleciona três tarefas independentes e lança três agentes. Enquanto um escreve testes, outro implementa uma funcionalidade e um terceiro atualiza a documentação. Você supervisiona, revisa os diffs quando eles terminam e mescla.

Não é ficção científica. É só uma flag.

Dica 5: quando NÃO usar worktrees

Tão importante quanto saber quando usar worktrees é saber quando não usá-los. Boris Cherny fala explicitamente sobre isso, e eu concordo.

Não use worktrees para tarefas sequenciais. Se a tarefa B depende do resultado da tarefa A, você não ganha nada paralelizando. Na verdade, você perde: agora precisa mesclar A antes de B poder começar, o que adiciona uma etapa que não existia se você tivesse simplesmente trabalhado na mesma branch.

Não use worktrees para mudanças pequenas. Um fix de uma linha não justifica a cerimônia de criar um worktree, mesmo que --worktree a reduza a uma flag. O overhead mental de ter múltiplos diretórios ativos não compensa se a mudança leva trinta segundos.

Não use worktrees se as alterações tocarem os mesmos arquivos. Se as funcionalidades A e B vão modificar o mesmo config.toml ou o mesmo routes.py, você inevitavelmente acabará com um conflito ao fazer o merge. Os worktrees brilham quando as funcionalidades são ortogonais — afetam áreas diferentes do código.

Não use worktrees sem um plano. Lançar cinco agentes paralelos “pra ver o que sai” parece produtivo. Na prática, você acaba com cinco branches em estados diferentes, cinco diffs para revisar e cinco merges potencialmente conflitantes. A paralelização funciona quando há intenção por trás: tarefas claras, independentes e com critério de aceitação definido.

A regra de ouro: se você consegue descrever cada tarefa em uma frase e nenhuma depende da outra, use worktrees. Caso contrário, trabalhe em série.

O fluxo completo: da teoria para sua segunda-feira de manhã

Para não ficar abstrato, este é o fluxo que uso agora quando tenho várias tarefas independentes no backlog:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# 1. Revise o backlog e escolha tarefas independentes
linear issue list --team PROD --state unstarted --sort priority --no-pager

# 2. Inicie um agente por tarefa, cada um em seu worktree + tmux
claude --worktree --tmux  # "implemente a funcionalidade X, crie testes"
claude --worktree --tmux  # "refatore o módulo Y"
claude --worktree --tmux  # "traduza os posts pendentes"

# 3. Vá revisando à medida que terminam (tmux panels)
# Ctrl-b + 1, 2, 3 para trocar entre sessões do tmux

# 4. Revise o diff de cada worktree
cd /tmp/claude-worktree-abc123  # ou onde Claude criou o worktree
git diff main

# 5. Se o diff for legal, push + PR
git push -u origin feature/qualquer-coisa
# PR, review, merge

# 6. Limpeza (ou deixe o Claude limpar automaticamente)
git worktree list  # veja o que ainda está ativo

O que antes levava uma manhã inteira — três funcionalidades desenvolvidas, testadas e com PR — agora eu consigo fazer antes de sair pra uma cerveja.

A evolução: do manual para o nativo

Quando comecei a usar worktrees há algumas semanas, tudo era manual. git worktree add, cd, claude, abrir outro terminal, repetir. Funcionava, mas parecia montar uma barraca toda vez que queria sair pro quintal.

Com --worktree, isolation: worktree e --tmux, Claude Code tornou os worktrees em algo que desaparece. Você não pensa neles. Não os gerencia. Apenas diz “trabalhe em paralelo” e as ferramentas cuidam do resto.

É a mesma evolução que vimos com contêineres: primeiro configurávamos LXC manualmente, depois o Docker abstraiu tudo, e agora nem pensamos nos namespaces do kernel. Os worktrees estão nessa fase de abstração. Git lançou as bases em 2015. Onze anos depois, o tooling finalmente os torna invisíveis.

E isso, no fim, é o que queremos de qualquer ferramenta: que faça seu trabalho e saia do nosso caminho.

TL;DR: O Claude Code tem cinco funcionalidades essenciais para worktrees: --worktree (criação e entrada com um flag), subagentes isolados (cada um em seu worktree), isolation: worktree em custom agents (isolamento por design), --tmux (sessões paralelas automatizadas), e saber quando não usá-los. O resultado: paralelismo real sem gestão manual. Os worktrees deixam de ser uma feature do git que ninguém utiliza para se tornarem a infraestrutura invisível do seu fluxo de trabalho com agentes.