Codex CLI oferece três formas de usar worktrees do Git: a flag --worktree, o comando /worktree e, desde a versão 0.162.0, três ferramentas que o próprio agente pode invocar para criar e listar worktrees gerenciadas enquanto sua sessão continua no checkout original. A função que as habilita, worktrees, é estável e vem ativada por padrão: não há nada para ativar.
Instalamos a 0.162.1 (a versão estável atual, lançada em 9 de outubro, um dia depois da 0.162.0) e testamos cada caminho em um repositório descartável. Aqui está o que cada um faz, o que realmente adicionou esta versão e um comportamento que o changelog não menciona: se você não nomear as novas ferramentas em seu prompt, é muito provável que o agente não as use.
O que é git worktree e por que importa para agentes de IA?
Um git worktree é um segundo checkout do mesmo repositório. Cada um tem sua própria cópia dos arquivos, mas todos compartilham um único diretório .git: os mesmos commits, as mesmas branches. Isso permite que você tenha duas linhas de trabalho abertas ao mesmo tempo sem fazer stash, sem clonar novamente e sem mudar de branch repetidamente.
Para agentes de código, é a diferença entre executar uma tarefa por vez e executar várias: cada agente trabalha em seu próprio diretório, então dois agentes editando src/ ao mesmo tempo não se sobrescrevem.
O que mudou no Codex CLI 0.162?
Menos do que sugere um “Codex finalmente tem worktrees”, e algo mais interessante. Comparando a 0.161.0 com a 0.162.1, lado a lado:
- Já estava na 0.161.0: a flag
--worktree, o comando/worktreee a funçãoworktrees, ativada por padrão. - Novo na 0.162.0 (PR #50148): três ferramentas que o modelo pode invocar:
create_worktree,get_worktree_creation_statuselist_worktrees. Agora o agente pode criar um worktree em segundo plano e associá-lo à tarefa atual, enquanto o diretório de trabalho dessa tarefa permanece onde estava.
Ou seja, a mudança não é para você, o humano, que já tinha uma flag. É para o agente: agora ele pode decidir que precisa de um checkout isolado, criá-lo e continuar trabalhando.
Preciso ativar worktrees no Codex CLI?
Não. O changelog diz que as ferramentas funcionam “quando o recurso worktrees está habilitado”, o que parece ser um interruptor oculto. Não é:
codex features list | grep worktrees
Na 0.162.1, isso imprime worktrees stable true. Já era assim na 0.161.0.
O outro requisito é que o projeto seja confiável: de acordo com o PR, a criação é rejeitada em projetos marcados explicitamente como não confiáveis. Codex pergunta se você confia em uma pasta na primeira vez que a abre; responda que sim.
Para instalar ou atualizar para a versão estável atual:
npm install -g @openai/codex@0.162.1
Como você inicia uma sessão do Codex CLI em um worktree?
Inicie Codex com a flag de dentro do seu repositório:
codex --worktree
O texto de ajuda o descreve como “Run the session in a new managed Git worktree”. A mesma flag existe em codex exec para execuções não interativas. Dentro de uma sessão já aberta, /worktree faz o mesmo.
Em nosso teste, o worktree ficou em ~/.codex/worktrees/<id>/repo: um identificador curto aleatório mais o nome do repositório. Uma mudança não commitada que deixamos no checkout original não passou para o worktree: apenas o trabalho commitado é levado.
Por que o worktree fica em detached HEAD?
Porque Codex não cria uma branch para ele. O worktree aponta diretamente para o commit atual em estado detached HEAD, então sua lista de branches permanece limpa. Se depois quiser preservar o trabalho, crie uma branch a partir desse worktree como faria com qualquer checkout.
Como o agente cria seus próprios worktrees?
Você pede, e a forma de pedir importa. Esta foi a descoberta mais útil do teste.
Com um prompt genérico (“Create a worktree to try adding a LICENSE file”), o agente ignorou completamente as novas ferramentas. Executou um git worktree add -b try-license-2 /private/tmp/... normal, pediu a aprovação usual para comandos shell e criou uma branch real em /tmp. Essa é a receita manual, não a função gerenciada.
Quando pedimos que listasse suas ferramentas com “worktree” no nome, respondeu que não tinha nenhuma. As ferramentas existem, mas não são carregadas até que algo as solicite pelo nome. Elas vivem sob o espaço de nomes codex_tui:
codex_tui.create_worktreecodex_tui.get_worktree_creation_statuscodex_tui.list_worktrees
Nomeá-las funciona. Este prompt:
Use your create_worktree tool, not the shell or git, to create a worktree for adding a LICENSE file. Then check its status with get_worktree_creation_status, and finally call list_worktrees.
produzin um worktree gerenciado em ~/.codex/worktrees/<id>/repo, em detached HEAD, sem nenhum comando shell ou Git. A criação é assíncrona: create_worktree retorna pending com um identificador de operação, e get_worktree_creation_status retorna created quando o checkout está pronto. A sessão permaneceu todo o tempo no repositório original.
Duas coisas que vale a pena saber:
- Não há solicitação de aprovação. Ao contrário da via
git worktree add,create_worktreefoi executado sem perguntar. Apenas cria um checkout e não modifica seus arquivos, mas se você trabalha com uma política de aprovações rigorosa, tenha em mente que o agente pode fazer isso por conta própria. - Branch base padrão. De acordo com o PR, o worktree parte da branch padrão do remoto, a menos que o agente indique um
refespecífico. Se você clonou um repositório vazio, é possível que o Git nunca tenha registrado essa branch;git remote set-head origin --autoresolve isso.
O que acontece com os worktrees quando você termina?
Arquive a sessão (/archive dentro do Codex, ou codex archive do terminal) e seu worktree gerenciado desaparece com ela: vimos ele sumir de git worktree list. Se quiser revisar como funciona o arquivamento de sessões, explicamos em Session management no Codex CLI.
Essa é a diferença mais clara com a via manual: os dois worktrees que o agente criou em /tmp com Git puro permaneceram lá, juntamente com suas branches, até que os deletamos manualmente com git worktree remove e git branch -D.
Worktrees gerenciados pelo Codex ou seus próprios scripts de git worktree?
Se você já executa agentes em paralelo com seus próprios scripts de git worktree add, isto é o que a versão gerenciada resolve para você:
| Seu próprio script | Gerenciado pelo Codex | |
|---|---|---|
| Localização | onde você colocar | ~/.codex/worktrees/<id>/repo |
| Branch | normalmente cria uma | detached HEAD, sem branch |
| Controle de confiança | nenhum | rejeitado em projetos não confiáveis |
| Limpeza | manual (git worktree remove, git branch -D) |
eliminado ao arquivar a sessão |
| O agente pode criá-lo no meio da tarefa | apenas com comandos shell | sim, com create_worktree, sem sair do diretório da tarefa |
Uma lacuna: a documentação de worktrees da OpenAI cobre o aplicativo desktop do ChatGPT (Handoff, o arquivo .worktreeinclude para copiar arquivos ignorados como .env, o limite de limpeza de 15 worktrees) e esclarece que .worktreeinclude aplica aos worktrees gerenciados pelo aplicativo desktop. No momento de publicar esta nota (13 de outubro de 2026), não documentava --worktree, /worktree nem as novas ferramentas do CLI, então não presumimos que esse comportamento se transfira.
O que mais traz o Codex CLI 0.162?
/copypara navegar e copiar blocos do histórico,Ctrl+Insertpara copiar uma seleção etui.mouse_scroll_speedpara ajustar a velocidade da rolagem.- Fixar tarefas no Command Center de agentes com a tecla
p. - URLs clicáveis em cabeçalhos de aprovação, perguntas, prompts de MCP, avisos e banners, mesmo quando ocupam mais de uma linha.
- A 0.162.1 corrigiu um bug da TUI com perguntas de múltiplas linhas e erros de inicialização quando a configuração de recursos de um servidor em background não correspondia aos valores padrão do CLI.
E você? Quantos agentes você executa ao mesmo tempo no mesmo repositório, e como evita que se sobrescrevam?
- Com worktrees gerenciados pela ferramenta (Codex, Claude Code…)
- Com meus próprios scripts de git worktree
- Um agente por vez, sem paralelismo
- Prefiro outra opção (conte-nos qual)
Comente abaixo ou, se este artigo chegou por email, responda diretamente: sua resposta é publicada aqui.
Relacionado: Voltar à sessão do seu agente a partir do grafo: GitLens 19 une Claude Code a cada worktree