Git Worktrees for ZCode

Cada hilo obtiene su propio worktree — automáticamente. Git Worktrees le da a cada nuevo hilo de ZCode un checkout aislado de tu repositorio, para que las tareas se ejecuten en paralelo sin stashing, sin malabares con ramas, ni sobrescribirse entre sí. Empieza a chatear; ya estás aislado.

/worktree:new fix-auth "Refactor the login flow"   ← worktree + background agent
/worktree                                          ← dashboard: branches, sizes, agents
/worktree:end fix-auth                             ← commit everything, remove cleanly

Por qué lo querrás

• Cero configuración. El modo de sesión automática (activado por defecto) entrega a cada nuevo hilo su propio worktree en el momento en que comienza — y reanudar un hilo devuelve al mismo. No se necesitan comandos, nunca.

• Nunca pierdas trabajo. La eliminación de worktrees sucios, agentes en ejecución o ramas sin fusionar se rechaza sin force — e incluso entonces, los cambios no confirmados se capturan primero (diff rastreado + archivos no rastreados) en un directorio restaurable. Las ramas se conservan por defecto.

• Tu entorno viaja contigo. .env y compañía (cualquier cosa ignorada por git y listada en .worktreeinclude) se llevan a los nuevos worktrees; setupCommands (pnpm install, docker compose up -d) se ejecutan automáticamente.

• Se mantiene fuera de tu camino. Los worktrees viven en un almacén central (~/.zcode/worktrees), tus repositorios permanecen intactos, y una limpieza de retención mantiene acotado el uso de disco. Nada se elimina silenciosamente.

Instalación

1. En ZCode Desktop, abre Configuración → Gestión de complementos y haz clic en Añadir marketplace.

2. Pega el repositorio — un slug de GitHub owner/repo o una URL completa de Git funcionan ambos:

   agallardol/zcode-git-worktrees

3. Instala Git Worktrees desde el catálogo.

4. Abre cualquier repositorio git y comienza un hilo — ya estás aislado. Escribe /worktree para el panel.

Requisitos: ZCode ≥ 3.8.1, node ≥ 18 en PATH, git.

Si /worktree no aparece: ejecuta node --version en una terminal (el servidor MCP necesita node), confirma que el complemento está habilitado en Instalados, y reinicia ZCode si lo instalaste mientras la aplicación estaba abierta.

Related MCP server: hop-mcp

Los comandos

Detrás de ellos: nueve herramientas MCP (worktrees_create, worktrees_list, worktrees_status, worktrees_remove, worktrees_cleanup, worktrees_prune, worktrees_snapshot, worktrees_set_task, worktrees_auto_session), una habilidad orientada al modelo y hooks — para que el agente pueda usar worktrees por sí solo cuando pidas trabajo paralelo o aislado.

Worktrees de sesión automática (activados por defecto)

Cada nueva sesión en el checkout principal de un repositorio obtiene su propio worktree (zcode/sess-…); reanudar devuelve al mismo, y las ediciones de archivos en el checkout principal se bloquean y se redirigen al worktree de sesión. Actívalo o desactívalo en Configuración → Complementos → Git Worktrees o con /worktree:auto (el cambio más reciente gana). Un repositorio siempre puede optar por no participar:

// .zcode/worktree.json in the repo
{ "autoSession": false }

Configuración del lado del repositorio (opcional)

.worktreeinclude — patrones estilo gitignore; solo los archivos que también están ignorados por git se llevan a los nuevos worktrees (los archivos rastreados nunca se duplican):

.env
config/secrets.json

.zcode/worktree.json — archivos explícitos, hooks de ciclo de vida y la anulación de sesión automática:

{
  "autoSession": true,
  "copyFiles": [".env.local"],
  "setupCommands": ["pnpm install"],
  "preRemoveCommands": ["docker compose down"]
}

Configuración del complemento (Configuración → Complementos → Git Worktrees): raíz del worktree, base predeterminada (fresh = origin/HEAD con respaldo sin conexión, o head), días de antigüedad máxima (14), máximo de worktrees por proyecto (15).

Modelo de seguridad

• Nada escapa del almacén — los nombres se validan para seguridad de rutas y referencias git (traversal, .lock, gemelos de mayúsculas, trucos unicode, todo rechazado), las rutas completas se protegen contra symlinks, las rutas del almacén se canonicalizan; un git worktree add fallido revierte su rama.

• Seguro para concurrencia — las mutaciones se serializan mediante una cola en proceso más un archivo de bloqueo entre procesos; las creaciones paralelas nunca pierden estado.

• Autocuración — el estado corrupto se pone en cuarentena y se reconstruye, los worktrees se re-adoptan de git, las eliminaciones fuera de banda se reconcilian con prune/cleanup.

• Sin ejecución desde repositorios no confiables — setupCommands / preRemoveCommands se ejecutan solo en worktrees que creas explícitamente. Las creaciones de sesión automática nunca ejecutan comandos proporcionados por el repositorio: abrir un repositorio clonado nunca es ejecución de código. Cada llamada a git pasa por execFile; la única ejecución de shell son los comandos de ciclo de vida a los que optaste.

En comparación con las herramientas que lo inspiraron: los checkouts por número de PR y la semántica de .worktreeinclude provienen de Claude Code, la instantánea antes de eliminar y el almacén central de Codex, la retención acotada de Cursor/Codex — además de la orquestación de tareas con agentes en segundo plano y el aislamiento duro de ediciones, que ninguno de ellos expone a los complementos.

Pruebas

npm test   # 129 tests: 80 unit (validators, state, carry-over, hooks, edit guard)
           #        + 13 integration (real MCP stdio JSON-RPC + protocol edges)
           #        + 36 adversarial & security (hostile names, races, corrupt
           #           state, out-of-band damage, exploit regressions)

CI runs the suite on macOS and Linux (Node 20 and 22).

Las suites se ejecutan enteramente contra fixtures locales — sin red, sin llamadas al modelo.

Notas y limitaciones

• El aislamiento de sesión automática es suave para comandos, duro para ediciones: las herramientas Write/Edit se bloquean contra el checkout principal mediante una protección PreToolUse; Bash se guía por contexto inyectado, no se controla estáticamente.

• ZCode no tiene evento de fin de sesión, por lo que nada se confirma o elimina automáticamente al salir — /worktree:end es la línea de meta explícita, y la limpieza de retención recoge lo que queda inactivo.

• Un retraso de una sesión en los cambios de Configuración para la sesión automática (los hooks leen un marcador que el servidor MCP sincroniza al inicio de la sesión).

Licencia

MIT © Alfredo Gallardo