Sabe aquela sensação de duas sessões do Claude Code editando o mesmo arquivo ao mesmo tempo — e você assistindo sua feature, que você construiu com tanto cuidado, ser sobrescrita aos poucos por uma branch de bugfix? Pois é. Já passei por isso mais de uma vez, e é de tirar do sério.
Sou o Hanks, e depois de rodar workflows de agente paralelo em repo de produção real, posso te dizer: a era das gambiarras acabou. Desde o Claude Code v2.1.49 (lançado em 19 de fevereiro de 2026), o suporte nativo a git worktree chegou na CLI — e isso muda completamente como você roda agentes paralelos. Deixa eu te mostrar exatamente como funciona, como configurar, e onde os gotchas estão escondidos.
O que o suporte a worktree do Claude Code faz — entregue na v2.1.49 (fev/2026)
Git worktrees não é conceito novo — o comando deixa um único repositório suportar múltiplas working trees ao mesmo tempo, então você dá checkout em mais de uma branch simultaneamente sem duplicar o repo. O que o Claude Code v2.1.49 acrescenta é suporte nativo first-class, pra você não precisar montar essa estrutura na mão.
A mecânica central é essa: cada comando claude --worktree nome cria uma branch isolada e um diretório dedicado em .claude/worktrees/nome/. Cada agente pega seu próprio estado de filesystem. Eles não pisam um no outro. E o ponto crítico — todos os worktrees compartilham o mesmo histórico .git e as mesmas conexões de remote, então você não tá duplicando o repo inteiro.
A feature chegou na CLI, no app desktop, nas extensões de IDE (VS Code e JetBrains) e na interface web. O app desktop, na real, já tinha suporte a worktree antes da v2.1.49 — a CLI agora alcançou e fechou o ciclo.
O que é criado a cada chamada de claude --worktree nome****:
| Objeto | Caminho / Nome | Pra que serve |
|---|---|---|
| Diretório de trabalho | .claude/worktrees// | Estado isolado de filesystem pro agente |
| Branch git | worktree- | Branch dedicada, derivada do remote padrão |
| .git database compartilhado | (raiz do repo) | Histórico completo compartilhado entre worktrees — sem duplicação |
| Auto-cleanup | ao sair da sessão | Removido se não tem mudança; pergunta se tem commit |
Como configurar e usar worktrees
Agente único
O caminho mais simples: passa --worktree (ou -w) com um nome ao iniciar o Claude Code.
# Cria .claude/worktrees/feature-auth/ com a branch worktree-feature-auth
claude --worktree feature-auth
# Omite o nome — o Claude gera um aleatório automaticamente
claude --worktree
# Adiciona --tmux pra rodar numa sessão tmux própria — continua rodando se você fechar o terminal
claude --worktree feature-auth --tmuxVocê também consegue acionar o modo worktree no meio da sessão. Só pede pro Claude: "trabalha em um worktree" e ele cria um na hora e migra sua sessão pra dentro dele. Útil quando você percebe na metade do caminho que suas mudanças precisam de isolamento.
Pro app desktop: vai pra aba Code, ativa o worktree mode, e cada nova sessão pega seu worktree isolado automaticamente. Sem flag.
Vários agentes em paralelo
Aqui é onde o negócio fica realmente forte. Abre terminais separados e dispara:
# Terminal 1 — construindo a feature de auth
claude --worktree task-auth
# Terminal 2 — corrigindo um bug de produção em paralelo
claude --worktree bugfix-payment
# Terminal 3 — refactor longo, roda em background via tmux
claude --worktree refactor-api --tmuxCada sessão pega seus próprios arquivos, sua própria branch e seu próprio contexto. Os agentes ficam totalmente independentes — sem estado de arquivo compartilhado, sem merge conflict no meio da sessão, sem um pisar no trabalho do outro.
Sessão única vs worktrees paralelos — visão geral:
| Dimensão | Sessão única | Worktrees paralelos |
|---|---|---|
| Isolamento de arquivo | Nenhum — diretório de trabalho compartilhado | Total — cada agente com seu diretório |
| Gerenciamento de branch | Stash manual obrigatório | Automático — uma branch por worktree |
| Merge conflict no meio da sessão | Comum quando as tarefas se sobrepõem | Impossível dentro de uma sessão |
| Histórico git | Uma branch compartilhada | .git DB compartilhado, branches independentes |
| Cleanup | Manual | Auto se não tem mudança; pergunta se tem commit |
Pra coordenação automatizada entre sessões paralelas — task list compartilhada, mensagem entre agente — isso é outra ferramenta: Claude Code agent teams, que roda cada worker no seu próprio context window independente.
Subagents, Custom Agents & VCS não-Git
Subagents
Subagents suportam isolation: "worktree" pra trabalhar num git worktree temporário com cleanup automático. Quando o Claude spawna subagents pra distribuir tarefa, cada um pode pegar seu próprio ambiente isolado. Só pede: "usa worktrees pros seus agentes" — e o Claude cuida do resto. Especialmente forte pra mudança em batch grande e migração, onde os agentes escrevem em partes diferentes do codebase ao mesmo tempo.
Custom Agents
Pra workflow que se repete, declara o isolamento via worktree direto no frontmatter de um custom agent:
---
name: refactor-agent
description: Handles large-scale refactoring tasks
isolation: worktree
---Toda vez que esse agent roda, ele pega seu worktree próprio automaticamente — sem precisar de flag manual. Salva as definições de agent em .claude/agents/ pra compartilhar com o time.
VCS não-Git (SVN, Perforce, Mercurial, etc.)
O isolamento via worktree funciona com git por padrão. Pra outros sistemas de controle de versão, os hook events WorktreeCreate e WorktreeRemove deixam você fornecer a lógica de criação e cleanup customizada. Quando configurados, esses hooks substituem o comportamento padrão do git quando você usa --worktree — seu script recebe um payload JSON via stdin com o nome do worktree, cria o ambiente como você precisar, e imprime o caminho absoluto do worktree no stdout. O Claude inicia a sessão nesse diretório. O mesmo padrão funciona pra setups customizados de git, tipo projetos que precisam de localização customizada do worktree fora do .claude/worktrees/ pra frameworks como Laravel Valet ou Herd.
Define os hooks em .claude/settings.json:
{
"hooks": {
"WorktreeCreate": [
{
"hooks": [
{
"type": "command",
"command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/worktree-setup.sh",
"timeout": 30
}
]
}
],
"WorktreeRemove": [
{
"hooks": [
{
"type": "command",
"command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/worktree-teardown.sh",
"timeout": 15
}
]
}
]
}
}Uma nuance que vale saber: hooks de WorktreeRemove hoje são informacionais — não conseguem bloquear a remoção. Se seu workflow precisa de worktree persistente entre sessões, que não pode ser destruído ao sair, essa issue aberta no GitHub tá rastreando uma proposta de mecanismo exit code 2 pro WorktreeRemove, espelhando o padrão que já existe no WorktreeCreate.
Cleanup e Gotchas
O cleanup é automático, mas condicional. Quando uma sessão termina sem mudança, o worktree e a branch são removidos automaticamente. Quando existem mudança ou commit, o Claude te pergunta: manter (preserva diretório + branch pra depois) ou remover (apaga os dois, descarta o trabalho não comitado).
Pra fazer cleanup manual fora de uma sessão do Claude:
# Lista todos os worktrees ativos
git worktree list
# Remove um worktree específico
git worktree remove .claude/worktrees/feature-auth
# Limpa metadata órfã depois de um delete forçado
git worktree pruneRoda a instalação de dependência por worktree. Cada worktree novo é um checkout do zero — node_modules, virtual environment, build artifact, nada disso é carregado. Roda o setup do projeto dentro de cada worktree antes de esperar o Claude buildar ou testar:
cd .claude/worktrees/feature-auth
npm install # ou: pip install -r requirements.txt, bundle install, etc.Adiciona .claude/worktrees/ ao .gitignore. Esquecer disso faz os diretórios de worktree aparecerem como arquivos untracked no seu repo principal. Git worktrees só duplicam arquivo tracked — qualquer coisa no seu .gitignore também não vai pros worktrees novos:
echo ".claude/worktrees/" >> .gitignore**Auto-criação indesejada no Desktop? **Uma issue conhecida no tracker do GitHub documenta que o app desktop cria um worktree aleatório pra cada sessão nova, sem toggle pra desativar no momento. O workaround: usa a CLI com claude (sem flag --worktree) pra operar direto no checkout principal, ou roda /permissions e adiciona "EnterWorktree" na deny list pra evitar entrada automática em worktree nas sessões da CLI.
Artigos relacionados
Claude AI: Acesso Gratuito 2026
Windsurf: Preços e Planos 2026
