Git worktree no Claude Code: sessões paralelas

Encontra informações práticas sobre como trabalhar com o Ailoot na documentação.

O que é um git worktree no Claude Code#

Lançar vários agentes em paralelo na mesma pasta é o problema básico do vibe-coding à velocidade de 2026. Os agentes de IA escrevem código mais depressa do que uma pessoa consegue acompanhar quem está a mexer em quê. Sem isolamento dos ficheiros, lançar duas sessões paralelas do Claude Code no mesmo diretório acaba com uma sessão a sobrepor o trabalho da outra.

O Git worktree resolve isto ao nível do sistema de ficheiros. Tem um diretório principal onde trabalha. O comando claude --worktree feature-auth cria a pasta .claude/worktrees/feature-auth/ num ramo separado e inicia aí o Claude Code. Os ficheiros ficam isolados. As alterações de uma sessão não são visíveis na outra até as integrar explicitamente.

A documentação oficial da Anthropic descreve-o desta forma:

Uma dica para fazer uma autoavaliação: se alguma vez recebeu um commit em que metade dos ficheiros era trabalho de outra pessoa, precisa de um worktree.

Em que difere o git worktree de um ramo normal#

O fluxo normal do Git: está no ramo main e executa git checkout feature-x — o Git sobrepõe os ficheiros da cópia de trabalho. Um npm run dev em execução deixa de funcionar porque o package.json foi alterado por baixo dele. Guarda as alterações ainda não commitadas com git stash e espera que o IDE volte a indexar os ficheiros. Muda novamente de ramo e tudo volta a ser sobreposto, pelo que tem de voltar a fazer stash e pop.

O Git worktree oferece outra opção: em vez de alternar uma pasta entre ramos, cria uma segunda pasta para outro ramo. O comando git worktree add ../project-feature-x feature-x cria o diretório ../project-feature-x/ com os ficheiros do ramo feature-x. O seu main permanece na pasta original e o servidor de desenvolvimento continua em execução.

Anteriormente, era necessário configurar manualmente o modo worktree no Claude Code: git worktree add, depois cd e, por fim, claude — repetindo o processo em cada terminal. A opção --worktree (também -w) faz os três passos com um único comando.

Iniciar a primeira sessão paralela: a opção --worktree#

Exemplo mínimo. Abra o primeiro terminal na raiz do projeto:

claude --worktree feature-auth

O Claude Code faz três coisas:

1. Cria .claude/worktrees/feature-auth/ com uma cópia de origin/HEAD (normalmente o seu ramo predefinido).
2. Cria um novo ramo worktree-feature-auth.
3. Inicia a sessão nesta pasta.

Abra um segundo terminal na mesma pasta raiz do repositório:

claude --worktree bugfix-123

Feito. Duas sessões do Claude Code, ficheiros diferentes no disco e ramos Git diferentes. Se escrever autenticação na primeira e corrigir um teste com falhas na segunda, não podem interferir fisicamente uma com a outra.

Se não quiser escrever um nome, o Claude inventa um:

claude --worktree
# → cria algo como .claude/worktrees/bright-running-fox/

Uma dica para quem está a começar com Git: adicione .claude/worktrees/ a .gitignore. Caso contrário, ao executar git status na pasta principal, verá o conteúdo de todos os worktrees como ficheiros não rastreados:

# .gitignore
.claude/worktrees/

Um problema a evitar: antes do primeiro lançamento de --worktree num diretório novo, entre nele com um claude normal (sem a opção) e aceite a janela de confiança do espaço de trabalho. Se não o fizer, a opção falha com um erro “trust not accepted” — incluindo se a combinar com -p para o modo headless.

Onde ficam os worktrees e como os encontrar#

A localização predefinida é fixa: .claude/worktrees/<value>/ na raiz do repositório. Se o seu projeto estiver em ~/dev/my-app/, o worktree feature-auth ficará em ~/dev/my-app/.claude/worktrees/feature-auth/.

Para configurações fora do comum (por exemplo, se quiser o worktree fora do repositório), existe o hook WorktreeCreate — falaremos mais sobre ele abaixo, na secção sobre SVN e Mercurial.

Numa sessão do Claude, pode mudar para outro worktree existente. Basta dizer no chat: “muda para .claude/worktrees/bugfix-123” e o Claude chamará a ferramenta EnterWorktree. A pasta atual permanecerá intacta — pode voltar a ela da mesma forma.

O comando padrão do Git apresenta uma lista de todos os worktrees, incluindo o principal e os criados manualmente:

git worktree list

O resultado será semelhante a este:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Copiar .env e segredos: o ficheiro .worktreeinclude#

Quando --worktree cria uma pasta nova, esta recebe apenas o que está commitado no Git. .env, com chaves de API, e .env.local, com configuração local, estão em .gitignore, por isso não ficam no worktree. E logo o primeiro npm run dev falha com “MISSING DATABASE_URL”.

A solução improvisada é copiar manualmente .env após cada utilização de --worktree. Funciona uma vez, depois acaba por ser esquecida. A solução da Anthropic é um ficheiro .worktreeinclude na raiz do projeto com a lista dos ficheiros ignorados pelo Git a copiar automaticamente para cada worktree novo.

Crie um ficheiro .worktreeinclude na raiz do repositório:

.env
.env.local
config/secrets.json

A sintaxe é igual à de .gitignore. Pode usar padrões glob:

.env*
*.local
config/*.json
.vscode/settings.json

A Anthropic apresenta uma regra clara para evitar acidentes:

Por outras palavras, não pode copiar package.json por acidente através de .worktreeinclude — não está em .gitignore. É seguro incluir quaisquer padrões nesse ficheiro.

O mesmo .worktreeinclude funciona em três modos: --worktree manual, worktrees automáticos para subagentes (ver abaixo) e sessões da aplicação de ambiente de trabalho do Claude.

Worktree a partir de um pull request para revisão de código#

Um cenário normal de revisão de código: um colega enviou um PR; precisa de inspecionar o código, executar testes e deixar um comentário. Com um git checkout pull/1234/head normal, volta a mudar a cópia de trabalho e interrompe a sessão ativa.

Com a opção --worktree, basta um comando:

claude --worktree "#1234"

O que acontece: o Claude Code executa git fetch origin pull/1234/head, cria um worktree em .claude/worktrees/pr-1234/ e faz checkout do ramo do PR. A sessão inicia-se. Pode pedir-lhe imediatamente para “ler as diferenças, executar os testes e encontrar erros de lógica” — enquanto o Claude trabalha, a sua sessão principal em main continua em execução.

A sintaxe alternativa é o URL completo do pull request:

claude --worktree https://github.com/OWNER/REPO/pull/1234

Utilização num projeto real: combinar claude --worktree "#N" com o seu próprio subagente de revisão de código permite obter uma revisão automática num ou dois minutos. Lance-o em segundo plano, continue o seu trabalho na janela principal e volte ao resultado através de claude agents.

Ramo de base: worktree.baseRef para fresh ou head#

A definição predefinida é a seguinte: todos os worktrees novos começam em origin/HEAD. A vantagem é começar de forma limpa, garantindo que corresponde ao que o CI verá. A desvantagem é que as alterações não commitadas ou vários commits locais posteriores ao remoto no ramo atual não serão incluídos no novo worktree.

Para iniciar um worktree no commit HEAD local atual, adicione a .claude/settings.json ou às definições globais:

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

Agora claude --worktree experimental-feature parte do HEAD local atual. Serve quando a funcionalidade já tem commits locais não enviados; não inclui edições controladas ainda sem commit. Se o subagente precisar delas, preserve e transfira explicitamente as alterações e examine o diff de destino; não confunda com .worktreeinclude, que trata de ficheiros locais ignorados.

A definição aceita exatamente dois valores: "fresh" (= origin/HEAD) e "head" (= HEAD local). Não aceita referências arbitrárias, como "feature-branch", nem hashes de commits — trata-se de uma restrição deliberada para evitar uma explosão combinatória de opções.

Isolar subagentes automaticamente: isolation: worktree#

Quando diz ao Claude “inicia três subagentes: um lê a base de dados, o segundo analisa a API e o terceiro verifica os testes”, os três trabalham na sua cópia de trabalho por predefinição. Se dois deles escreverem no mesmo ficheiro ao mesmo tempo, há um conflito. A solução é atribuir automaticamente a cada um o seu próprio worktree.

Método 1: peça-o verbalmente. Escreva ao Claude na conversa:

Utilize worktrees para os seus agentes.

O Claude aplicará o isolamento a todos os subagentes seguintes nesta sessão.

Método 2: defina-o explicitamente no próprio subagente. No ficheiro do subagente (por exemplo, .claude/agents/code-reviewer.md), adicione um campo ao cabeçalho:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

É um revisor meticuloso. Leia as alterações e procure erros de lógica...

A partir daí, cada lançamento deste subagente recebe um worktree temporário em .claude/worktrees/. Se o subagente não tiver escrito nada, a pasta é eliminada automaticamente quando termina. Se houver alterações não commitadas, o Claude pergunta se as quer manter ou remover.

O ramo de base para os worktrees dos subagentes é igual ao de --worktree: por predefinição, origin/HEAD; com worktree.baseRef: head, o HEAD local.

Matriz de decisão: worktree, /bg, subagente ou Agent View#

Combinações típicas:

• “2 funcionalidades em paralelo, manualmente” — dois terminais, cada um a executar claude --worktree. O caso mais simples.
• “Inicia uma refatoração durante a noite; vou fechar a aplicação” — /bg + /goal com uma condição de conclusão. A sessão funciona independentemente da sua janela.
• “Uma instrução, três investigações em paralelo” — três subagentes com isolation: worktree. Cada um no seu ambiente isolado.
• “O que está a funcionar neste momento?” — claude agents. Um painel de controlo de todas as sessões, com filtros “em execução”, “bloqueado” e “concluído”.

5 problemas comuns ao trabalhar com worktrees#

1. Iniciou um worktree, falta .env e nada funciona. O problema mais comum. Um worktree é um checkout novo sem os ficheiros ignorados pelo Git. A solução é adicionar um ficheiro .worktreeinclude com .env* e as configurações locais necessárias assim que configurar o modo worktree. Confirme que o ficheiro está na raiz do repositório, não em .claude/.

2. Quer mudar para o ramo principal, executa cd para a raiz e perde as alterações não commitadas no worktree. A pasta raiz e o worktree são duas cópias de trabalho diferentes. Regressou com cd; as alterações no worktree mantiveram-se no mesmo sítio — não desapareceram. Mas, se se confundiu e executou git stash na pasta principal, pensando que estava no worktree, o stash será criado no ramo principal, e não naquele que esperava.

3. Iniciou 5 sessões em paralelo e já não se lembra do que cada uma está a fazer. A documentação da Anthropic avisa explicitamente que a maioria dos programadores não consegue gerir cognitivamente mais de 2–3 sessões. Um sinal de sobrecarga é abrir o Agent View e não conseguir dizer imediatamente o que cada agente está a fazer. Limite-se a duas sessões simultâneas. Se a tarefa exigir mais, deve ser coordenada através de /goal + subagentes, e não manualmente.

4. Os worktrees iniciados com -p (headless) não são limpos automaticamente. O comando claude --worktree feature-x -p "do thing" não apresenta uma pergunta interativa ao sair, por isso não há um momento em que o Claude pergunte “remover o worktree?”. Estes worktrees acumulam-se. Limpe-os manualmente: git worktree remove .claude/worktrees/feature-x. Ou use um script cron para remover tudo o que tenha mais de 7 dias.

5. Janela de confiança numa pasta nova. Se abrir o repositório pela primeira vez e executar imediatamente claude --worktree, o comando falhará. Execute claude sem opções, aceite a confiança no espaço de trabalho e saia — depois, --worktree funcionará. Isto é intencional para que o Claude não tenha acesso ao projeto de outra pessoa sem o consentimento do utilizador.

Limpeza: o que é eliminado automaticamente#

A lógica de limpeza depende do que fez no worktree e de como iniciou a sessão. A documentação da Anthropic enumera três cenários:

Cenário 1: entrou, não fez nada e saiu — o worktree foi removido.

Cenário 2: fez algum trabalho, mas não o commitou — ao sair, o Claude pergunta “manter ou remover?”. “Manter” guarda a pasta e o ramo para mais tarde. “Remover” elimina o diretório juntamente com as alterações não commitadas e os novos commits. É uma operação destrutiva — não clique em “remover” por hábito.

Cenário 3: iniciou com -p (headless) e o comando terminou e saiu. O worktree permanece. Limpe-o manualmente:

git worktree remove .claude/worktrees/feature-x

Além disso, a limpeza em segundo plano remove automaticamente os worktrees de subagentes e das sessões /bg quando têm mais dias do que o valor de cleanupPeriodDays (uma definição que normalmente é de 30 dias por predefinição) e não têm trabalho por guardar. Os worktrees de --worktree não são afetados pela limpeza automática — são da sua responsabilidade.

Alternativas para SVN, Perforce e Mercurial: o hook WorktreeCreate#

Se o repositório usar Subversion ou Mercurial, a opção --worktree não funcionará diretamente. A Anthropic disponibiliza um ponto de extensão através de dois hooks: WorktreeCreate (cria uma cópia isolada) e WorktreeRemove (remove-a).

Exemplo de hook SVN da documentação oficial:

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

O hook lê o nome do worktree através de stdin ({ "name": "feature-auth" }), executa svn checkout para um diretório previamente determinado e imprime o caminho em stdout — o Claude Code utiliza-o como diretório de trabalho para a nova sessão.

Uma ressalva importante: ao usar um hook próprio, o .worktreeinclude não é utilizado. Se precisar de .env ou de outros ficheiros ignorados pelo Git na nova pasta, copie-os no próprio script do hook.

O que se segue: três mecanismos paralelos relacionados#

O worktree proporciona isolamento de ficheiros. /bg proporciona isolamento de contexto. Os subagentes proporcionam isolamento de tarefas. Cada mecanismo resolve um problema por si só. Em conjunto, permitem trabalhar em três a cinco tarefas em paralelo sem colapso cognitivo. Estas são as competências que estão na base do vibe-coding avançado em 2026.

Este tema continua naturalmente em três assuntos relacionados: como configurar um agente autónomo com /goal e Agent View, como criar os seus próprios subagentes para as suas tarefas e como lançar centenas de agentes através de Dynamic Workflows.

Abra o Ailoot.