Codex worktree: una copia de trabajo separada para una segunda tarea

Por ejemplo, estás usando Codex CLI para refactorizar un módulo cuando surge una segunda tarea: escribir pruebas para otro módulo. Abrir una segunda sesión en la misma carpeta es arriesgado: es fácil mezclar los cambios de la primera y la segunda tarea. El indicador --worktree crea una carpeta separada del mismo proyecto para la segunda tarea y deja intacta la primera.

Recursos prácticos para trabajar con agentes en paralelo: documentación de Ailoot.

¿Qué es una copia worktree para una segunda tarea en Codex?#

En la terminología de Git, un worktree es una carpeta de trabajo adicional vinculada al mismo repositorio: comparte el historial de commits, pero tiene su propio conjunto de archivos en el disco. En Codex CLI 0.155.1, el indicador --worktree usa este mecanismo de Git para iniciar una nueva sesión de agente en una carpeta separada y dejar intacta la carpeta donde ya se está ejecutando la primera tarea.

La nueva copia de trabajo contiene los archivos del commit al que apunta HEAD del proyecto original en el momento del inicio: el último commit, no la última vez que guardaste un archivo en el editor. Este comando no transfiere los cambios sin confirmar ni los archivos nuevos. Guardar en el editor no es lo mismo que confirmar cambios en Git. Si la primera carpeta aún tiene cambios sin confirmar cuando inicias la segunda tarea, esos cambios permanecerán solo en esa carpeta.

Esto no es una copia de seguridad de todo el repositorio ni un aislamiento de todo el ordenador. Es una segunda carpeta de trabajo del mismo proyecto, con acceso a la misma rama y al mismo historial de commits. Para ver un mecanismo similar en otra herramienta, consulta Claude Code y git worktree: tareas en paralelo.

Preparación: versión, confianza del proyecto y un commit#

Antes de empezar, comprueba tres cosas. Ejecuta los comandos desde la carpeta del proyecto original.

Primero, comprueba la versión de Codex CLI. Estas instrucciones se aplican a la versión 0.155.1; para otras versiones, comprueba por separado el comportamiento de los indicadores:

codex --version

Segundo, necesitas un proyecto Git local cuyo HEAD apunte a un commit existente; en otras palabras, el repositorio debe contener al menos un commit. De lo contrario, no hay nada a partir de lo cual crear la copia.

Tercero, la fuente debe ser de confianza: si el proyecto está marcado explícitamente como no confiable, el inicio con --worktree fallará antes de crear la copia. Si acabas de configurar Codex CLI, la preparación básica se explica en Codex (OpenAI): qué es y cómo empezar.

Comprueba de antemano la lista de copias de trabajo existentes de este repositorio. Puedes usarla para comparar después del inicio:

git worktree list

Las carpetas separadas ayudan a mantener las tareas aparte. Para conocer un enfoque general sobre cómo trabajar con un agente, consulta los recursos prácticos de la documentación de Ailoot.

Pasos: iniciar una copia separada para una segunda tarea#

1. Activa la función experimental e inicia una sesión con una copia separada

   Ejecuta el comando desde la carpeta del proyecto original, donde ya estás trabajando en la primera tarea.

   codex --enable worktrees --worktree
   

   Resultado esperado: Codex crea una nueva copia de trabajo del proyecto a partir del HEAD actual y abre allí una sesión de agente. La copia queda en estado HEAD separado, sin ninguna rama con nombre asociada. Así funciona el indicador en la versión 0.155.1.

2. Vuelve a enumerar las copias de trabajo en otra terminal del proyecto original

   git worktree list
   

   Resultado esperado: la salida contiene una línea adicional con la ruta de la nueva copia y una marca de HEAD separado (o una rama, si la hay). Esta lista muestra que Git ha registrado la copia, pero no confirma que el agente haya completado la tarea. Para asegurarte de que los archivos están ahí, abre la carpeta indicada y comprueba su contenido.

Cómo comprobar el resultado y conservar tu trabajo#

Cuando hayas terminado la segunda tarea en la nueva copia, debes guardar y transferir el resultado por separado. El comando --worktree no fusiona los cambios en la rama principal ni transfiere automáticamente el resultado. La copia permanece en estado HEAD separado, así que hacer un commit en ella no crea por sí mismo una rama nueva. Si necesitas conservar esos commits, asígnalos a una rama o transfiérelos al proyecto principal antes de eliminar la carpeta de la copia.

No elimines la carpeta de la copia hasta haber conservado el resultado. Comprobar que la carpeta de trabajo está limpia no sustituye la conservación de los commits que necesitas: quizá todavía no tengan ninguna rama asociada.

Si trabajas en tareas de distintas herramientas al mismo tiempo, planifica de antemano cómo evitar que interfieran entre sí. El trabajo con dos agentes a la vez se explica en Claude Code y Codex juntos.

Si el inicio se interrumpió: dónde encontrar la copia#

El inicio con --worktree puede fallar por varios motivos:

• la función no se activó de antemano y el comando de inicio no incluye --enable worktrees: Codex se negará a iniciarse con el indicador --worktree;
• estás en la carpeta equivocada o no hay ningún commit: si la carpeta actual no es un repositorio Git o aún no contiene ningún commit, no hay nada a partir de lo cual crear la copia;
• el proyecto está marcado explícitamente como una fuente no confiable: Codex se negará a iniciar una sesión con --worktree. Primero, asegúrate de haber abierto el proyecto correcto. No cambies automáticamente su estado de confianza.

Si la sesión no llegó a conectarse a la copia recién creada —por ejemplo, porque se interrumpió el proceso—, la carpeta de trabajo no se elimina automáticamente. Primero, comprueba la lista de copias de trabajo y, antes de eliminar nada, asegúrate de que ninguna sesión de Codex CLI siga usando esta copia:

git worktree list

Abre la carpeta y guarda los cambios que necesites antes de eliminarla. La copia puede permanecer aunque la sesión del agente no haya terminado de iniciarse. Si la copia existe, ya no la necesitas y tienes la certeza de que ninguna sesión la está usando, elimínala manualmente con git worktree remove desde el repositorio original, indicando la ruta de la carpeta. No añadas --force: si la copia contiene archivos sin confirmar o sin seguimiento, el comando se negará a eliminarla. Si se niega, comprueba el contenido de la carpeta sin desactivar la protección.

Al actualizar Codex CLI, vuelve a comprobar codex --version y repite la comprobación con git worktree list: los indicadores experimentales pueden comportarse de forma distinta entre versiones.

Más recursos y herramientas: Ailoot.