Isolamento paralelo com Worktrees: Deixe vários Codex trabalharem cada um na sua, sem brigar
📚 Navegação da Série: O capítulo anterior (24 Regras e Hooks) equipou o Codex com "comportas" e "gatilhos", automatizando tarefas repetitivas e chatas. Este capítulo muda de dimensão: em vez de fazer um único Codex realizar mais uma tarefa, permitimos que várias tarefas comecem realmente ao mesmo tempo, sem que uma pise no pé da outra. O Worktree (árvore de trabalho) é o principal meio de isolamento do Codex para fazer isso: como criar, como usar, por que a mesma branch não pode ser obtida por checkout em dois lugares ao mesmo tempo, e como o Handoff (entrega) move o trabalho entre o primeiro plano (foreground) e o plano de fundo (background). O próximo capítulo (26 Integração com Git e GitHub) explicará como fazer commit, push e abrir PR após as alterações.
Vou contar uma tolice que fiz em março deste ano.
Aquele dia, para poupar trabalho, abri duas threads Local (locais) seguidas no app de desktop do Codex para alterar o mesmo repositório: uma para refatorar a camada de dados e outra para alterar as rotas. Eu estava todo feliz: pensei que abrir duas threads duplicaria a eficiência. No final, ambas as threads modificaram o mesmo config.ts. Quando a segunda thread fez o commit, acabou sobrescrevendo metade das alterações que a primeira tinha acabado de salvar. Fiquei parado olhando para aquele amontoado colorido de blocos vermelhos e verdes do git diff por alguns minutos até cair a ficha: não era o Codex agindo de forma estranha, fui eu quem colocou duas pessoas para disputar a mesma caneta na mesma mesa.
Só depois disso comecei a usar de verdade o que deveria ter usado desde o início — o Worktree. Para trabalhar em paralelo no mesmo projeto, sempre crio um Worktree; cada thread recebe uma cópia isolada do código. Desde então, nunca mais tive esse tipo de problema com alterações sendo sobrescritas.
No capítulo 07, ao falar sobre o app de desktop, já mencionei de passagem o Worktree — ele é um dos três modos (Local / Worktree / Cloud) para novas threads, trabalhando junto com o Handoff para mover tarefas entre o primeiro plano e o plano de fundo (o modo Cloud não será detalhado aqui, pois possui um capítulo próprio: 10 Tarefas na Nuvem). Neste capítulo, vamos nos aprofundar: como o isolamento funciona por baixo dos panos, por que existe a regra rígida de que 'uma branch só pode ser obtida por checkout em um único lugar', como o Handoff opera em ambas as direções e como limpar as cópias quando elas se acumulam. Se não explicarmos esses detalhes, mais cedo ou mais tarde você vai acabar caindo nessas armadilhas.
Ao ler este capítulo, você vai obter:
- Uma explicação simples sobre o que o Worktree resolve e a diferença fundamental entre ele e "abrir duas threads Local simultaneamente"
- Os passos completos para criar uma thread Worktree no app de desktop, além do fato contra-intuitivo de ele iniciar por padrão em estado detached HEAD (HEAD desanexado)
- A regra rígida na qual as pessoas mais costumam tropeçar — a mesma branch não pode ser obtida por checkout em dois lugares ao mesmo tempo, qual erro é exibido e como contorná-lo
- As duas rotas comuns do Handoff para mover threads em ambas as direções entre Local e Worktree, e quando usar cada uma delas
- Como usar o script de setup do Local environment para fazer com que um novo Worktree já nasça com todas as dependências instaladas e pronto para uso
- O que fazer quando as cópias de Worktree acumuladas ocupam muito espaço em disco: quantas são mantidas por padrão, o que não é excluído e se é possível restaurar um snapshot antes da exclusão
⚠️ Worktree, Handoff e Local environments são todos recursos exclusivos do app de desktop do Codex; não existe um switch correspondente como
--worktreena CLI — não procure por isso no terminal. Quaisquer botões, valores padrão ou itens de configuração mencionados abaixo baseiam-se na documentação oficial do Codex (Worktrees / Local environments); as funções podem ser ajustadas de acordo com a versão, portanto, prevalece a interface real exibida na sua máquina.
01 Entenda primeiro: Qual problema o Worktree realmente resolve?
Primeiro, a conclusão: o Worktree resolve o problema de "querer trabalhar simultaneamente em várias tarefas não relacionadas no mesmo repositório, sem que uma sobrescreva a outra". Há apenas um pré-requisito para que funcione: não deixe essas tarefas disputarem a mesma caneta no mesmo arquivo.
Lembrando dos capítulos anteriores, praticamente trabalhamos em "uma única thread": abrir uma tarefa, dar instruções e ela executa passo a passo. Esse modo é suficiente para 90% dos cases. Porém, há duas situações em que você vai achar isso limitante.
Primeira: tarefas que são naturalmente separáveis e não dependem uma da outra. Por exemplo, "ajustar o estilo do frontend", "corrigir um bug no backend" e "adicionar uma suite de testes". Elas não têm nada a ver uma com a outra, mas você é forçado a enfileirá-las — terminando o frontend antes de ir para o backend. Quando, na verdade, poderiam ser feitas ao mesmo tempo.
Segunda: você quer testar uma ideia nova, mas tem receio de mexer no trabalho atual que ainda não foi concluído. Há muitas alterações não salvas no diretório de trabalho atual e você decide validar outro caminho ali mesmo; se der errado, pode bagunçar também o que estava inacabado.
Nesse momento, você pode pensar: "então por que não abro mais algumas threads?" — é aí que está a armadilha. Se você abrir várias threads no modo Local apontando para o mesmo diretório do projeto, acabará cometendo a burrada que fiz no início: vários Codex alterando simultaneamente o mesmo arquivo, com a última gravação sobrescrevendo a anterior.
Analogia: Prontuário médico em um hospital. Existe apenas um prontuário físico original para o paciente. Se médicos de três departamentos diferentes quiserem dar opiniões ao mesmo tempo e escreverem todos no mesmo prontuário, as caligrafias com certeza vão se chocar e eles vão acabar rasurando o texto uns dos outros. A prática correta é dar a cada médico uma cópia do prontuário para escreverem, cada um na sua cópia, e depois consolidar tudo no original. O Worktree faz exatamente isso: a partir do mesmo histórico de repositório, ele extrai para você alguns diretórios de trabalho independentes, cada um com seu conjunto completo de arquivos, mas compartilhando o mesmo .git (o histórico de commits, as branches e outros metadados pertencem ao mesmo conjunto). As alterações que uma thread fizer na sua própria cópia jamais afetarão a cópia de outra thread.
A documentação oficial explica esse ponto crucial de forma bem direta:
Cada worktree contém uma cópia independente de cada arquivo no seu repositório, mas compartilha os mesmos metadados relativos a commits, branches, etc. (a pasta
.git). Isso permite que você faça checkout e trabalhe em múltiplas branches em paralelo.
No cenário real com o qual você vai se deparar, as tarefas adequadas para o Worktree se parecem com isto:
- "Estes dois módulos não têm relação: um corrige um bug, o outro adiciona uma funcionalidade, e quero enviar ambos ao mesmo tempo" — abra uma thread Worktree para cada, e ninguém interfere com ninguém.
- "Tenho alterações pela metade não commitadas e de repente quero testar outra solução" — abra um Worktree para testar; o original fica intacto e, se der errado, basta descartar.
- "Deixar o Codex rodar uma grande refatoração lentamente em segundo plano enquanto continuo fazendo outras coisas no primeiro plano" — jogue o trabalho para rodar em segundo plano em um worktree (detalharemos primeiro plano e segundo plano na próxima seção).
💡 Resumo em uma frase: O Worktree serve para permitir que tarefas não relacionadas no mesmo repositório comecem ao mesmo tempo sem se sobrescreverem (como dar a cada médico uma cópia do prontuário). A única regra rígida é: não deixe que elas disputem a caneta no mesmo arquivo, caso contrário, o paralelo vira uma bagunça.
Na imagem acima: um único repositório Git deriva três worktrees independentes, com três tarefas do Codex ocupando cada uma delas, sem se sobrescreverem.
02 Criando uma thread Worktree no app de desktop
Agora que você sabe por que usar, vamos ver como criar. Tudo é feito com alguns cliques no app de desktop, sem necessidade de digitar comandos.
Worktree só funciona em repositórios Git — por baixo dos panos, ele usa o recurso nativo de worktree do git. O projeto selecionado deve ser um repositório git, caso contrário, essa opção simplesmente não estará disponível.
Criando em quatro passos
Passo 1: Nova thread, selecione o modo Worktree. Abaixo do campo de entrada da nova thread, altere o modo padrão de Local para Worktree (você também pode escolher um local environment para rodar o script de setup, que detalharemos na seção 05).
Passo 2: Escolha "a partir de qual branch". Abaixo da caixa de texto, você poderá selecionar em qual branch este worktree será baseado — pode ser a main / master, alguma branch de funcionalidade ou até mesmo sua branch atual junto com as alterações locais não indexadas (unstaged). Isso é muito útil: o trabalho que você deixou pela metade pode ser levado para continuar dentro do worktree.
Passo 3: Envie suas instruções. Ao enviar a tarefa, o Codex vai criar um git worktree baseado na branch que você selecionou e começará a trabalhar nele.
Passo 4: Decida o destino ao terminar. Na finalização, você tem dois caminhos — ou continua trabalhando neste worktree (fazendo commit, push, abrindo PR) ou faz um Handoff para passar essa thread de volta para o Local (seção 04).
Um fato contra-intuitivo porém crucial: o worktree inicia por padrão em detached HEAD
Este é o ponto que mais confunde quem está começando, então vale a pena destacar.
O worktree criado pelo Codex não fica em nenhuma branch por padrão, mas sim em um estado chamado detached HEAD (HEAD desanexado) — você pode entender isso como "ele aponta diretamente para um commit específico, em vez de apontar para o nome de uma branch". Palavras oficiais:
Por padrão, o Codex trabalha no estado 'detached HEAD'.
Por que esse design? A explicação oficial é muito pragmática: assim, o Codex consegue criar vários worktrees de uma vez sem poluir a sua lista de branches. Seu git branch não vai ficar cheio de nomes de branches estranhos só porque você abriu cinco worktrees.
E se eu quiser transformar essa alteração em uma branch de verdade? — Há um botão Create branch here (Criar branch aqui) no topo da thread. Clique nele para converter o worktree atual em uma branch, permitindo que você faça commit, push e abra PRs nela depois.
💡 Resumo em uma frase: Criar uma thread de Worktree requer apenas quatro passos — selecionar o modo Worktree → escolher a branch de origem → dar a instrução → decidir o destino; lembre-se de que ele inicia por padrão em detached HEAD (fora de qualquer branch) e, se quiser fazer commit e push normalmente, clique primeiro em Create branch here para transformá-lo em uma branch.
03 A regra mais importante para dominar: Uma branch não pode ser obtida por checkout em dois lugares ao mesmo tempo
Esta seção é curta, mas mais crítica do que as anteriores — muitas pessoas já tropeçaram nisso, inclusive eu.
Vamos deixar a regra bem clara. O Git tem uma regra rígida: uma branch só pode ser obtida por checkout em uma única árvore de trabalho (worktree) por vez. Se você fez o checkout de feature/a em um determinado worktree, seu repositório local original (Local) não pode fazer checkout de feature/a ao mesmo tempo, e vice-versa.
Analogia: O mesmo livro de uma biblioteca. Um livro físico tem apenas um exemplar. Se A o pegou emprestado, B não poderá pegar o mesmo exemplar — não é por mesquinharia da biblioteca, mas porque o estado de "com quem o livro está agora" só pode ter uma única resposta correta no mesmo instante. O mesmo vale para as branches do Git: o nome de uma branch (refs/heads/<name>) representa a resposta única de "qual é o estado atual desta árvore de trabalho". Se fosse permitido fazer checkout simultaneamente em dois lugares e enviar commits de ambos ao mesmo tempo, tudo viraria uma bagunça — commits poderiam ser perdidos ou o índice poderia entrar em conflito. Por isso, o Git simplesmente corta pela raiz: uma branch só é associada a uma única árvore de trabalho por vez.
O que acontece se você esbarrar nessa regra? Suponha que o Codex terminou o trabalho em algum worktree e você criou uma branch feature/a usando o Create branch here; agora você decide fazer checkout de feature/a no seu repositório local original para dar uma olhada — o Git vai disparar um erro diretamente:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'Isso significa: esta branch já está ocupada por aquele worktree, então não pode ser baixada por checkout localmente.
Como resolver isso? A solução correta não é insistir no erro, mas usar o Handoff. O guia oficial aponta dois caminhos:
- Se você solo quer dar uma olhada rápida: mude o checkout no worktree para outra branch, liberando a
feature/a. - Se você realmente quer trazer esse trabalho de volta para o repositório local e continuar: use o Handoff para passar toda a thread para o Local (detalharemos isso na próxima seção), em vez de tentar manter a mesma branch aberta por checkout nas duas pontas.
💡 Resumo em uma frase: Uma branch só pode ser obtida por checkout em uma única árvore de trabalho por vez (como um livro físico da biblioteca que só pode ser emprestado a uma pessoa). Tentar fazer checkout em dois lugares gera o erro
already used by worktree; para mover o trabalho de volta para o ambiente local, use o Handoff em vez de insistir em forçar a branch.
04 Handoff: Movendo threads de um lado para o outro entre Local e Worktree
Mencionamos o Handoff repetidamente na seção anterior, e agora vamos detalhá-lo. Ele é a solução oficial do Codex para lidar com o inconveniente de "não poder fazer checkout da mesma branch em duas pontas", e também uma ação que você usará diariamente no fluxo com worktrees.
Primeiro, compreenda um modelo mental: o Local é o primeiro plano, e o Worktree é o segundo plano. O Local (projeto original) é a área de trabalho onde você normalmente mexe diretamente com as mãos, abre sua IDE de costume e roda o servidor de desenvolvimento, equivalente à mesa de trabalho à sua frente; já o Worktree é a cópia isolada que progride silenciosamente em segundo plano. O que o Handoff faz é mover uma thread de um lado para o outro entre o primeiro plano e o segundo plano.
Analogia: A cozinha aberta e a despensa/cozinha de apoio. A cozinha aberta (Local) é a bancada onde os clientes podem ver e onde o chefe monta o prato à vista deles; a cozinha de apoio (Worktree) é onde as coisas são picadas, preparadas e cozidas em fogo baixo silenciosamente nos bastidores. Onde um prato deve ser preparado depende do momento: se for para finalizar na hora ou apresentar para inspeção, ele é levado para a cozinha aberta; se for necessário liberar a bancada da frente para outros pedidos enquanto este prato cozinha lentamente, ele é movido para a cozinha de apoio. O Handoff é exatamente esse movimento de levar e trazer — e o Codex se encarrega de tratar todas as operações de git subjacentes de forma segura, sem que você precise digitar um monte de comandos git worktree.
A documentação oficial destaca a razão essencial pela qual o Handoff existe, conectando diretamente com a seção anterior:
Isso é importante porque o Git permite apenas que uma branch seja baixada por checkout em um único lugar por vez.
Ele funciona em duas direções, correspondendo a dois fluxos de trabalho comuns:
Direção 1: Worktree → Local (trazer a thread do segundo plano para o primeiro plano). Clique em Hand off no topo da thread e selecione mover para Local. Quando usar? Quando você quiser realizar a validação usando seu ambiente familiar do dia a dia — ler os diffs na sua janela habitual da IDE, rodar o servidor de desenvolvimento existente ou quando o seu app só permite rodar uma única instância, impedindo que outra seja iniciada no worktree. Este é o fluxo que eu mais utilizo: deixo o Codex construir uma funcionalidade em segundo plano no worktree e, quando estiver pronto, faço o Handoff de volta para o Local para revisar linha por linha no editor que conheço.
Direção 2: Local → Worktree (jogar a thread do primeiro plano para o segundo plano). O inverso também é possível. Se estiver trabalhando no Local e quiser liberar a mesa de trabalho para fazer outra coisa, use o Hand off para mover esta thread para o worktree — deixando o Codex rodando em segundo plano enquanto você redireciona sua atenção para outras tarefas locais.
Aqui há um detalhe atencioso e fácil de passar despercebido: cada thread permanece sempre vinculada ao mesmo worktree. Se você fizer o Handoff dela de volta para o Local e, mais tarde, quiser jogá-la de volta para o segundo plano, o Codex a enviará de volta ao mesmo worktree original, permitindo que você continue de onde parou, sem começar do zero.
A última armadilha que você deve memorizar:
Como o Handoff utiliza operações do Git, qualquer arquivo presente no seu
.gitignorenão será movido junto com a thread.
Ou seja, itens não rastreados pelo git, como arquivos .env e caches locais, não serão levados no Handoff. Isso tem a ver com a própria natureza de "cópia limpa" do worktree, e a próxima seção detalha exatamente como preencher essa lacuna.
| Worktree → Local | Local → Worktree | |
|---|---|---|
| Direção | Trazer do segundo plano para o primeiro plano | Jogar do primeiro plano para o segundo plano |
| Cenário típico | Validar na IDE de costume, rodar servidor de desenvolvimento que só permite uma única instância | Liberar o primeiro plano para outras tarefas, deixando-o rodar em segundo plano |
| Quem cuida do git | Tratado automaticamente pelo Codex | Tratado automaticamente pelo Codex |
Arquivos no .gitignore | Não são movidos junto | Não são movidos junto |
💡 Resumo em uma frase: O Handoff move as threads em mão dupla entre o Local (primeiro plano) e o Worktree (segundo plano) (como levar e trazer pratos entre a cozinha aberta e a de apoio), com o Codex cuidando das operações de git com segurança; cada thread permanece vinculada ao mesmo worktree, mas los arquivos listados no
.gitignorenão são transferidos.
05 Fazendo o novo worktree nascer "totalmente equipado": O script de setup do Local environment
Retomando a lacuna mencionada na seção anterior: o worktree é uma nova cópia obtida por checkout que roda em um diretório diferente do seu Local. Por isso, ele não contém inicialmente as dependências, configurações e arquivos locais que não foram incluídos no git. O exemplo mais típico é: ao rodar um novo worktree, a pasta node_modules e o arquivo .env não estão lá, fazendo com que o trabalho trave de imediato.
Eu realmente caí nessa em abril: todo empolgado, criei um Worktree para o Codex alterar o backend, mas ele não conseguia se conectar ao banco de dados — depois de quebrar muito a cabeça é que percebi que o arquivo .env simplesmente não estava no worktree (como vimos na seção anterior, itens do .gitignore não são levados junto). Depois que adicionei o script de setup, nunca mais tive esse problema.
Analogia: A 'lista de abertura de filial' de uma rede de lojas. A matriz (seu Local) tem tudo completo, enquanto a nova filial (worktree) abre com as paredes vazias. Uma rede de lojas inteligente tem uma lista padrão de abertura: estocar produtos, instalar equipamentos, organizar a decoração; basta executar a lista e a nova loja estará pronta para funcionar. O script de setup do Local environment é exatamente essa lista — toda vez que o Codex cria um worktree para uma nova thread, ele roda esse script automaticamente, instalando as dependências e realizando as compilações necessárias.
Onde e como configurar? A documentação oficial explica claramente:
- Configure o local environment através do painel de settings (configurações) do App do Codex; as configurações geradas serão salvas na pasta
.codexna raiz do seu projeto. - Este arquivo de configuração pode ser commitado no git e compartilhado com a equipe — basta configurar uma vez para que os worktrees de toda a equipe fiquem equipados automaticamente.
Vejamos um exemplo de projeto TypeScript disponibilizado oficialmente; o script de setup possui apenas estas duas linhas:
npm install
npm run buildAssim que o novo worktree é criado, essas duas linhas rodam automaticamente, instalando as dependências e realizando o build inicial. O Codex pode começar a trabalhar imediatamente, sem faltar nada.
Diferenças entre plataformas: Se os seus passos de setup variam por plataforma (macOS / Windows / Linux), você pode definir scripts de setup individuais para cada uma para sobrescrever o padrão. A compatibilidade do app de desktop no Windows segue o que estiver definido na documentação oficial para Windows.
Aproveitando para citar um recurso relacionado: além do script de setup, o local environment permite configurar Actions (Ações) — transformando comandos de uso frequente como "iniciar o servidor de desenvolvimento" ou "rodar a suite de testes" em botões de atalho no topo do app. Basta clicar em um deles para executá-lo no terminal integrado. Já demos uma pincelada nisso no capítulo 07, então não nos estenderemos aqui.
💡 Resumo em uma frase: O worktree é uma cópia nova e limpa, logo as dependências e o
.envque não estão no git não farão parte dele; use o script de setup do local environment (salvo na pasta.codexna raiz do projeto e que pode ser commitado para compartilhamento) para instalar as dependências automaticamente logo na criação, assim como uma filial que abre seguindo uma "lista de abertura".
06 O que fazer quando os worktrees acumulados ocuparem muito espaço: Limpeza, limite máximo e restauração por snapshot
Após começar a usar o trabalho em paralelo com frequência, surgirá um problema real: os worktrees ocupam espaço em disco. Cada um deles carrega um conjunto completo de arquivos do repositório, dependências e caches de build — abrindo mais de uma dezena deles, o espaço em disco vai diminuir visivelmente. Por isso, o Codex ajuda você a manter a quantidade de worktrees sob controle dentro de um limite razoável.
Primeiro, vamos a dois fatos sobre o funcionamento interno, para que você não precise ficar procurando onde os worktrees estão localizados:
- O Codex cria e gerencia todos os worktrees centralizadamente sob
$CODEX_HOME/worktrees(sendo queCODEX_HOMEaponta por padrão para~/.codex, como mencionamos no capítulo de configuração 18). - Por padrão, o Codex mantém os 15 worktrees gerenciados pelo Codex mais recentes; este limite pode ser alterado nas configurações, ou você pode desativar a exclusão automática para gerenciar o espaço em disco manualmente.
Mas qual é a regra que o Codex segue para excluir os worktrees? Ele tenta ao máximo não apagar o que ainda é importante. De acordo com a documentação oficial:
Nas seguintes situações, o worktree gerenciado pelo Codex não será excluído automaticamente:
- Há um chat fixado (pinned) vinculado a ele
- A thread correspondente ainda está em execução
- Trata-se de um worktree permanente (permanent worktree, veja abaixo)
Nas seguintes situações, ele será excluído automaticamente:
- Você arquivou (archive) a thread correspondente
- O Codex precisa apagar worktrees mais antigos para não ultrapassar o limite que você configurou
O ponto mais tranquilizador — há um snapshot antes da exclusão:
Antes de excluir um worktree gerenciado pelo Codex, o Codex salvará um snapshot do trabalho realizado naquele worktree. Se você abrir o chat correspondente após o worktree ter sido deletado, verá uma opção para restaurá-lo.
Ou seja, mesmo que um worktree seja limpo automaticamente, a thread em si permanece no seu histórico, e ao reabri-la você ainda terá a opção de restaurá-lo — assim você não perde todo o trabalho de uma vez.
Por fim, vamos diferenciar dois conceitos para evitar confusão: Worktree gerenciado pelo Codex vs. Worktree permanente.
| Worktree gerenciado pelo Codex (padrão) | Worktree permanente (permanent) | |
|---|---|---|
| Como é criado | Criado automaticamente pelo Codex ao abrir uma thread no modo Worktree | Criado manualmente através do menu de três pontos do projeto na barra lateral |
| Threads vinculadas | Geralmente exclusivo para uma thread | Permite iniciar múltiplas threads a partir do mesmo worktree |
| É excluído automaticamente? | Sim (ao exceder o limite ou arquivar) | Não é excluído automaticamente |
| Indicado para | Tarefas leves e temporárias que podem ser descartadas após o uso | Quando se deseja um ambiente fixo que exista por longo prazo |
Explicando de forma simples: para testar uma ideia temporariamente, use o padrão; ele será limpo automaticamente após o uso; já se você deseja um ambiente estável a longo prazo para o qual voltará repetidamente, crie um worktree permanente a partir do menu de três pontos do projeto. Ele se tornará um projeto próprio e não será excluído automaticamente.
💡 Resumo em uma frase: Os worktrees são criados em
$CODEX_HOME/worktreese, por padrão, os 15 mais recentes são mantidos; eles são excluídos automaticamente quando o limite é excedido ou ao serem arquivados (com um snapshot salvo antes de apagar, permitindo restauração). Os fixados, em andamento ou permanentes não são excluídos. Use o padrão para tarefas temporárias e crie um worktree permanente para ambientes de longo prazo.
07 Prática: Roteiro completo de Worktree no app de desktop
Apenas ler sem praticar não adianta. O roteiro abaixo deve ser executado inteiramente com cliques no app de desktop do Codex, precisando apenas de um projeto git. Cada passo traz o resultado esperado para você se autoverificar; siga os passos para criar memória muscular sobre essa técnica.
Você precisará de um repositório git (se não tiver um, basta usar
git initem qualquer pasta para treinar). Este fluxo é exclusivo do app de desktop; não há chaves correspondentes na CLI. Os passos a seguir não dependem de conexões de rede especiais.
Passo 1: Nova thread, alterne o modo para Worktree
No app, clique para criar uma nova thread. Abaixo da caixa de entrada de texto, mude o modo de Local para Worktree e selecione uma branch de origem (para treinar, escolha main).
Resultado esperado: O modo é exibido como Worktree, e a opção "branch de origem" aparece abaixo. Ver esses dois itens significa que você está prestes a abrir uma cópia isolada, em vez de mexer no arquivo original.
Passo 2: Envie uma tarefa curta e apenas de leitura
Envie uma instrução simples e segura, que não faça alterações nos arquivos, como: "Liste os títulos de todos os arquivos markdown deste projeto."
Resultado esperado: O Codex vai criar um worktree baseado na branch que você selecionou e começará a trabalhar nele. O diretório de trabalho desta thread estará localizado sob $CODEX_HOME/worktrees (por padrão, ~/.codex/worktrees), totalmente separado do seu projeto Local original.
Passo 3: Confirme que se trata de um worktree independente no terminal integrado
Abra o terminal integrado da thread (usando Cmd + J no macOS, ou o atalho correspondente para Windows na sua máquina) e execute:
git worktree listResultado esperado: Além do seu checkout principal, a lista mostrará uma linha extra apontando para o diretório .../.codex/worktrees/.... Ver essa linha significa que a cópia isolada foi criada com sucesso e você está atualmente dentro dela.
Passo 4: Experimente fazer o Handoff de volta para o Local
Clique no botão Hand off no topo da thread e escolha mover para Local.
Resultado esperado: A thread será transferida para o seu projeto local original, e agora você poderá inspecionar as alterações usando seu ambiente habitual de IDE / terminal. O Codex cuida de todas as operações de git nos bastidores, sem que você precise digitar comandos do tipo git worktree.
Passo 5: Limpeza
Como você não vai precisar manter o worktree temporário de treino, a forma mais fácil de limpá-lo é arquivar (archive) a thread — conforme as regras da seção 06, o worktree gerenciado pelo Codex correspondente será excluído automaticamente após o arquivamento (com um snapshot salvo antes, permitindo restaurar caso mude de ideia). Você também pode ir em configurações para verificar o limite de quantidade de worktrees e a chave de exclusão automática.
Resultado esperado: Após o arquivamento, a thread desaparece da lista ativa e o worktree entra no fluxo de limpeza automática; a cópia correspondente no disco é desalocada. Tudo limpo = circuito completo concluído.
Ao concluir estes cinco passos, você terá percorrido manualmente o fluxo principal do worktree: "criar cópia isolada → confirmar independência → Handoff para o primeiro plano → limpar". A dinâmica de trabalho paralelo no futuro será essencialmente igual a esta, apenas mudando as tarefas ou abrindo múltiplas threads de Worktree.
💡 Resumo em uma frase: O fluxo de prática tem os mesmos cinco passos — iniciar thread no modo Worktree → enviar tarefa curta para criar o worktree → rodar
git worktree listpara confirmar o isolamento → fazer Hand off para Local para validação → arquivar thread para limpeza automática; executar esse fluxo uma vez ensina mais do que memorizar dez comandos.
08 Resumo
Este capítulo explicou detalhadamente a ideia de "deixar múltiplos Codex trabalharem no mesmo repositório simultaneamente sem conflitos", indo desde o "porquê isolar" até "como limpar as cópias acumuladas".
Vamos revisar os pontos centrais de forma integrada:
| O que você deseja fazer | O que usar | Pontos-chave |
|---|---|---|
| Entender o porquê de isolar | Os dois pré-requisitos do Worktree | Paralelismo no mesmo repositório; não disputar a caneta no mesmo arquivo (como dar a cada médico uma cópia do prontuário) |
| Criar uma thread isolada | Selecionar o modo Worktree para nova thread | Escolher a branch de origem; inicia por padrão em detached HEAD, clique primeiro em Create branch here para fazer commits |
| Evitar checkout duplo de branch | Lembrar-se da regra rígida | Uma branch só pode ser baixada por checkout em um lugar por vez; se violar, gera o erro already used by worktree |
| Mover trabalho entre primeiro e segundo plano | Handoff | Mão dupla entre Local (primeiro plano) e Worktree (segundo plano); o Codex cuida do git automaticamente; arquivos do .gitignore não são transferidos |
| Equipar o novo worktree | Script de setup do Local environment | Salvo em .codex na raiz do projeto, pode ser compartilhado via commit; o novo worktree instala as dependências automaticamente na criação |
| Controlar o consumo de disco | Regras de limpeza + worktree permanente | Mantém por padrão os 15 mais recentes; com snapshot de segurança para restauração; use worktrees permanentes para longo prazo |
Agora você deve ser capaz de:
- Explicar claramente o que o Worktree resolve, sabendo que a regra de ouro é "não disputar o mesmo arquivo ao trabalhar em paralelo no mesmo repositório"
- Criar uma thread Worktree no app de desktop, ciente de que ela inicia em detached HEAD por padrão e exige clicar em Create branch here antes de fazer commits
- Compreender a regra rígida de que "uma branch não pode ser obtida por checkout em dois locais ao mesmo tempo" e usar o Handoff caso esbarre nela
- Utilizar o Handoff para mover threads em ambas as direções entre Local e Worktree, além de configurar scripts de setup do local environment para automatizar a preparação do novo worktree
- Saber como os worktrees são limpos ao se acumularem e quais cenários impedem que sejam apagados
Olhando para trás, aquela burrada de "abrir duas threads Local seguidas para alterar o mesmo repositório" ocorreu basicamente porque não houve isolamento, permitindo que dois Codex disputassem a mesma caneta. Agora, munido da chave de isolamento do Worktree e do Handoff como transportador, você poderá evitar os desvios que quem apenas mergulha de cabeça costuma dar.
O próximo capítulo, 26 Integração com Git e GitHub — traz ações com o Git com as quais você já se deparou: converter worktree em branch, as operações internas de git tratadas silenciosamente pelo Codex no Handoff, commits, pushes... mas a maioria delas ainda estava no plano de "o Codex faz por você". O próximo capítulo vai expor de frente a capacidade de integração com Git / GitHub do Codex: fazer commit, push e abrir PR diretamente no App, gerenciar staging/descarte bloco a bloco no painel de diff e interagir com o GitHub. Pense bem: o worktree isola o trabalho muito bem, mas no fim é preciso integrá-lo de forma limpa na branch principal — e esse passo é exatamente o palco principal do próximo capítulo.