MemoryLake
Volver a todos los artículos
Tutorial13 de noviembre de 2026·12 min de lectura

¿Qué es un Codex Worktree? Qué incluye al inicio, por qué al archivar un chat se elimina y cómo restaurar el Snapshot que Codex guarda (2026)

Inicias un chat de Codex, seleccionas Worktree bajo el editor en lugar de Local, y dejas que se ejecute en segundo plano mientras sigues trabajando en tu propio checkout. Todo va bien. Unas semanas después, abres un chat antiguo y los archivos en los que trabajó ya no están en el disco. Codex ofrece restaurar algo. ¿Qué pasó?

Dos puntos en la documentación de OpenAI lo explican. Los worktrees están diseñados para ser temporales: "Por defecto, los chats utilizan un worktree gestionado por Codex. Estos están pensados para ser ligeros y desechables". Y se limpian según un cronograma que quizás no hayas notado: "Por defecto, Codex mantiene tus 15 Codex-managed worktrees más recientes".

El trabajo no se ha perdido necesariamente. "Antes de eliminar un Codex-managed worktree, Codex guarda un snapshot del trabajo en él".

Esta guía cubre qué es un Codex worktree, cómo iniciar un chat en uno, con qué comienza un nuevo worktree y qué deja fuera, cómo Handoff mueve un chat entre Local y un worktree, cuándo Codex elimina los worktrees, cómo restaurar uno, dónde residen y qué es lo que un worktree no almacena.

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:

  1. En la vista de nuevo chat, selecciona Worktree debajo del editor. Opcionalmente, elige un entorno local para ejecutar scripts de configuración.
  2. Debajo del editor, elige la rama de Git en la que se basará el worktree.
  3. Envía tu prompt. Codex crea el worktree a partir de esa rama.
  4. 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 .gitignore no 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.

La consola de MemoryLake mostrando la pantalla de claves API, donde se crea y copia una nueva clave para usar en un agente
La consola de MemoryLake mostrando la pantalla de claves API, donde se crea y copia una nueva clave para usar en un agente

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.

El espacio de trabajo de MemoryLake con los primeros documentos subidos, listando cada archivo a medida que se convierte en memoria buscable
El espacio de trabajo de MemoryLake con los primeros documentos subidos, listando cada archivo a medida que se convierte en memoria buscable

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.

La pantalla de integraciones de MemoryLake listando los clientes de IA y frameworks de agentes que pueden conectarse a la capa de memoria
La pantalla de integraciones de MemoryLake listando los clientes de IA y frameworks de agentes que pueden conectarse a la capa de memoria

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.

Preguntas frecuentes

¿Qué es un worktree en Codex?

Un Git worktree que la aplicación de escritorio ChatGPT crea a partir de tu checkout local para que un chat de Codex pueda trabajar en paralelo sin interferir con tus otros chats.

¿Por qué desapareció mi Codex worktree?

Codex elimina un worktree gestionado cuando archivas su chat o cuando necesita mantenerse dentro de tu límite, que es de 15 por defecto.

¿Puedo restaurar un Codex worktree eliminado?

Sí. Codex guarda un snapshot antes de eliminar un worktree gestionado, y cuando abras el chat, verás la opción de restaurarlo.

¿Por qué mis archivos .env no están en el worktree?

Los archivos ignorados no se copian a menos que coincidan con un patrón en .worktreeinclude en la raíz del repositorio.

¿Dónde almacena Codex los worktrees?

En $CODEX_HOME/worktrees por defecto. Puedes cambiar la ubicación en Settings, luego Worktrees, y después Worktree root.

¿Por qué no puedo activar la rama del worktree localmente?

Git permite que una rama esté activa en un solo lugar a la vez. Usa Handoff para mover el chat a Local en su lugar.

¿Archivar un chat de Codex elimina su worktree?

Sí. Archivar el chat asociado es uno de los disparadores para eliminar un Codex-managed worktree.