Worktrees

Los worktrees te permiten ejecutar varios agentes en el mismo proyecto sin que se pisen entre sí. Cada uno recibe su propio checkout del repositorio, en su propia rama, con sus propios panes y sesiones de agente, mientras el repositorio, los worktrees y los comandos se quedan en tu máquina.

Paneflow crea y elimina estos worktrees por ti. Antes de eliminar uno, guarda el trabajo sin commit en un snapshot que puedes restaurar después.

Qué es un worktree

Los worktrees solo existen para proyectos que viven en un repositorio Git, porque Paneflow usa worktrees de Git por debajo. Un worktree es una segunda copia ("checkout") de tu repositorio. Tiene su propia copia de cada archivo, pero comparte los mismos metadatos (la carpeta .git) sobre commits, ramas y remotos. Eso es lo que permite hacer checkout y trabajar en varias ramas a la vez.

Terminología

• Checkout del proyecto: el repositorio que abriste como espacio de trabajo, al que apunta tu carpeta de proyecto.
• Worktree gestionado: un worktree Git que Paneflow creó desde ese checkout y que limpia por ti.
• Snapshot: un commit que Paneflow hace con los cambios sin commit de un worktree justo antes de eliminarlo, para que no se pierda nada.

Por qué usar un worktree

• Deja que un agente trabaje en una funcionalidad mientras otro arregla un bug, cada uno en su rama, sin tocar el checkout del proyecto.
• Mantén una tarea larga en segundo plano mientras te concentras en el primer plano.
• Lee el resultado después en Review, junto a otros worktrees, sin hacer checkout de nada.

Primeros pasos

Los worktrees requieren un repositorio Git. Asegúrate de que el proyecto que abriste vive en uno.

Abrir un pane en una rama nueva

1. Añade un pane. La paleta "New pane" se abre con una fila de rama encima de la lista de agentes.
2. Abre la fila de rama y elige New branch….
3. Escribe un nombre de rama, o déjalo vacío para empezar en detached.
4. Elige en from la rama o el commit de partida. Por defecto es la rama en la que está tu proyecto.
5. Deja activado el interruptor Worktree.
6. Elige con qué abrir: un terminal, Claude Code, Codex, OpenCode o cualquier lanzador que hayas configurado.

Paneflow crea la rama y su worktree desde la base elegida, vincula la pestaña a ese worktree y abre el pane ahí. La pestaña muestra el nombre de la rama y el agente arranca dentro del directorio del worktree.

El mismo flujo existe en otros tres sitios:

• El Launch Pad tiene un campo "New branch" y el mismo selector "From".
• El menú contextual de la pestaña ofrece New branch… para una pestaña que ya existe.
• paneflow up y los flows aceptan los campos worktree y from; consulta Scripting.

Reutilizar una rama que ya existe

Elige una rama existente en la fila de rama, o escribe su nombre en "New branch…". Si la rama ya tiene checkout en un worktree, Paneflow reutiliza ese worktree. Si no tiene checkout en ningún sitio, Paneflow le crea un worktree. La base "from" se ignora en ese caso, porque la rama ya tiene su propio historial.

Git solo permite hacer checkout de una rama en un sitio a la vez. Paneflow nunca lucha contra esa regla: reutiliza el checkout existente en lugar de fallar con 'feature/a' is already used by worktree at ….

Empezar en detached y nombrar la rama después

Deja el nombre de rama vacío y Paneflow crea un worktree detached en la base elegida, llamado <base>-<sha> según el commit de partida. Es la opción correcta cuando aún no sabes si el trabajo merece una rama.

Cuando la merezca, haz clic derecho en la pestaña y elige Create branch here…. Paneflow ejecuta git switch -c dentro de ese worktree, así que tus cambios sin commit se quedan exactamente donde están.

Cambiar el checkout del proyecto en su lugar

Desactiva el interruptor Worktree en el formulario "New branch…" y Paneflow cambia tu checkout del proyecto a la rama, en el sitio, como haría git switch -c, en lugar de crear un worktree. El pane se abre en la raíz del repositorio y no se añade nada a la lista de gestionados.

Úsalo cuando trabajes solo en el repositorio y quieras una rama sin una segunda carpeta. Paneflow recuerda tu última elección en worktrees.for_new_branches, así que el interruptor se abre como lo dejaste.

Cambiar un checkout mueve los archivos bajo todos los panes que lo usan, así que Paneflow rechaza el cambio mientras un agente trabaje en ese checkout. Un worktree existe exactamente para ese caso.

Dónde viven los worktrees

Paneflow crea los worktrees gestionados bajo ~/.paneflow/worktrees (%USERPROFILE%\.paneflow\worktrees en Windows), un subdirectorio por repositorio y un directorio por rama:

~/.paneflow/worktrees/
  paneflow-05926cc4/
    feat-agents-browser/
    fix-login/

No se escribe nada dentro del propio checkout. La marca que le dice a Paneflow que un worktree es suyo vive en los metadatos Git del worktree, así que git status se mantiene limpio y la marca desaparece con el worktree.

Cambia la raíz en Settings > Worktrees, o define worktrees.dir en paneflow.json. La nueva raíz se aplica a los worktrees creados a partir de entonces; los creados bajo una raíz anterior siguen funcionando donde están y siguen listados.

Copiar archivos locales ignorados a los worktrees nuevos

Un worktree nuevo parte de un checkout Git, así que los archivos rastreados ya están. Los que Git ignora no, y un worktree suele necesitar unos cuantos para funcionar: .env, .env.local, un archivo local de secretos.

Añade un archivo .worktreeinclude en la raíz del repositorio y lista las rutas ignoradas a copiar, una por línea, relativas a la raíz. Los directorios también valen, con o sin / final, y # empieza un comentario.

# .worktreeinclude
.env
.env.local
config/secrets.json

Sin el archivo, Paneflow copia los .env* de primer nivel y AGENTS.override.md si existen. Un archivo que ya existe en el worktree nunca se sobrescribe. No listes archivos rastreados; Git ya los trae.

Limpieza

Los worktrees ocupan espacio: cada uno lleva sus propios archivos, dependencias y cachés de build. Paneflow mantiene su número razonable por sí solo.

Por defecto Paneflow conserva tus 15 worktrees gestionados más recientes. Cambia el límite o desactiva la eliminación automática en Settings > Worktrees, o con worktrees.keep_limit y worktrees.auto_remove en paneflow.json.

Un worktree gestionado se elimina automáticamente cuando:

• cierras el espacio de trabajo al que pertenece;
• Paneflow necesita recortar los más antiguos para no superar el límite de conservación.

Un worktree gestionado nunca se elimina automáticamente mientras una pestaña de un espacio de trabajo abierto lo use. La rama tampoco se borra nunca: eliminar un worktree solo elimina el checkout, tus commits siguen en la rama.

También puedes eliminar un worktree a mano desde Settings > Worktrees o desde el menú contextual de la pestaña. Paneflow solo elimina worktrees que creó él; los que hiciste tú con git worktree add se dejan en paz.

Snapshots

Antes de eliminar un worktree gestionado, automáticamente o a mano, Paneflow guarda su trabajo sin commit en un snapshot: ediciones de archivos rastreados, archivos nuevos y la rama en la que estaba el worktree. Un worktree limpio no deja snapshot.

Los snapshots son commits Git normales guardados bajo refs/paneflow/snapshots/ en tu repositorio. No tocan tus ramas, nunca se envían al remoto, y puedes inspeccionarlos con git log refs/paneflow/snapshots/<nombre> si quieres.

Settings > Worktrees los lista bajo "Snapshots":

• Restore recrea el worktree en su ruta original, en la misma rama, con los cambios guardados de vuelta como trabajo sin commit, y vuelve a copiar tus archivos de .worktreeinclude.
• Delete descarta el snapshot definitivamente.

Eliminar un worktree cuyos cambios ya no quieres es, a propósito, una operación en dos pasos: eliminar y luego borrar el snapshot.

Worktrees y Review

Review lee los worktrees sin hacer checkout de nada. Arrastra una rama o un worktree al borde de un pane para leer su diff contra la base que elijas, hasta seis en paralelo. Eliminar un worktree lo quita también de Review.

Preguntas frecuentes

¿Puedo controlar dónde se crean los worktrees?

Sí. Define la raíz en Settings > Worktrees o con worktrees.dir. ~ se expande a tu directorio personal, y PANEFLOW_HOME mueve toda la carpeta ~/.paneflow, worktrees incluidos.

¿Qué pasa con mi trabajo cuando se elimina un worktree?

Tus commits siguen en la rama. Los cambios sin commit van a un snapshot que puedes restaurar desde Settings > Worktrees. Vuelve a elegir la rama en la paleta "New pane" para obtener un worktree nuevo desde su estado commiteado.

¿Puedo mover trabajo entre un worktree y el checkout de mi proyecto?

Haz commit o stash en el worktree y luego cambia el checkout del proyecto a la rama, desde el formulario "New branch…" con el interruptor Worktree desactivado o con git switch. Git se negará mientras la rama siga con checkout en el worktree, así que elimina antes ese worktree desde Settings > Worktrees.

¿Paneflow toca los worktrees que creé yo mismo?

No. Paneflow los lista en la fila de rama y abre panes en ellos, pero nunca elimina un worktree que no creó.

Ver también

• Referencia de configuración: cada clave worktrees.*.
• Review: leer diffs de worktrees en paralelo.
• Scripting: worktree y from en paneflow up.
• Ajustes: la página Worktrees.