Qué es un worktree: varias copias de tu proyecto, cada una en su rama
Por IActn – escrita con ayuda de IA y revisada por una persona antes de publicarla. Fuentes al final.
Si abres dos sesiones de Claude Code sobre la misma carpeta, las dos editan los mismos archivos y se pisan. Un worktree resuelve eso: otra copia de trabajo del mismo proyecto, en su propia carpeta y su propia rama, para que cada sesión vaya a lo suyo. Aquí va qué es, cómo se crea, cuándo vale la pena y las trampas que nos tocaron a nosotros.
- 01Qué esQué es un worktree
- 02DecidirPara qué sirve y cuándo conviene
- 03Paso a pasoCómo crear, ver y quitar uno
- 04Qué esWorktrees en Claude Code
- 05CuidadoLas trampas que nos tocaron
- 06PromptsUn prompt para decidir si hace falta uno
- 07CuidadoLo que falta confirmar
Qué es un worktree (git worktree)
Un proyecto con git normalmente tiene una sola carpeta de trabajo, la que abres y editas. Git permite agregar más: según su documentación, un repositorio tiene un worktree principal y cero o más worktrees vinculados, y cada vinculado comparte todo con el repositorio salvo cosas propias como su HEAD (el punto donde estás parado en el historial) y su index (la lista de lo que está a punto de guardarse). (git – worktree)
Dicho sin jerga: es el mismo proyecto visto desde dos o tres carpetas a la vez, cada una con sus archivos en el estado de su propia rama. Los cambios que guardas con un commit en una copia viven en el historial compartido, por eso las demás pueden traerlos.
Piensa en una cocina con varias tablas de cortar. La despensa y el refrigerador son uno solo (el historial del proyecto), pero cada cocinero tiene su tabla y su cuchillo. Nadie corta encima de lo que está cortando otro, y todos usan los mismos ingredientes.
Para qué sirve y cuándo conviene
La documentación de git muestra el caso clásico: llega una urgencia mientras estás a mitad de otra cosa. En vez de dejar tu trabajo a medias, creas otra copia, arreglas lo urgente, guardas y la quitas. (git – worktree) Con asistentes de IA aparece un segundo caso: varias sesiones trabajando a la vez sin editar los mismos archivos. Claude Code lo describe así: cada worktree tiene sus propios archivos y su propia rama, y comparte historial y repositorio remoto con la carpeta principal. (Claude Code – worktrees)
Pero no es gratis: cada copia hay que mantenerla al día y acordarse de ella. Por eso no todo merece uno:
- Sí conviene: dos sesiones van a tocar los mismos archivos, o quieres probar un cambio que quizá tires a la basura.
- No hace falta: una sola sesión, o varias sesiones que tocan cosas distintas. Ahí la carpeta principal basta.
Nuestro ejemplo real - varias sesiones a la vez
En IActn trabajamos con varias sesiones de Claude Code al mismo tiempo, cada una con su tarea. Nuestra regla: por defecto se trabaja en la rama principal, sin copias extra.
Nuestro ejemplo real - cuándo sí usamos uno
Abrimos un worktree solo cuando dos sesiones van a tocar los mismos archivos, o cuando el cambio es de los que quizá se tiran. Si no se da ninguno de los dos casos, no lo creamos.
Cómo crear, ver y quitar un worktree
Son tres comandos de git. No hace falta aprenderlos de memoria: puedes pedirle a Claude que los corra, pero conviene saber qué hacen.
- Crear.
git worktree add ../mi-arreglohace una carpeta nueva y, por defecto, una rama nueva con el nombre de esa carpeta. Con-beliges tú el nombre de la rama. (git – worktree) - Ver cuáles hay.
git worktree listmuestra todas las copias: primero la principal y luego las vinculadas, con su rama. - Quitar.
git worktree remove ../mi-arregloborra la copia. Git solo deja quitar las «limpias»: si tiene cambios sin guardar o archivos nuevos sin registrar, se niega, y hay que forzarlo con--force. - Una rama, una copia. Git se niega a crear un worktree sobre una rama que ya está abierta en otra copia, salvo que lo fuerces. Así dos copias no pisan la misma rama.
Un detalle útil: si borras la carpeta a mano en vez de usar remove, git conserva un registro huérfano que luego se limpia con git worktree prune.
Worktrees en Claude Code
Claude Code trae su propia forma de crearlos: con claude --worktree nombre (o -w) abre una sesión en un worktree nuevo. Por defecto lo deja en .claude/worktrees/nombre/, dentro del proyecto, con una rama llamada worktree-nombre. También puedes pedirle en plena sesión «trabaja en un worktree». (Claude Code – worktrees)
Tres cosas de su documentación que conviene saber:
- De dónde parte la copia. Por defecto, desde la rama principal tal como está en el servidor remoto, no desde lo que tengas a medias en tu computadora. Hay un ajuste (
worktree.baseRef) para partir de tu estado actual. - Al salir, revisa si borrarla pierde algo. Si la copia está limpia y no le pusiste nombre, la quita sola. Si tiene trabajo, te pregunta si la conservas o la borras junto con ese trabajo.
- Protege la carpeta principal. Mientras una sesión está aislada en su worktree, Claude Code bloquea las ediciones que apuntan a la carpeta principal.
Los subagentes también pueden trabajar cada uno en su propio worktree: se pide con «usa worktrees para tus agentes» o con isolation: worktree en la definición del subagente.
Las trampas que nos tocaron
Los worktrees evitan unos problemas y traen otros. Estos son los que vivimos en IActn:
Nuestro ejemplo real - la copia que se queda atrás
Al trabajar desde un worktree, los cambios que otra sesión hizo sobre la rama principal no se veían hasta traerlos. La copia no se actualiza sola: hay que sincronizarla con la rama principal antes de seguir.
Nuestro ejemplo real - la edición en la copia equivocada
Una vez una edición fue a parar a la copia equivocada. Hoy una protección frena el intento de escribir en la carpeta principal desde un worktree.
- Antes de borrar uno, mira qué hay dentro. Nos pasó tener un worktree que, de haberse cerrado, se habría llevado trabajo sin guardar. Antes de quitar uno, confirma que todo está guardado con un commit; git y Claude Code ya se niegan o preguntan, pero conviene mirarlo también tú.
- Cada copia es otra carpeta que recordar. Si abres cuatro y se te olvidan, acabas con trabajo repartido y sin saber dónde. Por eso nuestra regla es empezar sin worktree.
Antes de editar, mira en qué carpeta y en qué rama estás. Es la pregunta que habría evitado la edición en la copia equivocada, y tarda un segundo.
Un prompt para decidir si hace falta un worktree
Es nuestro, no de Anthropic.
¿Trabajo en la carpeta principal o abro una copia?
Cuándo usarlo: antes de empezar una tarea cuando hay otras sesiones abiertas, o cuando no sabes si el cambio va a salir bien.
Lo que falta confirmar
- Las reglas de IActn son nuestras. «Rama principal por defecto, worktree solo si hay choque o cambio descartable» es lo que nos funciona a nosotros, no una norma de git ni de Anthropic.
- Los detalles de Claude Code cambian rápido. Los nombres de opciones (
--worktree,worktree.baseRef,isolation: worktree) y la limpieza al salir son de su documentación del 21-10-2026; revisa la versión que usas. - Git avisa que las copias múltiples son «experimentales» en general. Su documentación añade que el soporte de submódulos (proyectos dentro de proyectos) es incompleto y no recomienda varias copias en ese caso.
- No confirmamos el espacio en disco. Cada copia ocupa archivos propios; cuánto depende de tu proyecto y no hemos medido una cifra.
Un worktree es otra carpeta del mismo proyecto con su propia rama, para que dos sesiones no se pisen. Empieza sin él y úsalo solo cuando dos sesiones van a tocar lo mismo o el cambio puede tirarse. Si lo abres, mantenlo al día con la rama principal y antes de borrarlo confirma que no queda trabajo sin guardar.
¿Y ahora qué?
Tres formas de seguir, según lo que prefieras.
Recibe las guías nuevas en tu correo
Un correo cuando sale una guía nueva o una novedad que te sirva para tu negocio.
El mensaje para tu grupo
¿Le sirve a alguien de tu equipo o de tu grupo? Cópialo tal cual o ábrelo directo en WhatsApp.
Te paso esta guía: Qué es un worktree. Varias sesiones de Claude en el mismo proyecto, sin pisarse. https://iactn.com/arsenal/que-es-un-worktree/Fuentes, leídas el 21-10-2026
- git-worktree – documentación oficial de git. Qué es un worktree principal y uno vinculado, cómo se crea, se lista y se quita, qué pasa con copias con cambios y que una rama no se abre en dos copias a la vez.
- Run parallel sessions with worktrees – Claude Code Docs. La opción
--worktree, dónde se crea, desde qué rama parte, la limpieza al salir, el aislamiento de la carpeta principal y los subagentes con worktree. - Common workflows – Claude Code Docs. La sección de sesiones en paralelo con worktrees y que el repositorio necesita al menos un commit.