Worktrees do Codex: Git worktrees gerenciados, passo a passo
Ative o recurso worktrees, rode um chat em um Git worktree gerenciado, transforme o resultado em branch com Work here e abra o codex --worktree direto do terminal — 10 passos de uma gravação de tela limpa.
TL;DR
- Um Git worktree é um segundo checkout do mesmo repositório — cada worktree tem seus próprios arquivos mas compartilha a pasta .git, então chats do Codex em paralelo nunca se sobrescrevem.
- Os worktrees ficam atrás de um feature flag: rode codex features enable worktrees num terminal, reinicie o app, e a opção New local worktree aparece no composer.
- Um worktree terminado vira branch em dois cliques — o Create branch nomeia codex/your-branch, depois a folha de commit empurra e você abre o PR sem sair do worktree.
- Worktrees gerenciados vivem em $CODEX_HOME/worktrees como pastas com nome de hash. O Codex mantém os 15 mais recentes, salva um snapshot antes da limpeza e pode restaurá-lo pelo chat. As ferramentas de criar/listar chegaram no Codex 0.162.0.
Codex Worktrees: The Best Feature Most Developers Ignore
Canal:Software Engineer Meets AI4:56
Worktrees — official Codex documentation
Docs:developers.openai.com/codex
Os quadros vêm de uma gravação de tela limpa; comandos e rótulos de UI foram conferidos com a documentação oficial de worktrees do Codex. As ferramentas de worktree gerenciado chegaram no Codex 0.162.0 (outubro de 2026): "Add tools for creating and listing managed Git worktrees from trusted local projects when the worktrees feature is enabled."
O vídeo continua propriedade de seu criador e está linkado para fins de atribuição. Nomes de produtos e elementos de interface pertencem à OpenAI.
Como funcionam os worktrees do Codex, passo a passo
Ativar os worktrees e começar um
- 1
Saiba o que é um worktree antes de ativar qualquer coisa
Um Git worktree é um segundo checkout completo do seu repositório, na própria pasta dele — cada worktree tem sua cópia de cada arquivo, mas todos compartilham os mesmos metadados .git. É por isso que vários chats do Codex em paralelo podem editar cada qual sua pasta sem tropeçar nas mudanças não commitadas uns dos outros. Worktrees são um recurso Git comum de qualquer jeito; o Codex só automatiza as tarefas domésticas em volta.
A gravação abre com a definição de uma frase: várias branches de um mesmo repo com checkout em pastas diferentes ao mesmo tempo.Assistir em 0:28 - 2
Ative o recurso worktrees uma vez
Os worktrees ainda estão atrás de um portão no Codex, então o primeiro passo acontece num terminal. Como mostrado na gravação, o apresentador abre o terminal embutido do app e roda codex features enable worktrees, o que vira a flag no config.toml — depois reinicia a aplicação. Após a reinicialização, a opção New local worktree aparece no composer.
O app do Codex com um painel de terminal aberto sob o composer, bem onde o comando de ativação roda antes da reinicialização.Assistir em 1:58 - 3
Comece um chat em um New local worktree
Num chat novo, os chips do composer se leem: nome do projeto, New local worktree, No environment, main — o modo worktree e a branch de partida. Deixe o New local worktree selecionado e main como branch inicial, digite sua tarefa (aqui, "change the background color to be blue") e envie.
O composer com New local worktree e main selecionados enquanto o prompt é digitado.Assistir em 3:00 - 4
Deixe o agente trabalhar dentro do worktree dele
O Codex responde "Worktree created" e começa a trabalhar na cópia isolada — a thread mostra ele rodando npm run type-check && git diff --check enquanto você segue usando o app para outros chats. Seu checkout principal fica intacto, e o contador de Changes (+2 -2 na gravação) rastreia o que o agente edita dentro do worktree.
O cabeçalho da thread mostra Worktree created enquanto o agente roda type-check e comandos diff dentro do worktree.Assistir em 3:17
Transformar o worktree em branch e PR
- 5
Descubra onde o Codex guarda os worktrees
Worktrees gerenciados não são jogados ao lado do seu projeto. A documentação oficial os coloca em $CODEX_HOME/worktrees, e a gravação confirma: depois de cd em .codex/worktrees, o ls imprime uma pasta com nome de hash por worktree (09bd, 09ec, 7b3a, d021, dd4e). Dá para mudar a raiz em Settings > Worktrees pelo ajuste Worktree root.
Terminal dentro de .codex/worktrees listando cinco pastas worktree com nome de hash.Assistir em 3:41 - 6
Abra o menu da thread e crie uma branch
Um worktree novo começa detached — o Codex cria sem branch anexada. Para guardar o trabalho, abra o menu Environment da thread: Changes (+2 -2), Worktree, Create branch, Commit or push e Create pull request. O Create branch é a ação que transforma essa pasta em uma branch nomeada de verdade.
O menu Environment da thread com Changes, Worktree, Create branch, Commit or push e Create pull request.Assistir em 3:25 - 7
Confirme a branch no diálogo Work here
O Create branch abre o diálogo Work here: "Create a branch to commit changes, push, and create a PR from this worktree." O campo Branch name vem pré-preenchido com o prefixo codex/ — codex/change-background-color na gravação — clique em Create e a branch se prende ao worktree. O Git só permite uma branch com checkout em um worktree por vez, e é exatamente por isso que o Codex cuida desse pareamento por você.
Diálogo Work here com o nome de branch pré-preenchido codex/change-background-color e o botão Create.Assistir em 3:52 - 8
Commite e empurre do worktree
De volta à thread, o Commit or push abre uma folha de commit na branch codex/change-background-color: digite uma mensagem, mantenha Include unstaged changes marcado (+2 -2) e escolha Commit, Commit and push ou Push. A gravação cria em seguida o pull request para a main — o fluxo inteiro nunca saiu da pasta do worktree.
Folha de commit na branch codex/change-background-color com Include unstaged changes e a opção Commit and push.Assistir em 4:04
O caminho do CLI e as regras que mordem
- 9
Pule o app: abra um worktree pelo CLI
O mesmo recurso funciona headless. Na gravação, o apresentador digita codex --worktree "Implement the new feature" no prompt do zsh dentro do repo — o Codex cria um worktree gerenciado para esse chat e roda a tarefa ali, igualzinho ao app. Essas ferramentas de criar e listar chegaram no Codex 0.162.0 para projetos locais confiáveis.
Terminal na branch main do repo rodando codex --worktree "Implement the new feature".Assistir em 4:38 - 10
Conheça as regras de limpeza e o limite de uma branch
O Codex mantém seus 15 worktrees gerenciados mais recentes e poda os velhos conforme novos chegam — nunca um chat fixado, um chat em andamento ou um worktree permanente, e sempre depois de salvar um snapshot que você pode restaurar pelo chat. Duas bordas duras da documentação: uma branch só pode ter checkout em um worktree por vez (use Handoff em vez de um segundo checkout), e arquivos ignorados como .env não viajam para os worktrees a menos que você os liste num arquivo .worktreeinclude.
Documentação oficial de Worktrees: o que é um worktree, terminologia e comportamento de limpeza.Assistir em 4:47
Worktree do Codex não funciona? Confira isto primeiro
A maioria das falhas de worktree é de configuração, não de Git. A gravação e a documentação oficial apontam para a mesma lista curta — percorra ela de cima a baixo antes de mexer no .git à mão.
- 1Feature flag desligado. Os worktrees ficam atrás de um portão: rode codex features enable worktrees num terminal e reinicie completamente o app do Codex. Faltar a opção New local worktree no composer significa quase sempre que esse passo — ou a reinicialização — nunca aconteceu.
- 2O projeto não é um repositório Git. Worktrees só funcionam em projetos que fazem parte de um repositório Git, e as notas do 0.162.0 limitam as ferramentas a "trusted local projects" — uma pasta qualquer ou um repo novo não confiável não vai oferecer a opção de worktree.
- 3A branch de partida já tem checkout em outro lugar. O Git permite um worktree por branch, então escolher uma branch ocupada falha com fatal: 'branch' is already used by worktree at .... Comece pela main ou outra branch livre, ou use o Handoff para mover o chat.
- 4Seus arquivos de env não apareceram no worktree. O Git não rastreia .env e companhia, então não são copiados. Liste-os num arquivo .worktreeinclude na raiz do repo (um caminho por linha) e o Codex os copia para os worktrees novos.
- 5Um app desatualizado. A gravação abre com "make sure you update yours to the latest version" — as ferramentas de worktree gerenciado só existem em builds recentes (0.162.0 ou mais novo para as ferramentas create/list do CLI). Atualize, ative a flag, reinicie e tente de novo.
Se um worktree já sumiu mas o trabalho importava, abra o chat dele primeiro — o Codex salva um snapshot antes de limpar um worktree e consegue restaurá-lo. E se todo o modelo parecer pesado, o git worktree add de sempre continua funcionando: o Codex só automatiza a mesma função Git de baixo.