Qué es un Codex worktree
La documentación de OpenAI comienza con su propósito: "Los worktrees permiten que Codex ejecute múltiples chats independientes en el mismo proyecto sin interferir entre sí".
Internamente, un Codex worktree es un Git worktree. "Los worktrees solo funcionan en proyectos que forman parte de un repositorio Git, ya que utilizan Git worktrees internamente". La documentación explica lo que esto significa: "Cada worktree tiene su propia copia de cada archivo en tu repositorio, pero todos comparten los mismos metadatos (carpeta .git) sobre commits, ramas, etc."
La aplicación de escritorio de ChatGPT utiliza tres términos:
- Local es tu propio checkout, el repositorio que creaste.
- Worktree es un Git worktree que la aplicación creó a partir de tu checkout local.
- Handoff es el flujo que mueve un chat entre Local y un worktree.
OpenAI sugiere pensar en ellos como primer y segundo plano: "Puedes pensar en Local como el primer plano y en Worktree como el segundo plano".
El repositorio y el worktree permanecen en la máquina que contiene el proyecto. "Los worktrees no se ejecutan localmente en tu teléfono". La aplicación móvil de ChatGPT puede iniciar, guiar, aprobar y revisar chats de worktree, pero lo hace controlando Codex en tu computadora conectada.
Cómo iniciar un chat en un worktree
Los pasos son breves:
- En la vista de nuevo chat, selecciona Worktree debajo del editor. Opcionalmente, elige un entorno local para ejecutar scripts de configuración.
- Debajo del editor, elige la rama de Git en la que se basará el worktree.
- Envía tu prompt. Codex crea el worktree a partir de esa rama.
- Cuando estés listo, sigue trabajando en el worktree o transfiere (handoff) el chat a Local.
El proyecto debe estar en un repositorio Git.
Con qué comienza un nuevo worktree
Un worktree no es una carpeta vacía. La documentación de OpenAI describe exactamente lo que Codex coloca en él.
El último commit de la rama. "El commit inicial es el commit HEAD de la rama seleccionada al iniciar el chat".
Tus cambios sin confirmar, si elegiste una rama que los tiene. "Si elegiste una rama con cambios locales, Codex aplica también los cambios sin confirmar al worktree".
Cada archivo rastreado. "Los Codex-managed worktrees locales comienzan desde un checkout de Git, por lo que los archivos rastreados ya están presentes".
Sin rama propia. "El worktree no se extrae como una rama". Está en un estado de HEAD desprendido (detached HEAD), y la documentación da la razón: "Esto permite a Codex crear varios worktrees sin contaminar tus ramas".
Tu anulación de instrucciones locales. Codex copia un archivo ignorado automáticamente. "Codex copia automáticamente un AGENTS.override.md ignorado en los worktrees gestionados localmente, por lo que no necesitas listarlo en .worktreeinclude". Si guardas instrucciones personales para Codex en ese archivo, también estarán presentes en el worktree.
Lo que instale tu script de configuración. Si elegiste un entorno local, se ejecuta su script de configuración. OpenAI explica por qué esto es importante: "Dado que los worktrees se ejecutan en directorios diferentes a tus chats locales, es posible que tu proyecto no esté completamente configurado y le falten dependencias o archivos que no están registrados en tu repositorio". Y: "Los scripts de configuración se ejecutan automáticamente cuando Codex crea un nuevo worktree al inicio de un nuevo chat".
Qué deja fuera un nuevo worktree
La otra cara de comenzar desde un checkout de Git es que cualquier cosa que Git ignore se queda atrás, a menos que indiques lo contrario.
Archivos ignorados, por defecto. Los ejemplos de OpenAI incluyen archivos .env y un archivo de secretos. Para traer archivos específicos, añade un archivo .worktreeinclude en la raíz del repositorio y enumera las rutas o patrones a copiar. La documentación es precisa sobre los límites: "Codex solo copia los archivos ignorados que coinciden con .worktreeinclude; no copia otros archivos locales que Git no rastrea".
Archivos rastreados en la lista de inclusión. "No listes archivos rastreados". Ya están ahí.
Enlaces simbólicos y archivos existentes. "Codex omite los enlaces simbólicos de origen y no sobrescribirá los archivos que ya existan en el nuevo checkout".
Otros tipos de worktrees. El comportamiento de inclusión tiene un alcance: "Este comportamiento se aplica a los worktrees gestionados por la aplicación de escritorio ChatGPT local, no a los worktrees remotos ni a los Git worktrees que crees tú mismo desde la línea de comandos".
Dependencias instaladas. A menos que un script de configuración las instale, un worktree nuevo puede no tener tus node_modules o la salida de compilación. Para eso sirven los scripts de configuración del entorno local.
Mover un chat entre Local y un worktree
Handoff mueve un chat y su código en cualquier dirección. La documentación de OpenAI dice: "Transferir hacia o desde Local mueve tu chat y tu código para que puedas continuar en el otro checkout".
Dos detalles hacen que Handoff sea predecible:
- Un chat conserva su worktree. "Cada chat mantiene el mismo worktree asociado a lo largo del tiempo. Si devuelves el chat a un worktree más tarde, Codex lo devuelve a ese mismo entorno de segundo plano para que puedas retomar donde lo dejaste".
- Los archivos ignorados no viajan. "Dado que Handoff utiliza operaciones de Git, cualquier archivo que forme parte de tu archivo
.gitignoreno se moverá con el chat a menos que Codex los copie en un worktree gestionado localmente con.worktreeinclude".
Cubrimos Handoff en detalle, incluyendo qué se mueve con un chat entre tu computadora y un host remoto, en nuestra guía sobre qué se mueve con tu chat en Codex Handoff.
La regla de las ramas que confunde a la gente
Git tiene una regla que Codex no puede omitir. La documentación lo pone en negrita: "Git solo permite que una rama esté activa (checked out) en un lugar a la vez".
Esto aparece cuando conviertes un worktree en una rama. Si seleccionas Create branch here en el worktree y luego intentas activar esa rama en tu checkout local, Git lo rechazará con un error indicando que la rama ya está siendo usada por un worktree.
El consejo de OpenAI: "Si planeas activar la rama localmente, usa Handoff para mover el chat a Local en lugar de intentar mantener la misma rama activa en ambos lugares a la vez".
Cuándo elimina Codex un worktree
Los worktrees ocupan espacio. "Los worktrees pueden ocupar mucho espacio en disco. Cada uno tiene su propio conjunto de archivos de repositorio, dependencias, cachés de compilación, etc.". Por ello, la aplicación de escritorio limita cuántos conserva.
El límite predeterminado. "Por defecto, Codex conserva tus 15 Codex-managed worktrees más recientes. Puedes cambiar este límite o desactivar la eliminación automática en los ajustes si prefieres gestionar el uso del disco tú mismo".
Cuándo ocurre la eliminación. La documentación enumera dos disparadores:
- Archivas el chat asociado.
- Codex necesita eliminar worktrees antiguos para mantenerse dentro de tu límite configurado.
El primero es fácil de pasar por alto. Archivar un chat suena a poner orden en la barra lateral, pero para un chat con un Codex-managed worktree, también elimina el worktree. Archivar en Codex tiene otros efectos también, los cuales cubrimos en nuestra guía sobre el centro de comandos del agente Codex y qué hacen archivar y eliminar.
Qué está protegido. Los Codex-managed worktrees no se eliminan automáticamente si un chat fijado (pinned) está vinculado a ellos o si el chat aún está en progreso.
Worktrees permanentes antiguos. "Los worktrees permanentes creados en versiones anteriores siguen estando disponibles y protegidos de la limpieza automática. Ya no puedes crear worktrees permanentes desde el menú del proyecto".
Cómo restaurar un worktree eliminado
Eliminar un worktree no elimina el chat. El FAQ de OpenAI dice: "Los chats pueden permanecer en tu historial incluso si el directorio del worktree subyacente se elimina".
Y el trabajo se guarda primero: "Antes de eliminar un Codex-managed worktree, Codex guarda un snapshot del trabajo en él. Si abres un chat después de que su worktree fuera eliminado, verás la opción de restaurarlo".
Así que la ruta de recuperación es simple: abre el chat y elige la opción de restaurar.
La documentación no especifica cuánto tiempo se conservan los snapshots, ni si un snapshot incluye archivos ignorados copiados a través de .worktreeinclude. Si un worktree contenía algo que no puedes recrear, como un secreto local o un archivo generado, guarda tu propia copia en lugar de confiar únicamente en el snapshot.
Dónde residen los worktrees
"Codex crea worktrees en $CODEX_HOME/worktrees". Puedes cambiar la ubicación. El FAQ de OpenAI indica que debes abrir Settings, luego Worktrees, y cambiar Worktree root.
Esto es útil si tu unidad principal es pequeña o si quieres los worktrees en un disco más rápido. También es importante saberlo cuando limpies espacio en disco a mano. Las protecciones para chats fijados y en progreso, y el paso del snapshot, están documentados para la limpieza propia de Codex, no para carpetas que elimines tú mismo.
Worktrees para tareas programadas
Los worktrees no son solo para los chats que inicias tú mismo. "Para los repositorios Git, las tareas programadas pueden ejecutarse en worktrees dedicados en segundo plano para que no entren en conflicto con tu trabajo en curso".
Los proyectos fuera de Git funcionan de manera diferente: "En proyectos sin control de versiones, las tareas programadas se ejecutan directamente en el directorio del proyecto".
Lo que un worktree no almacena
Un worktree almacena archivos. El chat adjunto a él almacena la conversación. Lo que ninguno está diseñado para almacenar es el razonamiento que se traslada de un chat al siguiente: por qué se eligió este enfoque, qué alternativas fallaron y qué está esperando el código.
Los worktrees son, por diseño, desechables. Cuando uno se elimina, el snapshot conserva el trabajo realizado. Las decisiones tomadas en el camino viven en la conversación de ese chat, de la cual es fácil perder el rastro una vez que hay docenas de chats.
Lo que la gente intenta primero
Archivar chats antiguos para limpiar. En un chat con un Codex-managed worktree, archivar elimina el worktree.
Esperar archivos .env en un nuevo worktree. Los archivos ignorados no se copian a menos que coincidan con .worktreeinclude.
Activar la rama del worktree localmente. Git permite una rama en un solo lugar a la vez. Usa Handoff en su lugar.
Eliminar la carpeta de worktrees a mano. El paso del snapshot está documentado para la limpieza de Codex, no para carpetas que elimines tú mismo.
Asumir que el chat desaparece con el worktree. Los chats pueden permanecer en tu historial y puedes restaurar el worktree desde el chat.
La solución: Usar worktrees sin perder el trabajo
Paso 1: Configura lo que necesita un nuevo worktree
Añade un script de configuración de entorno local para las dependencias y un archivo .worktreeinclude para los archivos ignorados que necesita un worktree.
Paso 2: Protege los chats a los que volverás
Fija (pin) los chats cuyos worktrees quieras conservar, o aumenta el límite en los ajustes.
Paso 3: Restaurar en lugar de rehacer
Si un worktree fue eliminado, abre el chat y usa la opción de restaurar antes de empezar de cero.
Paso 4: Documenta el razonamiento
Guarda las decisiones detrás de los cambios de un worktree, como el enfoque y lo que descartaste, fuera del chat.
Configurando esto en MemoryLake
Un worktree es un buen lugar para el trabajo paralelo, y Codex tiene cuidado de guardarlo antes de la limpieza. Las decisiones detrás de ese trabajo son lo que el próximo chat, en un nuevo worktree o en Local, necesita retomar sin volver a preguntar.
MemoryLake es una capa de memoria para ese tipo de contexto de proyecto, como decisiones, restricciones y convenciones, mantenida en un solo lugar y disponible para los asistentes que conectes, como ChatGPT, Claude Code y Codex.
Tú mismo escribes las entradas, con tus propias palabras. No se lee nada de tus worktrees, ni se escribe ni se borra nada de ellos, sus snapshots, tus chats de Codex, tus archivos .worktreeinclude o AGENTS.override.md, tus memorias de Codex o el almacén de cualquier proveedor. Los worktrees, Handoff y la limpieza funcionan de la manera que describe OpenAI.
Paso 1: Crea una clave de API
Inicia sesión y genera una clave desde el panel de control. Guárdala fuera de tus repositorios, como cualquier otra credencial, y no la añadas a .worktreeinclude.

Paso 2: Sube tus primeras memorias
Comienza con lo que escribiste en el Paso 4 de la solución: el enfoque para cada pieza de trabajo, las alternativas que probaste y las restricciones que le dieron forma. Una decisión por entrada.

Paso 3: Conecta tu IA y agentes
Conecta Codex y cualquier otro asistente que uses. Un nuevo chat en un worktree fresco, o un chat transferido a Local, puede recurrir a las mismas decisiones.

Qué cambia esto en la práctica
La primera diferencia es que la limpieza deja de ser un riesgo para tu razonamiento. Un worktree puede ser archivado y eliminado, y las decisiones detrás de él seguirán estando documentadas.
La segunda es un inicio más rápido para chats paralelos. Cada nuevo chat de worktree puede basarse en las decisiones ya establecidas del proyecto en lugar de redescubrirlas.
La tercera es la continuidad entre herramientas. Claude Code u otro asistente que trabaje en el mismo repositorio puede usar las mismas entradas.
Mejores prácticas para Codex worktrees
Usa worktrees para trabajo en segundo plano. Mantén Local para lo que estés probando activamente.
Añade un script de configuración. Los nuevos worktrees pueden no tener dependencias a menos que algo las instale.
Lista los archivos ignorados en .worktreeinclude. Solo se copian los archivos ignorados que coincidan.
Fija lo que volverás a visitar. Los chats fijados conservan sus worktrees.
Archiva deliberadamente. Archivar elimina el Codex-managed worktree de un chat.
Restaura antes de rehacer. Codex guarda un snapshot antes de eliminar un worktree gestionado.
Guarda el "porqué" en otro lugar. Un worktree guarda archivos, no razones.
Conclusión
Un Codex worktree es un Git worktree que la aplicación de escritorio ChatGPT crea para que un chat pueda trabajar en segundo plano sin tocar tu checkout local. Comienza desde el commit HEAD de la rama que elegiste, incluye tus cambios sin confirmar si esa rama los tenía, tiene cada archivo rastreado y copia solo los archivos ignorados que listes en .worktreeinclude, además de AGENTS.override.md.
Codex conserva tus 15 worktrees gestionados más recientes por defecto y elimina el worktree de un chat cuando lo archivas. Los chats fijados y en progreso están protegidos, y antes de eliminar un worktree gestionado, Codex guarda un snapshot que puedes restaurar desde el chat. Mantén el razonamiento detrás del trabajo en algún lugar donde el próximo chat pueda leerlo.