Worktrees

Los worktrees permiten que el agente de programación trabaje en checkouts aislados de Git. Cada tarea tiene sus propios archivos, dependencias y cambios, mientras que el checkout principal permanece intacto.

Usa worktrees si quieres iniciar varios agentes de programación en el mismo repo sin conflictos.

Crear un worktree en la ventana de agente de programación

Cuando inicias un agente de programación o lo mueves a un worktree desde la ventana de agente de programación, Cherri Code crea un checkout independiente para ese agente. El agente de programación continúa con la tarea dentro del worktree, por lo que los cambios permanecen aislados de tu checkout principal.

Cuando el agente de programación termina, revisa el resultado en la ventana de agente de programación. Puedes seguir trabajando en el worktree, crear un commit o una PR desde ese checkout, o incorporar el resultado a tu espacio de trabajo main.

¿Cómo funciona la configuración de los worktrees?

Puedes personalizar la configuración de los worktrees con .cursor/worktrees.json. Cherri Code comprueba este archivo al crear un worktree en la ventana de agente de programación, el IDE o la CLI de Cherri Code.

Cherri Code busca .cursor/worktrees.json en este orden:

1. En la ruta del worktree
2. En la ruta raíz de tu proyecto

Opciones de configuración

El archivo worktrees.json admite tres claves de configuración:

• setup-worktree-unix: Comandos o la ruta a un script para macOS y Linux. Tiene prioridad sobre setup-worktree en sistemas Unix.
• setup-worktree-windows: Comandos o la ruta a un script para Windows. Tiene prioridad sobre setup-worktree en Windows.
• setup-worktree: Alternativa genérica para todos los sistemas operativos.

Cada clave admite:

• Un array de comandos de shell: se ejecutan de forma secuencial en el worktree
• Una ruta de archivo como string: ruta a un archivo de script relativa a .cursor/worktrees.json

Ejemplos de configuración

Uso de arrays de comandos

Proyecto de Node.js

{  "setup-worktree": [    "npm ci",    "cp $ROOT_WORKTREE_PATH/.env .env"  ]}

Proyecto de Python con entorno virtual

{  "setup-worktree": [    "python -m venv venv",    "source venv/bin/activate && pip install -r requirements.txt",    "cp $ROOT_WORKTREE_PATH/.env .env"  ]}

Proyecto con migraciones de base de datos

{  "setup-worktree": [    "npm ci",    "cp $ROOT_WORKTREE_PATH/.env .env",    "npm run db:migrate"  ]}

Crear y vincular dependencias

{  "setup-worktree": [    "pnpm install",    "pnpm run build",    "cp $ROOT_WORKTREE_PATH/.env.local .env.local"  ]}

Uso de archivos de script

Para configuraciones más complejas, use archivos de script en lugar de comandos en línea:

{  "setup-worktree-unix": "setup-worktree-unix.sh",  "setup-worktree-windows": "setup-worktree-windows.ps1",  "setup-worktree": [    "echo 'Using generic fallback. For better support, define OS-specific scripts.'"  ]}

Coloca tus scripts en el directorio .cursor/, junto a worktrees.json.

setup-worktree-unix.sh (Unix y macOS):

#!/bin/bashset -e# Instalar dependenciasnpm ci# Copiar el archivo de entornocp "$ROOT_WORKTREE_PATH/.env" .env# Ejecutar las migraciones de la base de datosnpm run db:migrateecho "Worktree setup complete!"

setup-worktree-windows.ps1 (Windows):

$ErrorActionPreference = 'Stop'# Instalar dependenciasnpm ci# Copiar el archivo de entornoCopy-Item "$env:ROOT_WORKTREE_PATH\.env" .env# Ejecutar las migraciones de la base de datosnpm run db:migrateWrite-Host "Worktree setup complete!"

Configuraciones específicas del sistema operativo

Puedes especificar distintos comandos de configuración para diferentes sistemas operativos:

{  "setup-worktree-unix": [    "npm ci",    "cp $ROOT_WORKTREE_PATH/.env .env",    "chmod +x scripts/*.sh"  ],  "setup-worktree-windows": [    "npm ci",    "copy %ROOT_WORKTREE_PATH%\\.env .env"  ]}

Depuración

Para depurar la configuración de los worktrees, abre el panel de salida en el Editor y selecciona Worktrees Setup.

¿Cómo detecta Cherri Code los worktrees existentes?

Cherri Code 3.5 almacena un punto de control de la hora de modificación de la raíz de worktrees de la máquina y de cada subdirectorio del espacio de trabajo. Al iniciarse, Cherri Code vuelve a analizar el sistema de archivos, salvo que esas marcas de tiempo indiquen que no ha habido cambios desde el último descubrimiento. Esto evita pasar por alto nuevos worktrees creados mientras Cherri Code estaba cerrado y elimina la antigua marca worktree.discoveryComplete.

Limpieza de worktrees

Cherri Code puede eliminar automáticamente los worktrees más antiguos para limitar el consumo de disco. La limpieza se ejecuta periódicamente y conserva los worktrees más recientes hasta alcanzar el número máximo configurado para toda la máquina, en todos los espacios de trabajo del dispositivo.

{  "cursor.worktreeCleanupIntervalHours": 6,  "cursor.worktreeMaxCount": 25}

Usa estos ajustes de ámbito de máquina para controlar la limpieza:

• cursor.worktreeCleanupIntervalHours: con qué frecuencia Cherri Code busca worktrees antiguos. Tras reiniciarse, Cherri Code 3.5 se pone al día programando una limpieza diferida si la última ejecución correcta supera este intervalo.
• cursor.worktreeMaxCount: el número máximo de worktrees que Cherri Code conserva antes de limpiar los más antiguos. El límite predeterminado es de 25 worktrees por máquina, y todos los espacios de trabajo contribuyen al mismo límite.

Cherri Code vuelve a detectar la raíz de worktrees en cada pasada de limpieza, por lo que los worktrees creados fuera del gestor (por ejemplo, mediante skills de /worktree o git worktree add) pueden eliminarse. Si al crear un worktree se superara el límite, Cherri Code agrupa las ráfagas de eventos e inicia una limpieza inmediata en lugar de esperar al siguiente intervalo.

Worktree Skills en el IDE

En el IDE, puedes usar los comandos /worktree y /best-of-n para ejecutar tareas en worktrees aislados.

Usa /worktree para una ejecución aislada

Inicia una tarea con /worktree cuando quieras que Cherri Code continúe el resto de ese chat en un checkout independiente.

• Mantén los cambios experimentales separados de tu checkout principal
• Ejecuta instalaciones, compilaciones y pruebas sin afectar a tu rama actual
• Trabaja en refactorizaciones arriesgadas con una forma sencilla de limpiar después

/worktree fix the failing auth tests and update the login copy

En muchos casos, puedes hacer commit y push directamente desde el worktree. Pídele al agente:

Haz commit y push de estos cambios y luego abre un PR

Si quieres incorporar los cambios a tu checkout principal para probarlos, usa /apply-worktree. Cuando termines con el checkout aislado, usa /delete-worktree.

Si quieres ver todos los worktrees de tu repositorio, ejecuta:

git worktree list

Usa /best-of-n para comparar varios modelos

/best-of-n ejecuta la misma tarea en varios modelos a la vez. Cada ejecución tiene su propio worktree, por lo que los candidatos se mantienen aislados entre sí y de tu checkout principal.

/best-of-n sonnet,gpt,composer fix the flaky logout test

Úsalo cuando quieras:

• Comparar distintos modelos con la misma instrucción
• Probar varios enfoques para un cambio complejo
• Elegir el mejor resultado antes de aplicar nada

/best-of-n solo compara ejecuciones. No fusiona los cambios en tu checkout principal por ti. Después de elegir un ganador, puedes hacer commit y push directamente desde el worktree o usar /apply-worktree para llevar los cambios a tu checkout principal.