Worktree en Claude Code: por qué no tiene tus últimos commits

worktree.baseRef decide si un worktree de Claude Code lleva tus commits sin subir. Por defecto parte de origin/main y los deja fuera, también en tus subagentes.

Worktree en Claude Code: con baseRef "fresh" el worktree parte de origin/main y tu commit sin subir no está; con baseRef "head" parte de tu HEAD local y lo trae, activado con worktree.baseRef en .claude/settings.json

TL;DR Si tus worktrees o tus subagentes tienen que trabajar sobre lo que aún no has subido, pon "worktree": { "baseRef": "head" } en .claude/settings.json. Si quieres que cada worktree empiece limpio desde main, no toques nada: ese es el valor por defecto.

claude --worktree no parte de la rama en la que estás. Parte de la rama por defecto del remoto, normalmente origin/main. Así que si llevas tres commits sin subir en tu rama de feature y abres un worktree para que Claude siga desde ahí, esos tres commits no están. Lo decide un ajuste, worktree.baseRef, con dos valores: fresh (el de por defecto) y head.

Lo probé en un repo con un commit subido y otro sin subir:

$ git log --oneline
31ef515 unpushed: my local work
a785234 pushed: initial

# baseRef "fresh" (por defecto)
$ claude -w fresh-test -p "git log --oneline"
a785234 pushed: initial

# baseRef "head"
$ claude -w head-test -p "git log --oneline"
31ef515 unpushed: my local work
a785234 pushed: initial

Mismo repo, mismo comando. Con fresh, el worktree arranca en a785234 y tu commit se queda fuera. Con head, arranca en 31ef515 y lo tiene.

Dónde te muerde

No solo en claude -w. El mismo ajuste decide desde dónde parten:

claude --worktree desde la terminal.
El tool EnterWorktree, cuando le pides a Claude en mitad de una sesión que "trabaje en un worktree".
Los subagentes con isolation: worktree. Este es el caso caro: le encargas a un subagente que termine algo que tienes a medias y lo hace sobre main, sin tu código.

Cómo cambiarlo

1. Añade el ajuste

En .claude/settings.json si lo quieres para todo el equipo, o en .claude/settings.local.json solo para ti:

{
  "worktree": {
    "baseRef": "head"
  }
}

2. Abre un worktree y compruébalo

claude -w prueba

Pídele git log --oneline -3 y mira si sale tu último commit.

Cuál elegir

Valor	Parte de	Úsalo cuando
`fresh`	La rama por defecto del remoto (`origin/HEAD`)	Cada worktree es una tarea nueva e independiente
`head`	Tu `HEAD` local, con los commits sin subir	El worktree o el subagente tiene que seguir tu trabajo a medias

No acepta un nombre de rama. Para arrancar desde una rama concreta, crea el worktree con git worktree add y abre Claude dentro.

Tres detalles de fresh que conviene saber:

Actualiza origin/HEAD solo. Si el repo lleva más de 24 horas sin un fetch, hace uno de cinco segundos como mucho antes de crear el worktree. Si falla (sin red, o git pide una contraseña), usa la copia local.
Sin remoto, cae a head. Si no hay remoto o no puede conseguir origin/HEAD, parte de tu HEAD local.
Reabre limpio. Si vuelves a usar un nombre de worktree que no tiene cambios ni commits propios, o cuyo PR ya se fusionó, lo resetea a la rama por defecto en vez de dejarlo donde estaba. Con head no lo hace.

Y en ninguno de los dos casos viajan los cambios sin commitear: un worktree es un checkout de un commit. Si los necesitas allí, haz commit antes. Los archivos ignorados como el .env son otra historia, la de .worktreeinclude.

Si los worktrees son nuevos para ti, empieza por poner varios Claude a trabajar a la vez. Y para revisar un PR, claude --worktree "#123" ya descarga la rama del PR, sin importar este ajuste.

Documentación oficial: Choose the base branch

Requisitos

Una versión de Claude Code de mayo de 2026 o posterior: el ajuste llegó entre la v2.1.128 y la v2.1.136. Probado en v2.1.293.