Codex CLI com worktrees: guia prático para trabalhar em paralelo

Codex CLI com worktrees: a configuração mais rápida

Você precisa do Codex CLI 0.154.0, de um repositório Git local e do recurso experimental worktrees habilitado. Antes de procurar uma flag que uma versão antiga não reconhece, confira a versão instalada.

codex --version
npm install -g @openai/codex@0.154.0
codex features enable worktrees
codex features list

O comando persistente registra a escolha do recurso na configuração do Codex. Se a ideia é testar uma única vez, deixe a configuração como está e acrescente --enable worktrees à chamada.

Agora você pode iniciar uma sessão isolada do zero, executar uma tarefa sem interface interativa ou criar um fork de uma conversa existente:

codex --enable worktrees --worktree "Upgrade the test runner and run its suite"
codex exec --enable worktrees --worktree "Find the flaky test and propose the smallest fix"
codex fork --enable worktrees --worktree <session-id> "Try the lower-risk implementation"

No fork interativo, <session-id> é o ID do chat exibido por /status. A versão 0.154.0 exige que esse ID seja informado. codex fork --worktree --last não é aceito.

O mesmo fluxo está disponível na interface do terminal. Digite /worktree e escolha entre continuar a conversa atual em um novo checkout, abrir uma conversa nova nele ou navegar pelas worktrees que o Codex já gerencia para o repositório.

O que o Codex cria

Uma worktree gerenciada é um segundo checkout ligado ao mesmo repositório Git. Imagine o repositório como o catálogo de uma biblioteca compartilhado por duas salas de leitura. Cada sala pode abrir um conjunto diferente de páginas, mas ambas consultam os mesmos commits e branches.

O Codex cria o novo checkout a partir do HEAD commitado do repositório de origem, no estado detached HEAD, e então o vincula à nova sessão. Detached HEAD quer dizer que o checkout aponta diretamente para um commit, em vez de avançar junto com uma branch nomeada. O checkout de origem permanece onde estava.

Esse ponto de partida limpo tem uma consequência importante: as alterações não commitadas no checkout original não acompanham a sessão. Arquivos ignorados, como os diretórios .env ou node_modules típicos, também ficam para trás. A OpenAI documenta a cópia via .worktreeinclude para worktrees locais gerenciadas pelo Desktop, mas deixa claro que esse comportamento não vale para worktrees criadas pela linha de comando. No fluxo do CLI, prepare o ambiente de que a tarefa precisa.

Se o Codex for iniciado em um diretório dentro do repositório, o checkout gerenciado preserva essa localização relativa. Por exemplo, iniciar em apps/web coloca a sessão no diretório apps/web correspondente da nova worktree, desde que ele exista na revisão commitada.

Fluxo prático: da abertura à integração

O processo mais seguro tem cinco etapas: começar do ponto certo, confirmar em qual checkout você está, executar o trabalho, examinar as evidências e só então decidir se vai manter ou descartar o resultado.

1. Comece pelo commit que você realmente quer usar

--worktree é uma opção booleana, não um seletor de branch ou de base. Ela parte do HEAD do repositório indicado. Antes de iniciar, faça checkout da branch-base desejada e commite qualquer alteração da origem necessária para a tarefa. Você pode usar -C <repo-path> para apontar o Codex para um checkout local específico.

Abra uma sessão nova quando a tarefa for independente. Prefira um fork quando a nova tentativa depender das decisões e restrições da conversa original. O fork preserva o histórico em um novo chat e transfere o novo trabalho para um checkout isolado; assim, a primeira tentativa continua intacta para comparação.

2. Confirme o checkout antes de editar

Logo no início, peça ao Codex para executar pwd, git status --short e git rev-parse --short HEAD. O diretório de trabalho deve ser o caminho gerenciado, o status precisa estar limpo e o commit deve coincidir com o HEAD de origem que você pretendia usar.

Essa verificação evita o erro banal que mais custa caro: fazer um ótimo trabalho sobre a base errada.

3. Instale apenas o necessário para essa frente

Uma worktree isola os arquivos presentes no checkout. Ela não cria um contêiner, reserva uma porta, clona um banco de dados nem instala dependências. Execute o comando normal de setup do repositório no checkout gerenciado. Quando houver risco de conflito, atribua portas, bancos temporários, diretórios de cache e contas de teste diferentes a cada sessão simultânea.

Esse é o principal limite do recurso. Dois diffs limpos no Git ainda podem interferir um no outro se as duas sessões migrarem o mesmo banco de desenvolvimento ou tentarem usar a mesma porta.

4. Revise o diff e retome a conversa certa

Dentro da sessão da worktree, /review consegue analisar alterações ainda não commitadas. Em outro terminal, primeiro use /worktree, selecione Browse worktrees, escolha o checkout e clique em Copy working directory. Depois, execute git -C "<worktree-path>" status --short, git -C "<worktree-path>" diff --stat e git -C "<worktree-path>" diff.

Não execute codex review --worktree. A versão 0.154.0 rejeita essa combinação de flags. Faça a revisão dentro da sessão ativa da worktree ou aponte as ferramentas normais de revisão para o caminho copiado.

Para continuar mais tarde, digite /worktree, escolha Browse worktrees, selecione o checkout e então Resume owner thread. Não acrescente --worktree a codex resume: retomar a conversa deve levar ao checkout já vinculado à sessão, e não criar outro.

5. Preserve a mudança antes de limpar o checkout

Se quiser manter a alteração, execute os testes relevantes, faça o commit dentro da worktree e copie o SHA do commit. No checkout original, use git cherry-pick <sha> para levar esse commit à branch atual. Faça o cherry-pick antes de remover a worktree, para que o commit detached ganhe um destino durável.

Caso o trabalho mereça uma branch própria para revisão, execute git switch -c codex/<task> na worktree, faça o commit, envie a branch e abra um pull request. O Git não permite que a mesma branch esteja ativa ao mesmo tempo no checkout original. Faça o push a partir da worktree ou remova essa worktree antes de abrir a branch em outro lugar.

Worktrees criadas pelo CLI não são removidas automaticamente. Depois de commitar com segurança a alteração — ou decidir descartá-la —, confirme que o checkout está limpo e execute git worktree remove <worktree-path> no repositório de origem. Evite --force. Mais tarde, git worktree prune pode limpar registros obsoletos do Git, mas não substitui a verificação de que nenhuma sessão ainda é dona do checkout.

Como isso muda o custo

O recurso nativo elimina uma camada pequena, porém recorrente, de comandos auxiliares. Antes da versão 0.154.0, quem usava o CLI precisava criar um caminho, abrir ou separar uma branch, iniciar o Codex naquele diretório, lembrar qual chat correspondia a ele e, depois, limpar tanto o estado do Git quanto o da sessão. A nova flag cria e vincula o checkout em uma única inicialização, enquanto /worktree oferece um navegador ciente do repositório e uma rota para retomar o trabalho.

Para quem já assina o Codex, não há uma tarifa específica publicada para o checkout. O Codex Plus custa $20 por mês. O Unstoppable, um workspace comercial para agentes que organiza worktrees paralelas, oferece o plano Pro a partir de $19 por mês, o Business por $29 por usuário e o Enterprise por $49 por usuário. Com o Codex nativo, a tarefa específica de criar checkouts e retomar sessões passa a caber na assinatura já existente.

Isso não substitui todo o restante da categoria de workspaces pagos. Painéis entre agentes, alocação de portas, preparação de ambientes compartilhados, consolidação de testes, acompanhamento de pull requests, políticas de equipe e relatórios de custos continuam acima da camada básica do checkout. Sessões paralelas também usam a mesma franquia do Codex. Portanto, a leitura financeira correta não é “desenvolvimento paralelo grátis”, mas “uma ferramenta de orquestração a menos caso o isolamento fosse o único motivo para comprá-la”.

Para entender o produto em torno desse recurso, a análise do Codex aborda o CLI local e o fluxo com agentes. Já o artigo anterior sobre o Codex CLI 0.152.0 mostra por que limites específicos de cada versão importam na automação do terminal.

Sete usos de worktrees, do maior para o menor retorno

1. Atualizações arriscadas de dependências

Quem mantém um projeto pode abrir uma worktree para atualizar um framework, gerenciador de pacotes ou executor de testes, deixar o Codex editar lockfiles e configurações e rodar toda a suíte sem misturar essas mudanças ao desenvolvimento de uma feature no checkout principal. O retorno é uma frente de atualização fácil de revisar e descartar, sem stash nem reversão de edições alheias.

2. Implementações concorrentes da mesma feature

Uma liderança técnica pode criar forks da mesma conversa de planejamento em duas worktrees gerenciadas, pedir à primeira sessão o menor patch possível e à segunda uma abordagem mais estrutural, e então comparar o tamanho dos diffs, os testes e o risco de migração. O retorno é uma escolha baseada em evidências, sem deixar a segunda tentativa sobrescrever a primeira.

3. Triagem de bugs em paralelo ao desenvolvimento

No meio de uma feature, uma pessoa de engenharia pode abrir uma worktree limpa a partir do HEAD commitado para reproduzir um bug de produção. O Codex consegue instrumentar, testar e corrigir o problema nessa frente, enquanto a feature inacabada permanece intacta. O retorno é depender menos de stashes emergenciais e obter um diff de hotfix mais limpo.

4. Codemods e refatorações de grande porte

Uma equipe de plataforma pode reservar um checkout para uma renomeação ampla ou migração de API, executar formatadores e testes ali e inspecionar o conjunto de arquivos alterados antes de levá-lo à branch principal. O retorno é contenção: a avalanche de mudanças geradas fica separada até merecer um commit.

5. Uma frente para correções de review

Quem abriu um pull request pode commitar a base da revisão, iniciar uma sessão isolada do Codex a partir desse estado e atender aos comentários sem interromper outra branch aberta localmente. O retorno é uma sequência focada de correções, que pode ser enviada da própria worktree quando estiver pronta.

6. Rotinas de manutenção reproduzíveis

Uma pessoa de engenharia de build pode usar codex exec --worktree em uma tarefa pontual, como atualizar arquivos gerados ou investigar um teste instável. A execução sem interface interativa recebe um checkout limpo dos arquivos rastreados e mantém uma sessão que pode ser inspecionada depois. O retorno é reduzir a contaminação acidental causada pelo que estiver aberto na árvore de trabalho principal. A ressalva: a automação precisa cuidar da instalação das dependências e da limpeza.

7. Exploração segura de um repositório

Quem acabou de entrar na equipe pode pedir ao Codex que mapeie uma base de código desconhecida e tente uma pequena mudança de documentação ou testes em uma worktree gerenciada antes de tocar no checkout habitual. O retorno também é psicológico: a exploração ganha um limite visível e um caminho simples para ser descartada.

Três produtos que vale criar para preencher a lacuna

1. A melhor aposta: uma camada de preparação de worktrees

Crie uma pequena ferramenta local que transforme um checkout gerenciado recém-aberto em uma frente de trabalho executável e livre de colisões. Ela detectaria a stack do projeto, executaria a instalação de dependências aprovada, alocaria uma porta, criaria um banco ou schema temporário, exporia apenas os segredos selecionados, faria uma verificação de integridade e mostraria o plano de limpeza correspondente.

A demanda é ampla: git worktree recebe cerca de 9,900 buscas mensais no Google dos EUA, e what is a git worktree, outras 590. O recurso nativo do Codex resolve a criação do checkout, mas deixa a preparação do ambiente em aberto — por isso, essa é a oportunidade mais forte.

A menor versão vendável precisa de um manifesto por repositório, comandos de setup e teardown, reserva de portas, criação de arquivos de ambiente a partir de modelos e uma verificação de status. A ressalva real é a segurança. Uma ferramenta que copie segredos ou aponte dois agentes para o mesmo banco de dados pode aumentar o risco em vez de reduzi-lo. A OpenAI também pode adicionar hooks nativos de ciclo de vida e diminuir essa lacuna.

2. Um painel de frentes para diferentes agentes

Crie um painel para desktop ou terminal que descubra worktrees entre repositórios e ferramentas e exiba a sessão proprietária, a branch ou o estado detached, arquivos alterados, resultado dos testes, uso do Codex, pull request, espaço em disco e uma ação segura para retomar ou limpar cada frente.

git worktree claude code recebe cerca de 480 buscas mensais nos EUA, enquanto a expressão exata parallel coding agents recebe 10. O segundo número é pequeno, mas já há comportamento pago: o Unstoppable começa em $19 por mês por um produto que inclui worktrees paralelas para agentes. O comprador é o desenvolvedor que já alterna entre Codex, Claude Code e terminais comuns.

Um MVP pode ser somente leitura: enumerar worktrees do Git, associar metadados conhecidos das sessões, executar comandos de status e teste sob demanda e criar links diretos para cada agente. A ressalva é a concorrência dos recursos nativos. O Codex 0.154.0 já navega pelas worktrees que ele próprio gerencia, então esse produto precisa vencer em visibilidade entre agentes, estado do ambiente de execução e relatórios para equipes.

3. Uma barreira de integração e limpeza

Crie uma proteção entre uma frente de agente concluída e a branch principal. Ela verificaria se o status está limpo, executaria o conjunto obrigatório de testes, detectaria arquivos alterados por outras worktrees ativas, recomendaria uma ordem de cherry-pick e impediria uma limpeza destrutiva enquanto ainda existissem commits não integrados.

A demanda de busca já revela essas dúvidas: git remove worktree recebe cerca de 390 buscas mensais nos EUA, git worktree vs branch chega a 320 e git worktree prune, a 140. As consultas se concentram no momento em que o trabalho isolado precisa virar trabalho compartilhado.

O MVP é um comando local do Git acompanhado de um pequeno arquivo de políticas. Ele pode ser útil sem editar uma linha sequer de forma automática. A ressalva é a distribuição: clientes Git e fornecedores de CI podem incorporar as mesmas verificações, então uma ferramenta independente precisa oferecer suporte excelente a diferentes agentes de programação e a repositórios reais e desorganizados.

Limites que devem pesar na sua decisão

Use worktrees nativas quando o problema for isolar arquivos. Não as confunda com isolamento completo de ambiente.

Também não existe, nesta versão, um equivalente no CLI ao botão Handoff do aplicativo Desktop. Trazer o código de volta ainda é uma decisão do Git: commitar e aplicar cherry-pick, fazer push de uma branch ou descartar e remover. Essa etapa explícita é saudável. O isolamento é útil justamente porque nada deve chegar por acidente ao checkout principal.

Seu próximo passo na segunda-feira: escolha uma atualização de dependência que não seja crítica, execute-a com codex --enable worktrees --worktree, compare o diff e os testes pelo caminho copiado do checkout, aplique cherry-pick somente no commit aprovado e remova a worktree. Se você quer montar um fluxo confiável de agentes isolados em torno dos seus repositórios, posso ajudar a projetar o sistema para produção.