# Git worktree no Claude Code: sessões paralelas

> Como usar --worktree, .worktreeinclude, worktree.baseRef e o isolamento de subagentes. Diferenças em relação aos ramos, limpeza de worktrees e erros comuns.

Source: https://ailoot.ai/blog/pt-pt/claude-code-git-worktree/
Canonical: https://ailoot.ai/blog/pt-pt/claude-code-git-worktree/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-045
Revision: sha256-b8b1d9920279628ad83f25b550e52f4c2c67a6f557c9810d2041e03041b80e32




[Encontra informações práticas sobre como trabalhar com o Ailoot na documentação](https://ailoot.ai/docs/).

## O que é um git worktree no Claude Code

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

Um Git worktree é um diretório de trabalho separado para outro ramo do mesmo repositório. O comando `claude --worktree <name>` cria automaticamente um worktree em `.claude/worktrees/<name>/` e inicia o Claude Code nesse diretório. Dois terminais → duas sessões → ficheiros diferentes no disco, sem interferência. Está disponível de origem no Claude Code v2.0+ e pode ser configurado através de `.worktreeinclude` para segredos e de `worktree.baseRef` para escolher o ramo de base.

</div>

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:

<figure>
<blockquote>
<p>Executar cada sessão do Claude Code no seu próprio worktree significa que as edições numa sessão nunca afetam os ficheiros de outra. Pode desenvolver uma funcionalidade num terminal e corrigir um erro noutro.</p>
</blockquote>
<figcaption>— Anthropic Docs, https://code.claude.com/docs/en/worktrees</figcaption>
</figure>

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

Um `git checkout` normal muda a cópia de trabalho na mesma pasta — os ficheiros antigos desaparecem do disco até regressar ao ramo. O `git worktree add` cria uma **segunda pasta** para outro ramo, ao lado da primeira. Os dois ramos existem no disco ao mesmo tempo; passa de um para o outro com um simples `cd`. Nos bastidores, há um único repositório `.git`, com histórico e remoto partilhados. Apenas várias cópias de trabalho.

</div>

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.

| Parâmetro | Ramo `git checkout` | `git worktree add` |
|----|----|----|
| Ficheiros da cópia de trabalho | Sobrepostos | Surgem numa pasta nova |
| Trabalho em paralelo em dois ramos | Não | Sim |
| Alterações não commitadas | É necessário `git stash` | Não é preciso fazer nada |
| Velocidade de mudança | Depende da dimensão das diferenças | Basta um `cd` |
| Espaço em disco | 1× | N× (uma cópia dos ficheiros por ramo) |

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`

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

O comando `claude --worktree feature-auth` cria um worktree em `.claude/worktrees/feature-auth/`, cria o ramo `worktree-feature-auth` a partir de `origin/HEAD` e inicia o Claude Code nesse local. Não é necessário executar manualmente `git worktree add` nem `cd`. No terminal ao lado, repita o processo com um nome diferente para obter duas sessões independentes. Se omitir o nome (`claude --worktree`), o Claude gera um nome aleatório, como `bright-running-fox`.

</div>

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

```bash
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:

```bash
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:

```bash
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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

Por predefinição, todos os worktrees ficam em `.claude/worktrees/<name>/`, junto à raiz do repositório. Para ver a lista, execute `git worktree list`. Para entrar manualmente num worktree, use `cd .claude/worktrees/feature-auth`. Para mudar de worktree numa sessão do Claude, peça-lhe para “mudar para outro worktree”; ele usa a ferramenta incorporada EnterWorktree. O worktree anterior permanece intacto no disco.

</div>

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:

```bash
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`

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

Um worktree é um checkout novo. Os ficheiros de `.gitignore` (`.env`, `.env.local`, configurações locais) não estão na nova pasta. Sem eles, `npm run dev` ou `prisma db push` não funcionam. O ficheiro `.worktreeinclude` na raiz do projeto usa a sintaxe de `.gitignore` e indica ao Claude Code que ficheiros ignorados pelo Git deve copiar automaticamente para cada worktree novo. É tido em conta com `--worktree`, nos worktrees de subagentes e nas sessões da aplicação de ambiente de trabalho.

</div>

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:

<figure>
<blockquote>
<p>O ficheiro usa a sintaxe de gitignore. Só são copiados os ficheiros que correspondem ao padrão e que também são ignorados pelo Git. Os ficheiros rastreados pelo Git nunca são duplicados.</p>
</blockquote>
<figcaption>— Anthropic Docs, https://code.claude.com/docs/en/worktrees</figcaption>
</figure>

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

O comando `claude --worktree "#1234"` obtém o pull request \#1234 de origin e cria um worktree em `.claude/worktrees/pr-1234/` com o ramo do PR. Pode fornecer o URL completo — `claude --worktree https://github.com/OWNER/REPO/pull/1234`. É útil para rever código: abra o PR na sua própria pasta e o Claude pode executar testes, ler registos e escrever um comentário, enquanto o repositório principal permanece intacto.

</div>

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:

```bash
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:

```bash
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`

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

Por predefinição, um worktree parte de `origin/HEAD` — o commit mais recente sincronizado com o remoto. É um início seguro e “limpo”. Para incluir commits locais ainda não enviados, defina `worktree.baseRef: "head"`. HEAD identifica um commit; edições controladas sem commit permanecem na cópia original e exigem transferência explícita separada. É útil quando um subagente precisa de trabalhar com base na sua funcionalidade atual sem mudar para main. Só aceita `fresh` ou `head`; não são suportadas referências arbitrárias.

</div>

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:

```json
{
  "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`

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

Um subagente no Claude Code é um agente especializado que executa uma tarefa (revisão de código, refatoração, investigação). Se iniciar vários subagentes em paralelo a partir de uma sessão, todos trabalham na mesma pasta por predefinição e podem sobrepor os ficheiros uns dos outros. Adicione `isolation: worktree` ao cabeçalho do subagente para atribuir a cada um um worktree temporário, que será removido de forma limpa no final se não tiver feito nenhum commit.

</div>

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:

```yaml
---
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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

Quatro mecanismos do Claude Code que são muitas vezes confundidos. Worktree é **isolamento de ficheiros** (disco). `/bg` é uma **sessão em segundo plano** (contexto e tokens). Subagente é um **agente especializado para uma única tarefa** (instruções e ferramentas). Agent View é um **painel de controlo de todas as sessões** (IU). Podem ser combinados: `/bg` cria automaticamente um worktree, um subagente com `isolation: worktree` começa num worktree temporário e o Agent View mostra os três como linhas numa única lista.

</div>

| Ferramenta | O que isola | Quando utilizar |
|----|----|----|
| `claude --worktree <name>` | Ficheiros (pasta e ramo separados) | Quer manter manualmente N sessões em paralelo em terminais diferentes |
| `/bg` (ou `Ctrl+B`) | Contexto e tempo | Uma tarefa demorada que não deve bloquear a janela atual. Um worktree é criado nos bastidores |
| Subagente com `isolation: worktree` | Ficheiros dentro de uma sessão | Uma instrução atribui trabalho a N agentes e precisa de impedir que se sobreponham uns aos outros |
| `claude agents` (Agent View) | Nada, é uma IU | Quer ver todas as sessões em execução / pausadas / concluídas num único painel |
| `/goal` | Gestão da autonomia | Quer que o Claude trabalhe até se verificar uma condição sem lhe dar instruções entre turnos |

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

Os problemas mais comuns: esquecer-se de `.worktreeinclude` e ficar com um ambiente que não funciona; confundir um worktree com um ramo normal e perder alterações não commitadas; manter mais de 5 sessões paralelas e esquecer-se do que está onde; não configurar `cleanupPeriodDays` e deixar as pastas abandonadas acumularem-se; e esquecer-se da janela de confiança num diretório novo, fazendo com que `--worktree` falhe com um erro.

</div>

**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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

Um worktree criado com `--worktree` sem alterações (sem commits, ficheiros não rastreados ou alterações por commitar) é removido automaticamente ao sair. Se houver alterações, o Claude pergunta. Os worktrees de subagentes e de `/bg` são removidos automaticamente quando expira o prazo `cleanupPeriodDays` nas definições, desde que estejam limpos. Os worktrees de `-p` não são limpos de todo — remova-os manualmente com `git worktree remove`.

</div>

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:

<figure>
<blockquote>
<p>Se o worktree não tiver alterações por commitar, ficheiros não rastreados ou novos commits, o worktree e o respetivo ramo são removidos automaticamente ao sair da sessão. Se a sessão tiver um nome, o Claude pergunta em vez de remover, para que possa guardar o worktree para mais tarde.</p>
</blockquote>
<figcaption>— Anthropic Docs, https://code.claude.com/docs/en/worktrees</figcaption>
</figure>

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:

```bash
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`

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

O modo worktree usa `git worktree` por predefinição. Para SVN, Perforce, Mercurial e outros sistemas de controlo de versões, pode ligar o seu próprio mecanismo através dos hooks `WorktreeCreate` e `WorktreeRemove` nas definições do Claude Code. O hook recebe o nome por stdin, tem de imprimir o caminho para o diretório criado e terminar com o código 0. Quando usa um hook próprio, o `.worktreeinclude` não é processado — tem de copiar os ficheiros locais no próprio hook.

</div>

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:

```json
{
  "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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Principal conclusão desta secção">

Principal conclusão

O worktree proporciona isolamento de ficheiros. `/bg` proporciona isolamento de contexto e tokens. O subagente proporciona isolamento de tarefas e ferramentas. `/goal` proporciona autonomia até se verificar uma condição. Cada um resolve um problema por si só. Em conjunto, permitem manter 3–5 tarefas em paralelo sem colapso cognitivo. A seguir, faz sentido explorar os guias relacionados com o modo autónomo, subagentes personalizados e fluxos de trabalho dinâmicos através das ligações abaixo.

</div>

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](https://ailoot.ai/blog/pt-pt/claude-code-goal-agent-view/), [como criar os seus próprios subagentes para as suas tarefas](https://ailoot.ai/blog/pt-pt/claude-code-subagents/) e [como lançar centenas de agentes através de Dynamic Workflows](https://ailoot.ai/blog/pt-pt/claude-code-dynamic-workflows/).

<div class="section" role="doc-bibliography" aria-label="Fontes">

### Fontes

- [Run parallel sessions with worktrees - Claude Code Docs](https://code.claude.com/docs/en/worktrees)
- [Create custom subagents - Claude Code Docs](https://code.claude.com/docs/en/sub-agents)
- [Claude Code Changelog (May-June 2026)](https://code.claude.com/docs/en/changelog)
- [Run agents in parallel - Claude Code Docs](https://code.claude.com/docs/en/agents)
- [Agent View - Claude Code Docs](https://code.claude.com/docs/en/agent-view)
- [git worktree man page](https://git-scm.com/docs/git-worktree)

</div>





[Abra o Ailoot](https://ailoot.ai/).

## Perguntas frequentes

### baseRef head copia alterações sem commit para o worktree novo?

Não. Parte do commit HEAD local, incluindo commits ausentes do remoto. Edições controladas sem commit ficam na cópia original; transfira WIP necessário explicitamente e inspecione o novo worktree.

### Porque falta .env num worktree novo?

É uma extração nova, sem ficheiros locais ignorados pelo Git. `.worktreeinclude` lista ficheiros ignorados a copiar; um hook WorktreeCreate personalizado tem de o fazer. Inclua só os ficheiros necessários à tarefa.


## Ailoot · A empresa e a sua carteira de projetos

A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.

A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.

A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.
