Los worktrees permiten que Codex trabaje en varios chats independientes dentro del mismo proyecto sin que interfieran entre sí. El repositorio y el worktree permanecen en la computadora o en el entorno de desarrollo remoto donde se encuentra el proyecto. Los comandos también se ejecutan allí. Puedes trabajar directamente en la aplicación de escritorio de ChatGPT o usar Codex en la aplicación móvil de ChatGPT para iniciar chats en los worktrees de una computadora conectada, guiar el trabajo, aprobarlo y revisarlo.
En los repositorios de Git, las tareas programadas pueden ejecutarse en segundo plano en worktrees dedicados, sin interferir con tu trabajo en curso. En los proyectos sin control de versiones, las tareas programadas se ejecutan directamente en el directorio del proyecto. También puedes iniciar chats manualmente en un worktree y usar la función de transferencia para mover un chat entre Local y Worktree.
Los worktrees no se ejecutan en tu teléfono. Desde la aplicación móvil de ChatGPT puedes controlar Codex en tu computadora conectada o en el entorno de desarrollo remoto que usa esa computadora. El repositorio y el worktree permanecen donde se ejecuta Codex. Las siguientes instrucciones para la aplicación de escritorio se aplican a la computadora conectada.
Qué es un worktree
Los worktrees solo funcionan en proyectos que forman parte de un repositorio de Git, ya que Codex usa los worktrees de Git. Un worktree te permite crear una segunda copia de trabajo (“checkout”) de tu repositorio. Cada worktree tiene su propia copia de cada archivo del repositorio, pero todos comparten los mismos metadatos (la carpeta .git) sobre los commits, las ramas y otros elementos. Así puedes tener varias ramas activas y trabajar en ellas en paralelo.
Terminología
- Copia de trabajo local: el repositorio que creaste. En la aplicación de escritorio de ChatGPT, a veces aparece simplemente como Local.
- Worktree: un worktree de Git creado a partir de tu copia de trabajo local en la aplicación de escritorio de ChatGPT.
- Transferencia: el proceso que permite mover un chat entre Local y Worktree. Codex se encarga de las operaciones de Git necesarias para trasladar tu trabajo de forma segura entre ambos entornos.
Por qué usar un worktree
- Trabaja en paralelo con Codex sin alterar tu configuración actual en Local.
- Pon tareas en cola para que se ejecuten en segundo plano mientras te concentras en lo que estás haciendo.
- Mueve un chat a Local más adelante, cuando quieras revisar los cambios, probarlos o colaborar de forma más directa.
Primeros pasos
Los worktrees requieren un repositorio de Git. Asegúrate de que el proyecto que seleccionaste forme parte de uno.
-
Selecciona “Worktree”
En la vista de chat nuevo, selecciona Worktree debajo del editor. Si quieres ejecutar scripts de configuración para el worktree, elige un entorno local.
-
Selecciona la rama de partida
Debajo del editor, elige la rama de Git a partir de la cual se creará el worktree. Puede ser tu rama
mainomaster, una rama de desarrollo de una funcionalidad o tu rama actual con cambios locales que aún no agregaste al área de preparación. -
Envía tu prompt
Envía tu prompt y Codex creará un worktree de Git a partir de la rama que seleccionaste. De forma predeterminada, Codex trabaja con HEAD desacoplado.
-
Elige dónde seguir trabajando
Cuando quieras, puedes seguir trabajando directamente en el worktree o transferir el chat a tu copia de trabajo local. Al hacer una transferencia hacia o desde Local, se trasladan el chat y el código para que puedas continuar en la otra copia de trabajo.
Cómo trabajar entre Local y Worktree
Trabajar en un worktree es muy parecido a trabajar en tu copia local. La diferencia está en cómo usas cada entorno. Puedes usar Local para trabajar en primer plano y Worktree para trabajar en segundo plano. La función de transferencia te permite mover un chat entre ambos.
Durante la transferencia, Codex se encarga de las operaciones de Git necesarias para mover el trabajo de forma segura entre las dos copias. Esto es importante porque Git solo permite tener una rama activa en un lugar a la vez. Si activas una rama en un worktree, no puedes activarla al mismo tiempo en tu copia de trabajo local, y viceversa.
En la práctica, hay dos opciones habituales:
- Trabajar exclusivamente en el worktree. Esta opción es la más adecuada cuando puedes verificar los cambios directamente en el worktree, por ejemplo, si instalaste las dependencias y las herramientas con un script de configuración del entorno local.
- Transferir el chat a Local. Usa esta opción cuando quieras pasar el chat a primer plano, por ejemplo, para revisar los cambios en tu IDE habitual o si solo puedes ejecutar una instancia de tu aplicación.
Opción 1: trabajar en el worktree
Si quieres seguir trabajando con tus cambios exclusivamente en el worktree, crea una rama a partir de su estado actual con el botón Crear rama aquí del encabezado del chat.
A partir de ahí, puedes hacer un commit de tus cambios, subir la rama a tu repositorio remoto y abrir un pull request en GitHub.
Con el botón “Abrir” del encabezado puedes abrir el worktree en tu IDE. También puedes usar la terminal integrada o realizar cualquier otra tarea que necesites desde el directorio del worktree.
Recuerda que, si creas una rama en un worktree, no puedes activarla en ningún otro worktree, incluida tu copia de trabajo local.
Opción 2: transferir un chat a Local
Si quieres pasar un chat a primer plano, selecciona Transferir en el encabezado del chat y muévelo a Local.
Esta opción es útil si quieres revisar los cambios en la ventana de tu IDE habitual, ejecutar tu servidor de desarrollo o validar el trabajo en el mismo entorno que usas a diario.
Codex se encarga de las operaciones de Git necesarias para mover el chat de forma segura entre el worktree y tu copia de trabajo local.
Cada chat conserva su vínculo con el mismo worktree. Si más adelante vuelves a transferir el chat a un worktree, Codex lo devuelve al mismo entorno en segundo plano para que puedas retomar el trabajo donde lo dejaste.
También puedes hacer la transferencia en sentido contrario. Si ya trabajas en Local y quieres liberar el primer plano, usa Transferir para mover el chat a un worktree. Así, Codex puede seguir trabajando en segundo plano mientras tú retomas otra tarea en tu entorno local.
Como la transferencia usa operaciones de Git, los archivos que excluyas mediante .gitignore no se trasladarán con el chat, a menos que Codex los copie a un worktree local administrado mediante .worktreeinclude.
Detalles avanzados
Worktrees administrados por Codex
De forma predeterminada, los chats usan worktrees administrados por Codex. Están diseñados para que sea fácil usarlos y descartarlos. Por lo general, Codex dedica cada worktree administrado a un solo chat. Si más adelante transfieres el chat de vuelta, Codex lo devuelve a ese mismo worktree.
Cómo administra Codex tus worktrees
Codex crea los worktrees en $CODEX_HOME/worktrees. El commit de partida es el commit HEAD de la rama que seleccionas al iniciar el chat. Si eliges una rama con cambios locales, Codex también aplica al worktree los cambios que aún no incluiste en un commit. El worktree no tiene una rama activa. Está en estado de HEAD desacoplado. Así, Codex puede crear varios worktrees sin añadir ramas innecesarias.
Cómo copiar archivos locales ignorados a worktrees administrados
Los worktrees locales administrados por Codex se crean a partir de una copia de trabajo de Git, así que ya contienen los archivos bajo control de versiones. Si tu repositorio ignora archivos de configuración local que necesita un worktree nuevo, agrega un archivo .worktreeinclude en la raíz del repositorio. Incluye las rutas ignoradas o los patrones de tipo .gitignore que indiquen qué archivos debe copiar Codex al crear un worktree administrado.
Usa este mecanismo para archivos que Git ignora de forma intencional, como .env, .env.local o config/secrets.json. Codex solo copia los archivos ignorados que coinciden con las entradas de .worktreeinclude. No copia otros archivos locales que estén fuera del control de versiones de Git. No incluyas archivos que ya estén bajo control de versiones.
Si Git ignora AGENTS.override.md, Codex lo copia automáticamente a los worktrees locales administrados, por lo que no necesitas incluirlo en .worktreeinclude.
# .worktreeinclude
.env
.env.local
config/secrets.jsonCodex omite los enlaces simbólicos de origen y no sobrescribe los archivos que ya existen en la nueva copia de trabajo. Este comportamiento se aplica únicamente a los worktrees locales que administra la aplicación de escritorio de ChatGPT. Quedan excluidos los worktrees remotos y los worktrees de Git que creas por tu cuenta desde la línea de comandos.
Limitaciones de las ramas
Supongamos que Codex termina una tarea en un worktree y decides crear allí la rama feature/a con Crear rama aquí. Ahora quieres probarla en tu copia de trabajo local. Si intentaras activar la rama, obtendrías el siguiente error:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'Para resolverlo, tendrías que activar otra rama en el worktree en lugar de feature/a.
Si quieres activar la rama en tu copia local, usa la función de transferencia para mover el chat a Local en vez de intentar mantener la misma rama activa en ambos lugares a la vez.
Por qué existe esta limitación
Git impide que una misma rama esté activa en más de un worktree a la vez porque cada rama representa una única referencia modificable (refs/heads/<name>) que indica “el estado activo actual” de una copia de trabajo.
Cuando una rama está activa, Git considera que su HEAD pertenece a ese worktree y espera que operaciones como git commit, git reset, git rebase y git merge actualicen esa referencia una a la vez y en un orden bien definido. Si varios worktrees pudieran tener activa la misma rama al mismo tiempo, no quedaría claro qué worktree debe actualizar la referencia de la rama y podrían producirse condiciones de carrera. Como consecuencia, podrían perderse commits, quedar índices inconsistentes o resultar difícil determinar cómo resolver los conflictos.
Al limitar cada rama activa a un solo worktree, Git garantiza que cada rama tenga una única copia de trabajo de referencia. Los demás worktrees pueden seguir apuntando de forma segura a los mismos commits con HEAD desacoplado o desde ramas distintas.
Limpieza de worktrees
Los worktrees pueden ocupar mucho espacio en disco. Cada uno tiene sus propios archivos del repositorio, dependencias, cachés de compilación y otros elementos. Por eso, la aplicación de escritorio de ChatGPT procura limitar la cantidad de worktrees que conserva.
De forma predeterminada, Codex conserva los 15 worktrees más recientes que administra. Si prefieres gestionar el uso del disco por tu cuenta, puedes cambiar este límite o desactivar la eliminación automática en la configuración.
Codex procura conservar los worktrees que aún son importantes. Un worktree administrado por Codex no se elimina automáticamente si se cumple alguna de estas condiciones:
- Tiene un chat fijado asociado.
- El chat sigue en curso.
Los worktrees permanentes creados en versiones anteriores siguen disponibles y están protegidos de la limpieza automática. Ya no puedes crear worktrees permanentes desde el menú del proyecto.
Los worktrees administrados por Codex se eliminan automáticamente en los siguientes casos:
- Archivas el chat asociado.
- Codex necesita eliminar worktrees antiguos para respetar el límite que configuraste.
Antes de eliminar un worktree que administra, Codex guarda una instantánea del trabajo que contiene. Si abres un chat después de que se haya eliminado su worktree, verás la opción de restaurarlo.
Preguntas frecuentes
¿Puedo elegir dónde se crean los worktrees?
Sí. De forma predeterminada, Codex crea los worktrees administrados en $CODEX_HOME/worktrees. Para elegir otra ubicación, abre Configuración > Worktrees y cambia Directorio raíz de los worktrees.
¿Puedo mover un chat entre Local y Worktree?
Sí. Usa Transferir en el encabezado del chat para moverlo entre tu copia de trabajo local y un worktree. Codex se encarga de las operaciones de Git necesarias para mover el chat de forma segura entre los dos entornos. Si más adelante transfieres el chat de vuelta a un worktree, Codex lo devuelve al mismo worktree asociado.
¿Qué pasa con los chats si se elimina un worktree?
Los chats pueden permanecer en tu historial aunque se elimine el directorio del worktree. Si Codex administra el worktree, guarda una instantánea antes de eliminarlo y te ofrece restaurarlo cuando vuelves a abrir el chat asociado.