Hace unas semanas escribí sobre git worktrees — qué son, cómo crearlos, por qué son mejor que clonar el repo tres veces. Los fundamentos.
Pero los fundamentos son solo la mitad de la historia. Porque Claude Code no se limita a funcionar sobre worktrees — tiene soporte nativo para ellos. Flags dedicados, aislamiento automático, integración con tmux. Y la diferencia entre saber que los worktrees existen y saber cómo Claude Code los aprovecha es la diferencia entre tener un coche y saber que tiene modo sport.
Boris Cherny, el creador de Claude Code, publicó un hilo con cinco tips para sacarles partido. Los he probado todos. Algunos me han cambiado el workflow. Otros me han ahorrado las ñapas que llevaba haciendo desde enero. Vamos a verlos.
Tip 1: --worktree — un worktree con un solo flag
El flujo clásico para trabajar con un worktree es:
git worktree add ../mi-proyecto-feature -b feature/algo
cd ../mi-proyecto-feature
claude
Tres pasos. No es terrible, pero requiere pensar en nombres de directorios, acordarte de la sintaxis, y luego navegar al directorio nuevo. Si lo haces cinco veces al día, cansa.
Claude Code lo reduce a uno:
claude --worktree
Eso es todo. Claude crea un worktree temporal en un directorio con nombre generado, se mueve a él, y arranca una sesión ahí. Cuando terminas, el worktree se limpia solo.
¿Cuándo lo uso? Cada vez que quiero probar algo sin contaminar mi rama actual. Experimentar con una refactorización agresiva, explorar una alternativa de diseño, hacer un spike. Si sale bien, mergeo. Si no, desaparece sin dejar rastro.
Es el equivalente a abrir un borrador nuevo en tu editor de texto. Sin compromiso, sin ceremonia.
Tip 2: subagentes en worktrees aislados
Si ya usas subagentes en Claude Code (con Task dentro de un custom agent o con el propio agente principal delegando), sabes que comparten el directorio de trabajo. Eso significa que dos subagentes pueden pisarse los archivos, competir por el index de git, o dejar el staging area hecho un Cristo.
La solución: subagentes que corren cada uno en su propio worktree.
Cuando un agente lanza un subagente con aislamiento de worktree, Claude Code:
- Crea un worktree temporal para el subagente.
- El subagente trabaja ahí, en su propia rama.
- Cuando termina, los cambios se pueden mergear al worktree padre.
- El worktree temporal se limpia.
Dicho en cristiano: cada subagente tiene su propia mesa de trabajo. Pueden estar los dos serrando madera al mismo tiempo sin arrancarse los dedos mutuamente.
El beneficio no es solo evitar conflictos. Es que puedes paralelizar de verdad. Mandar a un subagente a escribir tests mientras otro implementa la feature. Uno traduciendo documentación mientras otro refactoriza el módulo de autenticación. Sin esperas, sin bloqueos.
Tip 3: custom agents con isolation: worktree
Esto es donde la cosa se pone interesante de verdad. Los custom agents en Claude Code se definen con un fichero Markdown en .claude/agents/. Y en el frontmatter de ese fichero puedes poner:
---
name: refactor-module
isolation: worktree
---
isolation: worktree le dice a Claude Code: «cada vez que invoques a este agente, dale su propio worktree automáticamente». No tienes que pasar --worktree. No tienes que crear nada manualmente. El aislamiento es parte de la definición del agente.
¿Para qué sirve esto? Para agentes que, por diseño, siempre deberían trabajar aislados. Algunos ejemplos:
Un agente de refactorización agresiva. Quieres un agente que mueva archivos, renombre funciones, cambie la estructura de directorios. Si lo haces en tu rama de trabajo, cualquier error es un desastre. Con isolation: worktree, el agente hace los cambios en su propia copia. Revisas el diff. Si te convence, mergeas. Si no, git worktree remove y como si no hubiera pasado.
Un agente de traducción. Lo uso literalmente para este blog. Un agente que traduce posts a cuatro idiomas, genera frontmatter, y commitea. Necesita tocar muchos archivos a la vez. Si trabaja en mi directorio de desarrollo, me bloquea. Con su propio worktree, traduce mientras yo sigo escribiendo el siguiente post.
Un agente de migración de base de datos. Genera archivos SQL, los valida contra el schema actual, corre tests. Todo en un worktree aislado donde puede romper cosas sin consecuencias.
La clave es que isolation: worktree convierte el aislamiento en un atributo del agente, no en una decisión que tomas cada vez que lo lanzas. Es la diferencia entre un coche que tiene airbags y un coche donde tienes que acordarte de activar la seguridad cada vez que arrancas.
Tip 4: --tmux — sesiones paralelas de verdad
Hasta ahora, «paralelo» significaba abrir varias terminales manualmente. Terminal 1 para un worktree, terminal 2 para otro, terminal 3 para el principal. Funciona, pero es artesanal.
--tmux automatiza esto:
claude --worktree --tmux
Claude Code crea el worktree, arranca la sesión en un panel de tmux, y te devuelve el control de tu terminal. Puedes lanzar tres, cuatro, cinco sesiones así:
claude --worktree --tmux # sesión 1: implementar feature A
claude --worktree --tmux # sesión 2: escribir tests para módulo B
claude --worktree --tmux # sesión 3: refactorizar el CLI
Cada una en su worktree, cada una en su panel de tmux, todas corriendo en paralelo. Cambias entre ellas con Ctrl-b + número de ventana (o tu atajo de tmux favorito).
Esto es game changer para sprints de productividad. Imagina un lunes por la mañana: abres tu backlog, seleccionas tres tareas independientes, y lanzas tres agentes. Mientras uno escribe tests, otro implementa una feature, y el tercero actualiza la documentación. Tú supervisas, revisas diffs cuando van terminando, y mergeas.
No es ciencia ficción. Es un flag.
Tip 5: cuándo NO usar worktrees
Tan importante como saber cuándo usar worktrees es saber cuándo no hacerlo. Boris Cherny lo dice explícitamente, y estoy de acuerdo.
No uses worktrees para tareas secuenciales. Si la tarea B depende del resultado de la tarea A, no ganas nada con paralelizar. De hecho, pierdes: ahora tienes que mergear A antes de que B pueda empezar, lo cual añade un paso que no existía si simplemente hubieras trabajado en la misma rama.
No uses worktrees para cambios pequeños. Un fix de una línea no justifica la ceremonia de crear un worktree, aunque --worktree la reduzca a un flag. El overhead mental de tener múltiples directorios activos no compensa si el cambio se hace en treinta segundos.
No uses worktrees si los cambios tocan los mismos archivos. Si la feature A y la feature B van a modificar ambas el mismo config.toml o el mismo routes.py, te comes un conflicto al mergear seguro. Los worktrees brillan cuando las features son ortogonales — tocan zonas distintas del código.
No uses worktrees sin un plan. Lanzar cinco agentes en paralelo «a ver qué sale» suena productivo. En la práctica, acabas con cinco ramas que no sabes en qué estado están, cinco diffs que revisar, y cinco merges potencialmente conflictivos. La paralelización funciona cuando hay intención detrás: tareas claras, independientes, y con criterio de aceptación definido.
La regla de oro: si puedes describir cada tarea en una frase y ninguna depende de otra, usa worktrees. Si no, trabaja en serie.
El workflow completo: de la teoría a tu lunes por la mañana
Para que no quede en abstracto, este es el flujo que uso ahora cuando tengo varias tareas independientes en el backlog:
# 1. Reviso el backlog y elijo tareas independientes
linear issue list --team PROD --state unstarted --sort priority --no-pager
# 2. Lanzo un agente por tarea, cada uno en su worktree + tmux
claude --worktree --tmux # "implementa la feature X, crea tests"
claude --worktree --tmux # "refactoriza el módulo Y"
claude --worktree --tmux # "traduce los posts pendientes"
# 3. Voy revisando conforme terminan (tmux panels)
# Ctrl-b + 1, 2, 3 para cambiar entre sesiones
# 4. Reviso el diff de cada worktree
cd /tmp/claude-worktree-abc123 # o donde Claude lo haya creado
git diff main
# 5. Si el diff mola, push + PR
git push -u origin feature/lo-que-sea
# PR, review, merge
# 6. Limpieza (o dejar que Claude la haga automáticamente)
git worktree list # ver qué queda vivo
Lo que antes me costaba una mañana entera — tres features desarrolladas, testeadas y con PR — ahora se puede hacer antes de irse de cañas.
La evolución: de manual a nativo
Cuando empecé con worktrees hace unas semanas, todo era manual. git worktree add, cd, claude, abrir otra terminal, repetir. Funcionaba, pero se sentía como montar una tienda de campaña cada vez que quieres salir al jardín.
Con --worktree, isolation: worktree, y --tmux, Claude Code ha convertido los worktrees en algo que desaparece. No piensas en ellos. No los gestionas. Simplemente dices «curra en paralelo» y el tooling se encarga del resto.
Es la misma evolución que vimos con los contenedores: primero configurabas LXC a mano, luego Docker lo abstrajo, y ahora ni piensas en los namespaces del kernel. Los worktrees están en esa fase de abstracción. Git puso los cimientos en 2015. Once años después, el tooling finalmente los hace invisibles.
Y eso, al final, es lo que queremos de cualquier herramienta: que haga su trabajo y se quite de en medio.
TL;DR: Claude Code tiene cinco features clave para worktrees: --worktree (crear y entrar con un flag), subagentes aislados (cada uno en su worktree), isolation: worktree en custom agents (aislamiento por diseño), --tmux (sesiones paralelas automatizadas), y saber cuándo no usarlos. El resultado: paralelismo real sin gestión manual. Los worktrees pasan de ser una feature de git que nadie usa a ser la infraestructura invisible de tu workflow con agentes.
Read this article in English.
