Nethür
Iniciar sesión
macOS próximamente

Blog · 5 de noviembre de 2026

Los worktrees de Claude Code, explicados

Una guía en lenguaje claro sobre los git worktrees en Claude Code: qué aíslan, dónde se ubican y cómo crearlos, revisarlos y eliminarlos sin perder trabajo.

Diagrama de una rama main que se divide en tres worktrees de Nethür, uno por tarea

Un worktree de Claude Code es un git worktree normal dentro del cual ejecutas Claude Code. Git hace un segundo checkout del repositorio en otro branch, Claude Code usa ese directorio como árbol de trabajo y tu checkout principal queda intacto. La ubicación es la ruta que pases a `git worktree add` o el directorio gestionado de la herramienta que lo cree por ti.

«Worktree de Claude Code» suena a una función que se activa. Casi siempre es más sencillo: un worktree es un directorio que crea git, y Claude Code es un proceso que edita archivos en el directorio donde lo inicias. Junta esos dos hechos y tendrás sesiones de agentes aisladas.

La distinción importa porque internet mezcla tres cosas distintas: los git worktrees, las funciones de worktree dentro de las propias apps de Claude Code y las herramientas de espacio de trabajo que crean worktrees por ti. Comparten nombre y propósito, pero la ubicación, la limpieza y la revisión cambian según quién creó el directorio.

Qué es realmente un git worktree

Un clon normal tiene un árbol de trabajo: los archivos que ves en el editor. Un git worktree permite que el mismo repositorio tenga varios árboles de trabajo a la vez, cada uno en un branch distinto. La base de objetos y los remotos se comparten; los archivos del checkout y el índice, no.

git worktree list
# /Users/you/app             abc1234 [main]
# /Users/you/app-fix-login   def5678 [fix/login]
  • Cada worktree tiene su propio branch, HEAD, índice y archivos en disco.
  • No puedes hacer checkout del mismo branch en dos worktrees a la vez.
  • Eliminar un worktree borra el directorio y su checkout, no el historial del branch.
  • Todos los worktrees siguen siendo el mismo repositorio, así que los commits, fetch y push ven los mismos objetos.

Este es exactamente el aislamiento que necesita un agente. Claude Code puede leer, editar, ejecutar tests y hacer commit en su worktree sin tocar el checkout que tienes abierto. Si el agente rompe algo, borras el directorio y conservas tu branch principal.

Por qué Claude Code se beneficia de un worktree

Una sesión de agente no es un chat que toca archivos de casualidad. Ejecuta comandos, arranca servidores de desarrollo, escribe archivos generados, prepara cambios y a veces cambia de branch. Dos sesiones en un mismo checkout comparten todo ese estado. El fallo rara vez es dramático: un test pasa contra el código equivocado, un formateador reescribe el trabajo del otro agente o un commit incluye archivos de ambas tareas.

Un worktree convierte esos fallos de estado compartido en directorios separados. El coste es que cada worktree nuevo empieza limpio: sin node_modules, sin .env, sin base de datos local. El resto de esta guía trata, sobre todo, de asumir ese coste a propósito.

¿Claude Code tiene un modo worktree?

El CLI de Claude Code no necesita un modo especial para trabajar en un worktree. El límite de su sesión es el directorio de trabajo. Inicia claude dentro de ../app-fix-login y la sesión lee y escribe ahí; inicia otra dentro de ../app-fix-billing y tendrá otro branch y otro conjunto de archivos.

Otras superficies de Claude Code gestionan los worktrees por ti. La app de escritorio puede ejecutar sesiones en paralelo en git worktrees aislados, y los equipos de agentes o subagentes pueden delegar trabajo dentro de una sesión. Son capas de comodidad: crean un checkout, meten al agente dentro y ocultan la ruta. Si necesitas una ubicación predecible, crea el worktree tú mismo y lanza Claude Code dentro de él.

¿Dónde debería vivir un worktree de Claude Code?

La ubicación depende de quién cree el worktree. En una configuración manual, pasa una ruta a git worktree add. Dos convenciones funcionan bien: un directorio hermano junto al checkout principal o una carpeta worktrees/ dedicada fuera del repositorio.

# sibling next to the main checkout
git worktree add ../app-fix-login -b fix/login origin/main

# or a dedicated root outside the repo
git worktree add ~/worktrees/app/fix-login -b fix/login origin/main

Mantén los worktrees fuera del checkout principal. Un worktree dentro del repositorio aparece en todas las búsquedas, confunde la indexación del editor y puede acabar en un commit por accidente. Si una herramienta crea worktrees en una carpeta oculta dentro del repo, comprueba que esa carpeta esté en el gitignore antes de fiarte de ella.

Nethür crea los worktrees en su propio directorio gestionado y registra la ruta por ti. Si ya tienes worktrees creados por Claude Code, GSD o un simple git worktree add, Nethür puede mostrarlos como worktrees externos en lugar de pedirte que los muevas. Ajustes → General → Workspace controla qué fuentes externas son visibles y qué raíces de ubicación se escanean.

Si prefieres no gestionar las rutas a mano, una interfaz gráfica de git worktree como Nethür puede crear, seguir y limpiar worktrees por ti, sin dejar de mantener un checkout normal en disco.

Crea un worktree y arranca Claude Code

Parte de una referencia base actualizada para que el agente no trabaje contra el código de la semana pasada.

git fetch origin
git worktree add ../app-fix-login -b fix/login origin/main
cd ../app-fix-login
claude

Usa un nombre de branch único por worktree. Si quieres un segundo agente en la misma tarea, crea un segundo worktree con otro branch, aunque el prompt sea idéntico. El branch es lo que hace que los dos resultados se puedan comparar y fusionar de forma independiente.

En Nethür, ese mismo paso es un diálogo: crea un worktree, ponle nombre a la tarea, elige la referencia de partida y selecciona el agente. Nethür ejecuta git fetch y git worktree add en segundo plano, muestra el espacio de trabajo mientras se crea y abre el agente en el nuevo checkout. La documentación de worktrees cubre el selector de referencia de partida, los espacios de carpeta y los issues vinculados.

Dependencias, archivos env y puertos

Un worktree recién creado es un checkout limpio, lo que significa que le falta todo lo que git ignora. Hay tres formas de manejarlo, y la mayoría de los equipos acaba usando las tres.

  • Instalar por worktree. Es correcto y sencillo, pero lento y consume disco cuando cada agente necesita su propio node_modules.
  • Compartir los directorios pesados y reconstruibles. Las rutas compartidas de worktree de Nethür materializan los directorios ignorados por git desde el checkout principal, con worktree.sharedDirectories en nethur.yaml para definirlos a nivel de repositorio.
  • Copiar los archivos pequeños y propios del worktree. .worktreeinclude enumera los archivos y directorios ignorados por git que hay que copiar, como .env o ajustes locales del editor, para que cada worktree tenga su propia copia.
# nethur.yaml at the repo root
worktree:
  sharedDirectories:
    - node_modules
    - .cache

# .worktreeinclude at the repo root
.env
.env.local
.vscode/settings.json

Los puertos merecen su propia regla. Si dos agentes arrancan el mismo servidor de desarrollo, el segundo falla o, peor, se conecta a la base de datos del primero. Pon el puerto y el nombre de la base de datos en un archivo de entorno por worktree, o haz que el hook de configuración los derive del nombre del worktree.

Revisa el diff y luego elimina el worktree

Revisa cada worktree contra la referencia desde la que partió, no contra lo que haya ahora en main. Así el diff se centra en el trabajo del agente. Nethür muestra el diff por espacio de trabajo, admite anotaciones en línea y puede enviar notas de revisión al agente antes de que hagas commit.

Cuando el trabajo esté fusionado, elimina el worktree y el branch. No borres el directorio a mano: git guarda metadatos en .git/worktrees, y un rm -rf manual deja una entrada obsoleta.

git worktree remove ../app-fix-login
git branch -d fix/login

# if git refuses because the branch has unmerged commits
git worktree remove --force ../app-fix-login

Git puede conservar un branch local con commits sin fusionar incluso después de que el worktree desaparezca. Es una red de seguridad, no un bug. Nethür muestra los branches conservados en un paso de revisión para que decidas cuáles forzar y borrar en lugar de perseguirlos más tarde.

Errores habituales con los worktrees

  • Hacer checkout del mismo branch en dos worktrees. Git se niega; elige otro branch para el segundo agente.
  • Poner el worktree dentro del repositorio. Las búsquedas y los editores ven archivos duplicados, y el directorio puede acabar en un commit.
  • Compartir un único .env que apunta a la base de datos principal. Cada agente debería tener su propia base de datos o esquema cuando hay migraciones de por medio.
  • Olvidar la referencia base. Un worktree creado desde un branch local desactualizado produce un diff confuso y un merge doloroso.
  • Dejar decenas de worktrees abiertos después del experimento. Limpia los branches mientras aún recuerdes cuál ganó.

Worktrees en equipo

En un servidor de equipo, los worktrees dejan de ser directorios privados. Son estado compartido del proyecto: un compañero puede ver que existe un worktree, quién lo creó, qué agente se está ejecutando y si está bloqueado. Esa visibilidad es lo que hace seguro pasar el trabajo a otra persona.

Nethür mantiene el mismo modelo de worktrees tanto si se ejecuta en tu portátil, en la máquina de un compañero, en un VPS o en un destino SSH. El agente se ejecuta donde vive el checkout y el cliente solo representa la sesión. Si quieres la versión de equipo de esta configuración, lee Claude Code para equipos.

Pruébalo con una tarea

Crea un worktree para un cambio pequeño, lanza Claude Code dentro y deja tu checkout principal abierto al lado. Cuando veas que las dos sesiones dejan de interferir, el directorio extra dejará de parecer una carga. La guía de agentes en paralelo muestra cómo escalarlo a varios agentes y comparar sus resultados.

Pon la guía en práctica.

Descarga Nethür y ejecuta tu primer agente en paralelo en minutos, o monta un espacio de trabajo de equipo en una máquina que ya tengas.