Codex worktree: uma cópia de trabalho separada para uma segunda tarefa

Por exemplo, está a usar o Codex CLI para refatorizar um módulo quando surge uma segunda tarefa: escrever testes para outro módulo. Abrir uma segunda sessão na mesma pasta é arriscado: é fácil confundir as alterações da primeira e da segunda tarefa. A opção --worktree cria uma pasta separada com o mesmo projeto para a segunda tarefa, deixando a primeira intacta.

Recursos práticos para trabalhar com agentes em paralelo: documentação da Ailoot.

O que --worktree cria e que ficheiros são incluídos na cópia#

Na terminologia do Git, uma worktree é uma pasta de trabalho adicional ligada ao mesmo repositório: partilha o histórico de confirmações, mas tem o seu próprio conjunto de ficheiros no disco. No Codex CLI 0.155.1, a opção --worktree usa este mecanismo do Git para iniciar uma nova sessão de agente numa pasta separada, deixando intacta a pasta onde já está a decorrer a primeira tarefa.

A nova cópia de trabalho contém os ficheiros da confirmação para a qual aponta o HEAD do projeto original no momento do arranque — a última confirmação, e não a última vez que guardou um ficheiro no editor. Este comando não transfere alterações por confirmar nem ficheiros novos. Guardar no editor não é o mesmo que confirmar alterações no Git. Se a primeira pasta ainda tiver alterações por confirmar quando iniciar a segunda tarefa, essas alterações permanecerão apenas nessa pasta.

Isto não é uma cópia de segurança de todo o repositório nem um isolamento de todo o computador. É uma segunda pasta de trabalho do mesmo projeto, com acesso à mesma ramificação e ao mesmo histórico de confirmações. Para conhecer um mecanismo semelhante noutra ferramenta, consulte Claude Code e git worktree: tarefas em paralelo.

Preparação: versão, confiança no projeto e uma confirmação#

Verifique três coisas antes de começar. Execute os comandos na pasta do projeto original.

Primeiro, verifique a versão do Codex CLI. Estas instruções aplicam-se à versão 0.155.1; para outras versões, verifique o comportamento das opções separadamente:

codex --version

Em segundo lugar, precisa de um projeto Git local cujo HEAD aponte para uma confirmação existente — por outras palavras, o repositório tem de conter pelo menos uma confirmação. Caso contrário, não há nada a partir do qual criar a cópia.

Em terceiro lugar, a origem tem de ser considerada fidedigna: se o projeto estiver explicitamente marcado como não fidedigno, o arranque com --worktree falhará antes de a cópia ser criada. Se estiver a configurar o Codex CLI, os passos básicos de preparação são descritos em Codex (OpenAI): o que é e como começar.

Verifique antecipadamente a lista das cópias de trabalho existentes neste repositório. Pode usá-la para comparar depois do arranque:

git worktree list

As pastas separadas ajudam a manter as tarefas distintas. Para uma abordagem geral ao trabalho com um agente, os recursos práticos da documentação da Ailoot são úteis.

Passos: iniciar uma cópia separada para uma segunda tarefa#

1. Ative a funcionalidade experimental e inicie uma sessão com uma cópia separada

   Execute o comando na pasta do projeto original, onde já está a trabalhar na primeira tarefa.

   codex --enable worktrees --worktree
   

   Resultado esperado: o Codex cria uma nova cópia de trabalho do projeto a partir do HEAD atual e abre aí uma sessão de agente. A cópia fica num estado detached HEAD, sem uma ramificação com nome associada. É assim que a opção funciona na versão 0.155.1.

2. Volte a listar as cópias de trabalho noutro terminal no projeto original

   git worktree list
   

   Resultado esperado: o resultado inclui uma linha adicional com o caminho da nova cópia e um indicador de detached HEAD (ou uma ramificação, se existir). Esta lista mostra que o Git registou a cópia, mas não confirma que o agente concluiu a tarefa. Para garantir que os ficheiros estão lá, abra a pasta no caminho indicado e verifique o respetivo conteúdo.

Como verificar o resultado e preservar o seu trabalho#

Quando a segunda tarefa na nova cópia estiver concluída, terá de guardar e transferir o resultado separadamente. O comando --worktree não integra as alterações na ramificação principal nem transfere automaticamente o resultado. A cópia permanece num estado detached HEAD, pelo que criar uma confirmação dentro dela não cria, por si só, uma nova ramificação. Se precisar de preservar essas confirmações, associe-as a uma ramificação ou transfira-as para o projeto principal antes de eliminar a pasta da cópia.

Não elimine a pasta da cópia até ter preservado o resultado. Verificar se a pasta de trabalho está limpa não substitui a preservação das confirmações de que precisa: estas podem continuar sem uma ramificação associada.

Se estiver a trabalhar em tarefas em ferramentas diferentes ao mesmo tempo, planeie antecipadamente como evitar que interfiram umas com as outras. O trabalho conjunto com dois agentes é abordado em Claude Code e Codex em conjunto.

Se o arranque foi interrompido: onde encontrar a cópia#

O arranque com --worktree pode falhar por vários motivos:

• a funcionalidade não foi ativada previamente e o comando de arranque não inclui --enable worktrees: o Codex recusa-se a iniciar com a opção --worktree;
• está na pasta errada ou não existe nenhuma confirmação: se a pasta atual não for um repositório Git ou ainda não contiver confirmações, não há nada a partir do qual criar a cópia;
• o projeto está explicitamente marcado como uma origem não fidedigna: o Codex recusa-se a iniciar uma sessão com --worktree. Primeiro, certifique-se de que abriu o projeto correto. Não altere automaticamente o respetivo estado de confiança.

Se a sessão não conseguiu associar-se à cópia recém-criada — por exemplo, porque o processo foi interrompido —, a pasta de trabalho não é eliminada automaticamente. Primeiro, verifique a lista de cópias de trabalho e, antes de eliminar seja o que for, certifique-se de que nenhuma sessão do Codex CLI ainda está a usar esta cópia:

git worktree list

Abra a pasta e guarde as alterações de que precisa antes de a eliminar. A cópia pode permanecer mesmo que a sessão do agente não tenha concluído o arranque. Se a cópia existir, já não for necessária e tiver a certeza de que nenhuma sessão a está a usar, remova-a manualmente com git worktree remove a partir do repositório original, especificando o caminho da pasta. Não acrescente --force: se a cópia contiver ficheiros por confirmar ou não monitorizados, o comando recusará eliminá-la. Se o comando recusar, verifique o conteúdo da pasta sem desativar a proteção.

Ao atualizar o Codex CLI, volte a verificar a versão com codex --version e repita a verificação com git worktree list: as opções experimentais podem comportar-se de forma diferente entre versões.

Mais recursos e ferramentas: Ailoot.