Git worktree com Claude Code e Codex: guia prático

Se você roda mais de um agente de código no mesmo repositório, você precisa de git worktrees. Com eles, cada agente trabalha no seu próprio branch, na sua própria pasta, ao mesmo tempo, sem pisar no pé dos outros.

O que é um git worktree?

Um clone normal tem uma working tree só: uma pasta, um branch com checkout. Um worktree é uma pasta de trabalho extra ligada ao mesmo repositório, com outro branch em checkout. Todos os worktrees compartilham o mesmo histórico .git, então commits feitos em qualquer um deles aparecem na hora para os outros, mas os arquivos ficam separados.

Para os agentes, isso significa:

• O Claude Code pode editar arquivos em ../atlas-auth, no feat/auth
• O Codex pode editar arquivos em ../atlas-search, no feat/search
• Você continua revisando e rodando o app na pasta principal, no main

Ninguém sobrescreve as mudanças de ninguém.

Crie um worktree por tarefa

Na pasta principal do seu repositório:

# new branch + new folder next to the repo
git worktree add ../atlas-auth -b feat/auth
 
# another one, starting from a specific branch
git worktree add ../atlas-search -b feat/search origin/main
 
# see them all
git worktree list

Depois, inicie um agente em cada pasta:

cd ../atlas-auth && claude
cd ../atlas-search && codex

Dê às pastas dos worktrees o nome da tarefa. Daqui a um mês, atlas-auth ainda vai fazer sentido; wt2, não.

Ou deixe o Claude Code criar o worktree

Versões recentes do Claude Code criam o worktree para você:

claude --worktree feature-auth   # or: claude -w feature-auth

Isso cria um worktree em .claude/worktrees/feature-auth/, num branch novo chamado worktree-feature-auth, e inicia o Claude dentro dele. Rode de novo com outro nome num segundo terminal para ter uma segunda sessão isolada. Você também pode pedir para o Claude “trabalhar num worktree” no meio de uma sessão.

Alguns detalhes da documentação de worktrees do Claude Code:

• Adicione .claude/worktrees/ ao seu .gitignore, para os arquivos dos worktrees não aparecerem como untracked no checkout principal.
• O repositório precisa ter pelo menos um commit.
• Quando você sai, o Claude remove um worktree limpo (perguntando antes, se ele tiver nome) e pergunta se você quer manter um worktree que ainda tem alterações.
• Um arquivo .worktreeinclude lista arquivos ignorados pelo git, como o .env, que devem ser copiados para todo worktree novo.

Use claude --worktree quando o Claude Code for o único agente na tarefa. Use o git worktree add puro quando quiser escolher você mesmo a pasta e o nome do branch, ou rodar o Codex ou outro agente no worktree.

Prepare cada worktree antes de o agente começar

Um worktree novo só tem os arquivos versionados pelo git. Antes de entregar para um agente:

• Instale as dependências. node_modules, virtualenvs e pastas de build não são compartilhados. Rode npm install (ou o equivalente) em cada worktree. Gerenciadores de pacotes com store compartilhado, como o pnpm, deixam isso rápido.
• Copie a configuração não versionada. Arquivos .env e ajustes locais costumam estar no gitignore, então copie o que o app precisa para rodar. Com claude --worktree, liste esses arquivos no .worktreeinclude.
• Use portas diferentes. Dois servidores de desenvolvimento não conseguem escutar os dois na porta 3000. Suba o segundo em outra porta, por exemplo PORT=3001 npm run dev.
• Compartilhe instruções por arquivos versionados. CLAUDE.md e AGENTS.md ficam no git, então todo worktree recebe esses arquivos automaticamente.

Revise, faça o merge e limpe

Quando um agente termina:

# in the worktree: check the work
git diff main...feat/auth
npm test
 
# in the main folder: merge
git merge feat/auth
 
# remove the worktree folder and its registration
git worktree remove ../atlas-auth
git branch -d feat/auth

Se você apagou a pasta de um worktree na mão, rode git worktree prune para limpar o registro que ficou para trás.

Armadilhas comuns

• “Branch is already checked out”. Um branch só pode estar em checkout num worktree por vez. Crie um branch novo para cada worktree.
• Worktrees esquecidos. Worktrees antigos mantêm branches vivos e ocupam espaço em disco. Rode git worktree list de vez em quando.
• Alterações não commitadas na hora de remover. O git worktree remove se recusa a remover quando o worktree tem alterações. Faça commit ou stash antes, ou use --force se quiser mesmo descartar tudo.
• Agentes editando a pasta principal. Inicie cada agente de dentro da pasta do worktree dele, não da raiz do repositório.

Worktrees no Vibe Console

O Vibe Console deixa os worktrees à vista enquanto os agentes trabalham neles:

• A aba Worktrees do controle de código-fonte (⌘⇧G) lista todos os worktrees com o branch de cada um, marcando o principal e qualquer checkout em detached HEAD.
• Arraste um worktree para um terminal para colar o caminho dele e inicie um agente ali com ⌘K.
• Remover worktree limpa um worktree quando você termina, e pede Forçar remoção se ele ainda tiver alterações locais. O worktree principal é protegido.
• A grade mostra até nove terminais, então o agente de cada worktree pode ter o seu próprio painel. Veja como rodar agentes em paralelo.

Crie os worktrees com git worktree add ou claude --worktree, como mostrado acima; os dois aparecem na lista na hora.

Perguntas frequentes

Worktrees ocupam muito espaço em disco?

Só o dos arquivos em checkout e do que você instalar neles. O histórico do git é compartilhado.

Uso worktrees ou clones separados?

Worktrees. Eles compartilham um histórico só, então branches e commits ficam disponíveis na hora em todo lugar, e a limpeza é um comando só.

Dois agentes podem dividir um worktree?

Só se no máximo um deles editar arquivos. Um agente revisor que só lê pode dividir o worktree com o agente que está escrevendo o código.

Teste grátis por 14 dias: baixe o Vibe Console.