Aislamiento en paralelo con Worktrees: cómo hacer que varios Codex trabajen de forma independiente sin interferir entre sí
📚 Navegación de la serie: El artículo anterior 〔24 Reglas y disparadores (Hooks)〕 equipó a Codex con "puertas" y "disparadores" para automatizar tareas repetitivas. Este artículo cambia de dimensión: no se trata de hacer que un solo Codex haga más cosas, sino de permitir que varias tareas comiencen verdaderamente al mismo tiempo sin estorbarse entre sí. Worktree (árbol de trabajo) es el método de aislamiento principal que utiliza Codex para lograr esto: cómo crearlo, cómo usarlo, por qué la misma rama no se puede extraer en dos lugares a la vez, y cómo Handoff (traspaso) mueve el trabajo entre el primer plano y el fondo. El siguiente artículo 〔26 Integración con Git y GitHub〕 explicará cómo confirmar, enviar y abrir PR después de realizar los cambios.
Les contaré una tontería que hice en marzo de este año.
Ese día, para ahorrar tiempo, abrí dos hilos Local (locales) al mismo tiempo en la App de escritorio de Codex para modificar el mismo repositorio. En uno le pedí que refactorizara la capa de datos y en el otro que modificara las rutas de paso. Estaba muy feliz pensando que la doble ejecución me daría el doble de eficiencia. Como resultado, ambos hilos modificaron el mismo config.ts, y cuando el segundo hilo confirmó sus cambios, sobrescribió la mitad de lo que el primero acababa de escribir. Me quedé mirando ese montón de bloques rojos y verdes en git diff durante varios minutos antes de darme cuenta: no es que Codex se hubiera vuelto loco, es que puse a dos personas a pelearse por el mismo bolígrafo en la misma mesa.
Después de eso, comencé a usar honestamente lo que debí haber usado desde el principio: Worktree. Si el mismo proyecto requiere procesamiento en paralelo, siempre abro un Worktree, de modo que cada hilo obtenga una copia aislada del código. Desde entonces, nunca más he tenido problemas de "sobrescritura mutua".
En el artículo 07, al hablar de la App de escritorio, ya mencioné brevemente Worktree: es uno de los tres modos (Local / Worktree / Cloud) para nuevos hilos, combinado con Handoff para moverse entre el primer plano y el fondo (el modo Cloud (nube) no se detalla en este artículo, se trata por separado en 〔10 Tareas en la nube〕). En este artículo profundizaremos: cómo funciona realmente el aislamiento en la capa inferior, por qué existe la regla estricta de que "una rama solo se puede extraer en un lugar", cómo se realiza el Handoff en ambas direcciones y cómo limpiar las copias acumuladas. Si no se explican claramente estos posibles problemas, tarde o temprano tropezarán con ellos.
Al terminar de leer este artículo, obtendrás:
- Una explicación sencilla de lo que resuelve Worktree y su diferencia fundamental con "abrir dos hilos Local simultáneamente"
- Los pasos completos para crear un hilo de Worktree en la App de escritorio, además del hecho contraintuitivo de que por defecto está en estado detached HEAD (cabeza desprendida)
- La regla estricta con la que es más fácil tropezar: la misma rama no se puede extraer en dos lugares a la vez, qué error se muestra cuando ocurre y cómo evitarlo
- Las dos rutas comunes de Handoff (traspaso) para mover hilos en ambas direcciones entre Local y Worktree, y cuándo usar cada una
- Cómo usar el script setup de Local environment (entorno local) para que un nuevo worktree tenga las dependencias instaladas y todo lo necesario en cuanto se cree
- Qué hacer si los worktrees acumulados ocupan demasiado espacio en disco: cuántos se conservan por defecto, qué cosas no se eliminarán y si se pueden recuperar las capturas (snapshots) antes de borrarlos
⚠️ Worktree, Handoff y Local environments son funciones de la App de escritorio (desktop app) de Codex, no tienen interruptores correspondientes como
--worktreeen la CLI; no los busques en la terminal. Cualquier botón específico, valor predeterminado o elemento de configuración mencionado a continuación se basa en la documentación oficial de Codex (Worktrees / Local environments); las funciones pueden cambiar con las versiones, así que confíe en la interfaz real que se ejecuta en su máquina.
01 Primero piénselo bien: ¿Qué problema resuelve realmente Worktree?
Primero la conclusión: Worktree resuelve el escenario de "querer realizar varias tareas no relacionadas al mismo tiempo en el mismo repositorio sin sobrescribirse entre sí". Su única premisa fundamental es: no deje que estas tareas compitan por escribir en el mismo archivo.
Si recordamos los artículos anteriores, básicamente hemos estado trabajando en "un solo hilo": abrimos una tarea, damos instrucciones y la completamos paso a paso. Este modo es suficiente para el 90% de los trabajos. Pero hay dos situaciones en las que te sentirás limitado.
La primera es cuando varias tareas se pueden separar de forma natural y no dependen entre sí. Por ejemplo, "modificar los estilos del frontend", "corregir un error del backend" y "agregar un lote de pruebas". No tienen relación alguna, pero te ves obligado a hacer fila: modificar el frontend antes de pasar al backend. Claramente podrían hacerse al mismo tiempo.
La segunda es cuando quieres probar una idea nueva pero no te atreves a tocar el trabajo actual que aún no has terminado. Hay un montón de cambios sin confirmar en el área de trabajo actual, y de repente quieres verificar otra idea. Si lo haces directamente en el mismo lugar, en caso de que salga mal, arruinarás también lo que no habías terminado.
En este punto podrías pensar: ¿entonces no puedo simplemente abrir varios hilos? Ahí es donde está la trampa. Si abres varios hilos en modo Local apuntando al mismo directorio del proyecto, estarás cometiendo la misma tontería que yo al principio: varios Codex modificando el mismo archivo al mismo tiempo, donde el último en escribir sobrescribe al anterior.
Analogía: La hoja de interconsulta de un hospital. Solo hay un historial clínico original del paciente. Si los médicos de tres departamentos diferentes quieren dar su opinión al mismo tiempo y escriben todos en el mismo cuaderno, las notas inevitablemente chocarán y se sobrescribirán entre sí. La práctica correcta es: dar a cada médico una copia del historial clínico para escribir, de modo que cada uno escriba en la suya y al final se consoliden en el original. Eso es precisamente lo que hace Worktree: a partir del mismo historial de repositorio, genera varios directorios de trabajo independientes, cada uno con su propio conjunto completo de archivos, pero compartiendo el mismo .git (el historial de confirmaciones, ramas y otros metadatos son los mismos). Los cambios que realice un hilo en su copia nunca afectarán a la copia de otro hilo.
La documentación oficial explica este valioso punto de forma muy directa:
Cada worktree tiene una copia independiente de cada archivo en su repositorio, pero comparten los mismos metadatos sobre confirmaciones, ramas, etc. (la carpeta
.git). Esto le permite extraer y trabajar en varias ramas en paralelo.
En los escenarios reales con los que se encontrará, las tareas adecuadas para usar Worktree son:
- "Quiero enviar estos dos módulos no relacionados al mismo tiempo, uno para corregir un bug y otro para agregar una función" — abre un hilo de Worktree para cada uno y no interferirán.
- "He modificado la mitad de las cosas sin confirmar y de repente quiero probar otra solución" — abre un Worktree para probar; el original no se moverá y si sale mal, simplemente lo descartas.
- "Dejar que Codex ejecute una gran refactorización lentamente en el fondo mientras yo continúo trabajando en otra cosa en el primer plano" — mándalo al fondo en un worktree para que se ejecute (se detalla en la siguiente sección).
💡 Resumen en una frase: Worktree sirve para permitir que tareas independientes en el mismo repositorio comiencen al mismo tiempo sin sobrescribirse (como dar a cada médico una copia del historial clínico). La única regla estricta es: no deje que compitan por escribir en el mismo archivo, de lo contrario, cuanto más en paralelo trabaje, más caos habrá.
Imagen superior: El mismo repositorio Git deriva tres worktrees independientes; tres tareas de Codex ocupan una cada una sin sobrescribirse.
02 Crear un hilo de Worktree en la App de escritorio
Una vez que sabemos por qué usarlo, veamos cómo crearlo. Todo el proceso se realiza haciendo unos clics en la App de escritorio, sin tener que escribir comandos.
Worktree solo se puede usar en repositorios Git (en la capa inferior utiliza la funcionalidad git worktree). El proyecto seleccionado debe ser un repositorio git, de lo contrario la opción no aparecerá.
Crear en cuatro pasos
Paso 1: Para un nuevo hilo, seleccione el modo Worktree. Debajo del cuadro de entrada del nuevo hilo, cambie el modo de Local (por defecto) a Worktree. (De paso, puede elegir un local environment para ejecutar el script setup, detallado en la sección 05).
Paso 2: Seleccione "desde qué rama empezar". Debajo del cuadro de entrada, se le pedirá elegir en qué rama se basará este worktree para crearse: puede ser main / master, alguna rama de función, o su rama actual junto con los cambios locales que aún no se han preparado (staged). Este detalle es muy práctico: puede llevarse lo que ha modificado a medias en su área de trabajo actual al worktree para continuar.
Paso 3: Envíe su instrucción. Envíe la tarea y Codex creará un git worktree basado en la rama seleccionada y comenzará a trabajar en él.
Paso 4: Decida a dónde ir al terminar. Al finalizar, tiene dos caminos: quedarse en este worktree para continuar (confirmar, enviar, abrir PR) o usar Handoff para traspasar el hilo de vuelta a Local (sección 04).
Un hecho contraintuitivo pero crucial: worktree está por defecto en detached HEAD
Este es el punto con el que los principiantes se confunden más fácilmente, por lo que es necesario mencionarlo específicamente.
El worktree creado por Codex no está por defecto en ninguna rama, sino en un estado llamado detached HEAD (cabeza desprendida); puede entenderlo como "apuntar directamente a una confirmación específica en lugar de apuntar al nombre de una rama". Palabras textuales de la documentación oficial:
Por defecto, Codex trabaja en estado "HEAD desprendido".
¿Por qué se diseñó así? La explicación oficial es muy práctica: de esta manera, Codex puede crear varios worktrees a la vez sin contaminar su lista de ramas. Su git branch no tendrá de repente cinco nombres de rama extraños solo porque abrió cinco worktrees.
¿And qué pasa si quiero convertir estos cambios en una rama normal? En la parte superior del hilo hay un botón Create branch here (Crear rama aquí); haga clic en él y el worktree actual se convertirá en una rama, tras lo cual podrá confirmar, enviar y abrir PR en ella.
💡 Resumen en una frase: Crear un hilo de Worktree requiere solo cuatro pasos: elegir el modo Worktree → elegir la rama inicial → enviar instrucciones → decidir si quedarse o irse. Recuerde que por defecto está en detached HEAD (sin estar en ninguna rama); si quiere confirmar y enviar de forma normal, primero haga clic en Create branch here para convertirlo en una rama.
03 La regla estricta que más debe dominar: una rama no se puede extraer en dos lugares a la vez
Esta sección es corta, pero más crucial que las anteriores. Muchas personas han tropezado con esto, incluido yo.
Dejemos clara la regla de inmediato. Git tiene una regla estricta: una rama solo puede estar extraída en un árbol de trabajo a la vez. Si ha extraído feature/a en un worktree, su copia local original (Local) no puede extraer feature/a al mismo tiempo, y viceversa.
Analogía: El mismo libro en una biblioteca. Un libro solo tiene una copia física. Si A lo toma prestado, B no puede tomar el mismo; no es que la biblioteca sea egoísta, es que el estado de "en manos de quién está actualmente" solo puede tener una respuesta definitiva en un momento dado. Las ramas de git funcionan igual: un nombre de rama (refs/heads/<name>) representa la única respuesta a "cuál es el estado actual de este árbol de trabajo". Si se permitiera extraer y confirmar en dos lugares al mismo tiempo, se generaría un caos sobre a quién escuchar; podrían perderse confirmaciones o haber conflictos en el índice. Por lo tanto, git corta por lo sano: una rama solo se reconoce en un árbol de trabajo a la vez.
¿Qué pasa si tropieza con esto? Supongamos que Codex termina su trabajo en un worktree y usted crea la rama feature/a mediante Create branch here. Si en ese momento intenta extraer feature/a en su copia local original, git le lanzará un error directamente:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'Significa que esta rama ya está ocupada por ese worktree y no se puede extraer de forma local.
¿Qué hacer entonces? La solución correcta no es insistir, sino usar Handoff. La documentación oficial ofrece dos opciones:
- Si solo desea echar un vistazo rápido: extraiga otra rama en el worktree para liberar
feature/a. - Si realmente quiere mover esa línea de trabajo a la copia local para continuar: use Handoff para traspasar todo el hilo a Local (se detalla en la siguiente sección), en lugar de intentar extraer la misma rama en ambos lados simultáneamente.
💡 Resumen en una frase: Una rama solo se puede extraer en un árbol de trabajo a la vez (como un libro físico de la biblioteca que solo se puede prestar a una persona). Intentar extraerla en dos lugares generará el error
already used by worktree. Si desea trasladar el trabajo a local, use Handoff en lugar de forzar las ramas.
04 Handoff: Traspasar hilos en ambas direcciones entre Local y Worktree
Hemos mencionado Handoff repetidamente en la sección anterior; ahora lo explicaremos a fondo. Es la solución oficial de Codex para resolver el problema de "la misma rama no se puede extraer en dos lados" y es una acción que usará a diario en el flujo de trabajo de worktree.
Primero, comprenda este modelo mental: Local es el primer plano, Worktree es el fondo. Local (copia local original) es el área de trabajo donde usted opera directamente, abre su IDE habitual y ejecuta servidores de desarrollo; equivale al escritorio frente a usted. Worktree es la copia aislada en segundo plano que avanza silenciosamente. Handoff se encarga de mover un hilo entre el primer plano y el fondo.
Analogía: La barra abierta y la cocina de preparación de un restaurante. La barra (Local) es el lugar visible donde los clientes ven al chef servir los platos. La cocina de preparación (Worktree) está detrás, picando, preparando y guisando silenciosamente. Dónde preparar un plato depende del momento: si requiere un acabado final cara a cara o verificar la presentación antes de servir, se lleva a la barra; si se quiere liberar la barra para otras cosas y dejar que el plato se guise lentamente, se traslada a la cocina. Handoff es esa acción de "entrar y salir", y Codex se encargará de gestionar de forma segura las operaciones de git subyacentes por usted, sin que tenga que escribir comandos git worktree usted mismo.
La documentación oficial señala la razón fundamental de la existencia de Handoff, conectando con la sección anterior:
Esto es importante porque Git solo permite extraer una rama en un lugar a la vez.
Tiene dos direcciones, que corresponden a dos rutas comunes:
Dirección 1: Worktree → Local (mover el hilo del fondo al primer plano). Haga clic en Hand off en la parte superior del hilo y elija Local. ¿Cuándo usarlo? Cuando quiera realizar la validación usando su entorno habitual (leer diferencias en su ventana de IDE habitual, ejecutar su servidor de desarrollo existente, o si su app solo permite una instancia y no puede iniciar otra en el worktree). Yo mismo uso esta ruta con frecuencia: dejo que Codex complete una función en segundo plano en el worktree, y una vez terminada, la traspaso a Local para revisar el código línea por línea en mi editor de confianza.
Dirección 2: Local → Worktree (enviar el hilo del primer plano al fondo). También funciona a la inversa. Si está trabajando en Local y quiere liberar el primer plano para hacer otra cosa, use Hand off para trasladar el hilo al worktree, de modo que Codex sigue ejecutándose en segundo plano mientras usted vuelve a concentrarse en otros asuntos locales.
Un detalle práctico que suele pasarse por alto: cada hilo permanece vinculado siempre al mismo worktree. Si lo traspasa a Local y más tarde decide enviarlo de vuelta al fondo, Codex lo devolverá al mismo worktree original para que continúe desde el progreso anterior, en lugar de empezar de cero.
Un último problema que debe recordar:
Dado que Handoff utiliza operaciones de Git, cualquier archivo que esté en su
.gitignoreno se trasladará con el hilo.
Es decir, los elementos no rastreados por git como .env o cachés locales no se moverán con el Handoff. Esto coincide con la naturaleza de "copia nueva y limpia" del propio worktree. La siguiente sección explica cómo solucionar esta limitación.
| Worktree → Local | Local → Worktree | |
|---|---|---|
| Dirección | Del segundo plano al primer plano | Del primer plano al segundo plano |
| Escenario típico | Validación con IDE habitual, servidores de desarrollo de una sola instancia | Liberar el primer plano para otros asuntos dejando que continúe en segundo plano |
| Quién gestiona git | Codex lo gestiona automáticamente | Codex lo gestiona automáticamente |
Archivos en .gitignore | No se trasladan | No se trasladan |
💡 Resumen en una frase: Handoff permite traspasar hilos en ambas direcciones entre Local (primer plano) y Worktree (segundo plano) (como mover platos entre la barra y la cocina). Codex gestiona de forma segura las operaciones de git, pero los archivos en
.gitignoreno se trasladan.
05 Equipar los nuevos worktrees desde el inicio: el script setup de Local environment
Siguiendo con la limitación de la sección anterior: un worktree es una copia recién extraída que se ejecuta en un directorio diferente al de Local, por lo que inicialmente no tiene las dependencias, configuraciones ni archivos locales que no estén incluidos en git. El caso más común es: al ejecutar el nuevo worktree, falta node_modules o .env, lo que detiene el trabajo de inmediato.
En abril tropecé una vez con esto: abrí con entusiasmo un Worktree para que Codex modificara el backend, pero no pudo conectarse a la base de datos. Tardé un rato en darme cuenta de que .env no estaba en el worktree (como dijimos antes, las cosas en .gitignore no se trasladan). Después de agregar el script setup, no volví a tener este problema.
Analogía: La "lista de apertura" al abrir una nueva sucursal de una franquicia. La tienda principal (su Local) tiene todo listo; la nueva sucursal (worktree) está vacía. Una franquicia inteligente tiene una lista de apertura estándar: abastecer inventario, instalar equipos, decorar. Al seguirla paso a paso, la nueva tienda puede abrir de inmediato. El script setup de Local environment es esa lista de comprobación: Codex la ejecuta automáticamente cada vez que crea un worktree para un nuevo hilo para instalar las dependencias y realizar las compilaciones necesarias.
¿Dónde y cómo se configura? La documentación oficial lo explica claramente:
- Configure el local environment a través del panel de configuración (settings) de la App de Codex; la configuración generada se guarda en la carpeta
.codexen el directorio raíz de su proyecto. - Este archivo de configuración se puede subir a git para compartirlo con el equipo; configúrelo una vez y los worktrees de todo el equipo se equiparán automáticamente.
Tomemos como ejemplo un proyecto TypeScript provisto oficialmente; el script setup consta de solo dos líneas:
npm install
npm run buildCuando se crea el nuevo worktree, estas dos líneas se ejecutan automáticamente, instalando las dependencias y realizando la compilación inicial, permitiendo que Codex empiece a trabajar de inmediato sin que le falte nada.
Diferencias de plataforma: Si sus pasos de configuración dependen de la plataforma (macOS / Windows / Linux), puede definir scripts setup separados para cada plataforma para anular el predeterminado. El rango de disponibilidad de la App de escritorio en Windows se basa en la documentación oficial de Windows.
Por cierto, una capacidad relacionada: además del script setup, local environment también permite configurar Actions (acciones) para convertir comandos comunes como "iniciar servidor de desarrollo" o "ejecutar pruebas" en botones de acceso directo en la barra superior de la App. Al hacer clic en ellos, se ejecutan en la terminal integrada. Esto se mencionó brevemente en el artículo 07 y no se detallará aquí.
💡 Resumen en una frase: El worktree es una copia limpia, por lo que las dependencias y el
.envque no están en git no aparecerán en él. Use el script setup de local environment (guardado en.codexdel proyecto y que se puede confirmar en git) para que instale automáticamente las dependencias al crearse, como abrir una tienda siguiendo una "lista de apertura".
06 Qué hacer cuando se acumulan demasiados Worktrees: limpieza, límites y recuperación de capturas
Cuando se utiliza mucho la ejecución en paralelo, surge un problema real: los worktrees ocupan espacio en disco. Cada uno tiene su propio conjunto completo de archivos de proyecto, dependencias y cachés de compilación. Si abre más de diez, el disco se reducirá visiblemente. Por ello, Codex le ayuda a mantener la cantidad de worktrees bajo control en un rango razonable.
Primero, analicemos dos hechos de la capa inferior para evitar que ande buscando dónde están los worktrees:
- Codex crea y administra todos los worktrees bajo
$CODEX_HOME/worktrees(por defectoCODEX_HOMEes~/.codex, mencionado en el artículo de configuración 18). - Por defecto, Codex conserva los 15 worktrees más recientes administrados por Codex; este límite se puede cambiar en la configuración o puede desactivar la eliminación automática para administrar el disco usted mismo.
¿Cuál es la regla de eliminación de worktrees de Codex? Intentará no borrar los que sigan siendo importantes. Según la documentación oficial:
En los siguientes casos, el worktree administrado por Codex no se eliminará automáticamente:
- Hay una conversación fijada (pinned) vinculada a él
- El hilo correspondiente sigue en curso
- Es un worktree permanente (permanent worktree, ver más abajo)
Se eliminarán automáticamente en los siguientes casos:
- Ha archivado (archive) el hilo correspondiente
- Codex necesita eliminar worktrees más antiguos para no superar el límite establecido
La regla más tranquilizadora: hay una captura antes de borrar:
Antes de eliminar un worktree administrado por Codex, Codex guardará una captura (snapshot) del trabajo en ese worktree. Si abre la conversación correspondiente después de haber eliminado el worktree, verá una opción para restaurarlo.
Es decir, incluso si un worktree se limpia automáticamente, el hilo en sí sigue en su historial, y al reabrirlo podrá elegir restaurarlo, por lo que no perderá todo al borrarse.
Por último, distingamos dos conceptos para evitar confusiones: worktree administrado por Codex vs. worktree permanente.
| Worktree administrado por Codex (predeterminado) | Worktree permanente (permanent) | |
|---|---|---|
| Origen | Creado automáticamente por Codex al abrir un hilo de Worktree | Creado manualmente desde el menú de tres puntos del proyecto en la barra lateral |
| Vínculo con hilos | Suele ser exclusivo de un hilo | Permite iniciar varios hilos desde el mismo worktree |
| ¿Se elimina automáticamente? | Sí (al superar el límite o archivar) | No se elimina automáticamente |
| Adecuado para | Tareas temporales ligeras que se descartan tras su uso | Entornos fijos a largo plazo a los que se desea regresar repetidamente |
En pocas palabras: para probar ideas temporales, use el predeterminado, ya que se limpiará solo tras su uso; si desea un entorno estable a largo plazo al que regresar repetidamente, cree un worktree permanente desde el menú de tres puntos del proyecto, el cual se convertirá en un proyecto independiente y no se borrará automáticamente.
💡 Resumen en una frase: Los worktrees se crean en
$CODEX_HOME/worktrees, y por defecto se conservan los 15 más recientes, borrándose automáticamente al superar el límite o archivarse (se guarda una captura antes de borrar para poder restaurarlos). Los que estén fijados, en curso o sean permanentes no se borrarán. Use los predeterminados para tareas temporales y cree worktrees permanentes para entornos a largo plazo.
07 Práctica: ejecutar una cadena principal de Worktree en la App de escritorio
Ver sin practicar no sirve de nada. La siguiente ruta se realiza por completo mediante clics en la App de escritorio de Codex, y solo requiere un proyecto git. se proporcionan los resultados esperados para cada paso para que pueda validarlos usted mismo y adquirir memoria muscular.
Utilice un repositorio git (si no tiene uno, cree uno cualquiera con
git initpara practicar). Este es un flujo exclusivo de la App de escritorio, no hay un interruptor equivalente en la CLI. Las siguientes operaciones no dependen de una conexión VPN.
Paso 1: Para un nuevo hilo, cambie el modo a Worktree
Haga clic en nuevo hilo en la App, cambie el modo debajo del cuadro de entrada de Local a Worktree y seleccione una rama inicial (elija main para practicar).
Resultado esperado: El modo se muestra como Worktree y aparece la opción de selección de la "rama inicial" en la parte inferior. Ver esto significa que se prepara para abrir una copia aislada sin alterar el original.
Paso 2: Envíe una pequeña tarea de solo lectura
Envíe cualquier instrucción simple y segura que no modifique archivos, por ejemplo: "Enumera los títulos de todos los archivos markdown en este proyecto."
Resultado esperado: Codex crea un worktree basado en la rama seleccionada y comienza a trabajar en él. El directorio de trabajo de este hilo se encuentra en $CODEX_HOME/worktrees (por defecto ~/.codex/worktrees), constituyendo una copia independiente de su Local original.
Paso 3: Confirme que es un worktree independiente en la terminal integrada
Abra la terminal integrada del hilo (en macOS Cmd + J; en Windows use el atajo correspondiente de su equipo) y ejecute:
git worktree listResultado esperado: En la lista, además de su extracción principal, aparece una línea adicional que apunta al directorio .../.codex/worktrees/.... Ver esa línea significa que la copia aislada se creó correctamente y se encuentra actualmente en ella.
Paso 4: Pruebe a realizar un Handoff de vuelta a Local
Haga clic en Hand off en la parte superior del hilo y elija mover a Local.
Resultado esperado: Este hilo se traslada a su copia local original, permitiéndole ver los cambios en su entorno IDE / terminal habitual. Codex gestiona automáticamente las operaciones de git subyacentes sin necesidad de escribir comandos git worktree manualmente.
Paso 5: Limpieza
Si no desea conservar el worktree de práctica temporal, la forma más sencilla es archivar (archive) el hilo. Según las reglas de la sección 06, el worktree administrado por Codex se limpiará automáticamente tras archivar (se conserva una captura, por lo que si se arrepiente puede restaurarlo desde el hilo). También puede verificar el límite de cantidad de worktrees y el interruptor de eliminación automática en la configuración.
Resultado esperado: Tras archivar, el hilo desaparece de la lista de actividades y el worktree correspondiente entra en limpieza automática; la copia en disco se libera. La limpieza completa indica que se ha completado toda la cadena principal de forma exitosa.
Al realizar estos cinco pasos, habrá completado personalmente la cadena principal de "abrir copia aislada → confirmar independencia → traspasar a Local para validación → limpiar". En el trabajo en paralelo real, el proceso es básicamente el mismo, solo que con diferentes tareas y abriendo varios hilos de Worktree.
💡 Resumen en una frase: La cadena de práctica consta de cinco pasos: abrir un hilo en modo Worktree → enviar una pequeña tarea para crear el worktree → usar
git worktree listpara confirmar la independencia → realizar Hand off a Local para validación → archivar el hilo para que se limpie automáticamente. Completar este proceso una vez es más útil que memorizar diez comandos.
08 Resumen
Este artículo ha explicado el proceso de "hacer que varios Codex comiencen a trabajar al mismo tiempo en el mismo repositorio sin interferir entre sí", desde "por qué aislar" hasta "cómo limpiar las copias acumuladas".
Repasemos los puntos clave:
| Lo que desea hacer | Qué usar | Puntos clave |
|---|---|---|
| Entender por qué aislar | Dos premisas de Worktree | Paralelismo en el mismo repositorio sin competir por escribir en el mismo archivo (como dar copias de historial clínico) |
| Crear un hilo aislado | Modo Worktree en nuevo hilo | Elegir rama inicial; por defecto en detached HEAD, para confirmar haga clic primero en Create branch here |
| Evitar extraer ramas en dos lados | Recordar la regla estricta | Una rama solo puede estar extraída en un lugar a la vez, de lo contrario se produce el error already used by worktree |
| Mover trabajo entre primer plano y fondo | Handoff (traspaso) | Traspaso bidireccional entre Local (primer plano) y Worktree (fondo); Codex gestiona git automáticamente y los archivos en .gitignore no se trasladan |
| Equipar las nuevas copias | Script setup de Local environment | Guardado en .codex en la raíz del proyecto, se puede compartir en git e instala dependencias automáticamente al crear el worktree |
| Gestionar el espacio en disco | Reglas de limpieza + worktree permanente | Conserva los 15 más recientes por defecto, guarda captura antes de borrar; use worktree permanente para entornos a largo plazo |
Ahora debería ser capaz de:
- Explicar qué resuelve Worktree, siendo la regla de oro "trabajar en paralelo en el mismo repositorio sin competir por escribir en el mismo archivo"
- Crear un hilo de Worktree en la App de escritorio, sabiendo que por defecto está en detached HEAD y que debe hacer clic en Create branch here antes de confirmar
- Comprender la regla estricta de que "una rama no se puede extraer en dos lugares a la vez", y usar Handoff en lugar de forzar las ramas cuando ocurra
- Usar Handoff para mover hilos en ambas direcciones entre Local y Worktree, y utilizar el script setup de local environment para que el nuevo worktree esté equipado desde el inicio
- Saber cómo limpiar los worktrees acumulados y en qué casos no se eliminarán
Si recordamos el error de "abrir dos hilos Local para modificar el mismo repositorio" al principio, la causa raíz fue no usar el aislamiento y dejar que dos Codex compitieran por el mismo bolígrafo. Ahora que tiene la llave del aislamiento con Worktree y el transportador con Handoff, podrá evitar dar un gran rodeo.
El siguiente artículo 〔26 Integración con Git y GitHub〕: En este artículo ya ha visto varias acciones de Git: convertir worktree en rama, operaciones de git gestionadas silenciosamente por Codex en el Handoff, confirmar y enviar tras modificar... pero la mayoría han sido a nivel de "Codex lo hace por usted". El siguiente artículo detallará las capacidades de Git / GitHub de Codex directamente: confirmar (commit), enviar (push) y abrir PR desde la App, cómo usar el panel de diferencias para preparar (stage) o descartar cambios bloque por bloque, y cómo interactuar con GitHub. Piénselo: una vez que worktree ha aislado el trabajo, el paso final es integrarlo limpiamente de vuelta a la línea principal; ese paso es precisamente el tema central del siguiente artículo.