Worktrunk git worktree: CLI para agentes de código en paralelo

Worktrunk git worktree: CLI en Rust para lanzar agentes de código en paralelo, instalación, hooks, límites y qué se puede observar en los logs.
Worktrunk git worktree : CLI pour agents de code en parallèle

Worktrunk git worktree: el repositorio max-sixty/worktrunk es una línea de comandos, escrita en Rust, que simplifica la gestión de los worktrees de Git. Su README la describe como «diseñada para lanzar agentes de IA en paralelo». Se publica con doble licencia MIT o Apache 2.0, a elección. El README se presenta como el gestor de worktrees de Git más popular: es una afirmación del proyecto, que no hacemos nuestra.

El problema es concreto. Cuando cinco o diez agentes de código trabajan en paralelo, cada uno necesita su propio directorio de trabajo. Los worktrees nativos de Git lo permiten, pero la sintaxis es pesada. ¿Cómo aligera Worktrunk este gesto, cómo se instala y qué se puede observar cuando la herramienta se ejecuta en un equipo de desarrollo?

Precisión de honestidad: span.observer no ha instalado ni ejecutado Worktrunk. Los comandos proceden del README y de la documentación del repositorio (carpeta docs/, publicada en worktrunk.dev), leídos el 5 de noviembre de 2026. Las capturas reproducen sus ejemplos. El número de estrellas no se pudo releer en la fuente, por lo que no se cita.

Worktrunk git worktree: lo que dice el repositorio

  • Licencia: el archivo LICENSE recoge los textos MIT y Apache 2.0; Cargo.toml indica MIT OR Apache-2.0.
  • Versión: Cargo.toml y la primera entrada del registro de cambios llevan la versión 0.81.0. La fecha de esa versión no figura en el registro, así que no la citamos. El número 0.x indica un proyecto todavía joven.
  • Principio: los worktrees se direccionan por nombre de rama, y la ruta se calcula a partir de una plantilla configurable. Tres comandos forman el núcleo: wt switch, wt list y wt remove, además de wt merge para fusionar.
  • Agentes: existen plugins para Claude Code, Codex, OpenCode, Pi, oh-my-pi y Gemini CLI. Según la documentación, aportan seguimiento de actividad en wt list, y aislamiento de worktrees solo para Claude Code y OpenCode.

El README compara los comandos con Git a secas: crear un worktree y lanzar Claude pasa de tres comandos encadenados (git worktree add -b, cd, claude) a wt switch -c -x claude feat.

Recorrido por los comandos y la documentación

La primera captura recoge el inicio rápido del README: creación de un worktree y listado del estado de cada rama. Las columnas Commit, Age y Message se quitaron para caber en 860 px; el resto se reproduce tal cual.

Extracto del README de max-sixty/worktrunk: wt switch --create feature-auth y luego wt list, con las columnas Branch, Status, HEAD, main, Remote para dos worktrees

La documentación explica los símbolos: @ marca el worktree actual, + cambios en el área de preparación, ↑1 un commit por delante de main y ⇡ commits sin subir. Para varios agentes, el README da tres comandos wt switch -x claude -c, donde la opción -x lanza un comando tras el cambio de worktree. Los hooks de la documentación se escriben en TOML, y la segunda captura los pone juntos.

Dos extractos: un archivo .config/wt.toml con dos bloques post-start (npm ci, luego npm run build y npm run dev), y los tres comandos wt switch -x claude -c del README para lanzar tres agentes

En este ejemplo de la documentación, install se ejecuta primero, y después build y server se ejecutan a la vez. Los hooks post-* se ejecutan en segundo plano.

Instalación paso a paso

Paso 1: instalar el comando wt

El README propone Homebrew (macOS y Linux), Cargo y otros gestores:

brew install worktrunk && wt config shell install
# o
cargo install worktrunk && wt config shell install

La integración con el shell permite que los comandos cambien de directorio. En Windows, el comando wt entra en conflicto con el de Windows Terminal: por eso Winget instala la herramienta con el nombre git-wt (winget install max-sixty.worktrunk, y luego git-wt config shell install). La FAQ precisa que se requiere Git for Windows, porque los hooks se ejecutan mediante Git Bash. También indica Git 2.43 o posterior como requisito. Arch Linux (pacman) y Conda o Pixi también figuran en la lista.

Paso 2: crear un worktree

  1. En un repositorio Git, ejecuta wt switch --create feature-auth: el comando crea la rama desde la rama por defecto y el worktree.
  2. Trabaja y luego revisa el conjunto con wt list.
  3. Termina con el flujo de pull request (wt step commit, gh pr create y luego wt remove tras la fusión) o con wt merge main, que agrupa squash, rebase, fusión y limpieza.

Paso 3: lanzar varios agentes

wt switch -x claude -c feature-a -- 'Add user authentication'
wt switch -x claude -c feature-b -- 'Fix the pagination bug'

Los argumentos tras -- se pasan al comando lanzado. Según la documentación, wt switch ejecuta primero los hooks pre-start, bloqueantes, y después lanza los hooks post-start en segundo plano.

Paso 4 (opcional): el plugin del agente

wt config plugins claude install

El plugin añade marcadores de actividad en wt list: 🤖 cuando el agente trabaja, 💬 cuando espera. La tercera captura reproduce el ejemplo de la documentación.

Extracto de la documentación de Worktrunk: salida de wt list con cuatro worktrees, entre ellos feature-api marcado con un robot (agente trabajando) y review-ui con una burbuja (agente en espera)

Límites y puntos abiertos

  • Madurez: versión 0.81.0, y un registro de cambios que señala cambios incompatibles («Breaking») en esa misma versión, en particular en los hooks y las plantillas. Léelo antes de cada actualización.
  • Hooks y seguridad: los comandos de los hooks de proyecto piden aprobación en la primera ejecución, que se guarda en ~/.config/worktrunk/approvals.toml. La opción --yes omite las preguntas: resérvala para la integración continua. Un hook de proyecto ejecuta comandos procedentes del repositorio, así que revisa el .config/wt.toml de un repositorio de terceros antes de aprobar.
  • Agentes en paralelo: la documentación advierte de que hooks concurrentes pueden competir por un mismo archivo. Usa bloques ordenados para los comandos dependientes. Consulta también las barreras de protección de los agentes de IA en producción.
  • Disco: cada worktree añade una copia de los archivos rastreados. La copia de las cachés de compilación (wt step copy-ignored) comparte bloques de disco solo en APFS, btrfs y XFS, no en ext4 ni NTFS.
  • Ramas apiladas: no se admiten de forma nativa, según la FAQ.
  • Integraciones: los estados de CI pasan por la CLI de la forja (gh, glab, tea o az) y requieren red con --full.

Observar Worktrunk y sus agentes

Worktrunk es una línea de comandos local, no un servicio. El repositorio no documenta métricas ni exportación OpenTelemetry, y la documentación afirma que la herramienta no recoge telemetría ni estadísticas de uso: por tanto, no suponemos ninguna. Lo que existe está documentado:

  • Registro de comandos: .git/wt/logs/commands.jsonl, una línea JSON por ejecución de hook o de comando LLM, con los campos ts, wt, label, cmd, exit y dur_ms. Rota al llegar a 1 MB.
  • Logs de los hooks en segundo plano: un archivo por hook en .git/wt/logs/{rama}/{origen}/{tipo-de-hook}/{nombre}.log, listados con wt config state logs.
  • Diagnóstico: la opción -vv escribe trace.log, trace.jsonl y subprocess.log, y wt config state logs profile resume las duraciones.
  • Estado de los agentes: los marcadores 🤖 y 💬 de wt list. Un marcador puede quedarse si el agente se mata antes de terminar la sesión; wt config state marker clear lo borra.

Para medir lo que hacen los propios agentes (coste, llamadas a herramientas, duraciones), el enfoque es la instrumentación del agente: consulta la supervisión de un agente de código en la empresa. Para gestionar una flota de agentes, compáralo con Orca.

¿Y Dynatrace?

Worktrunk no documenta ninguna integración con Dynatrace, y no nos inventamos ninguna. Un recolector de logs puede leer el archivo commands.jsonl; la configuración depende entonces de la documentación de la herramienta de recolección que uses.

Buenas prácticas

  • Un worktree por agente y por tarea, con el nombre de la rama, y wt remove una vez hecha la fusión.
  • Pon la instalación de dependencias en pre-start y los servidores de desarrollo en post-start, como recomienda la documentación.
  • Revisa los hooks de proyecto antes de aprobarlos y no pongas ningún secreto en .config/wt.toml.
  • Consulta commands.jsonl cuando falle un hook: ahí están el código de salida y la duración.
  • Equipa a tus agentes con un servidor MCP de confianza, por ejemplo el servidor MCP de GitHub.

Preguntas frecuentes

¿Worktrunk sustituye a git worktree?

No: la herramienta se apoya en Git y en sus worktrees. Añade el direccionamiento por rama, los hooks, el listado de estado y el flujo de fusión. Tus worktrees siguen siendo worktrees de Git normales.

¿Worktrunk funciona con otros agentes además de Claude Code?

Según la documentación, existen plugins para Codex, OpenCode, Pi, oh-my-pi y Gemini CLI. Las funciones difieren: el aislamiento de worktrees solo existe para Claude Code y OpenCode. Los demás agentes se usan con wt switch --create y wt remove.

¿Worktrunk envía datos?

La documentación afirma que no recoge telemetría. Ejecuta git y, opcionalmente, la CLI de la forja para el estado de la CI, así como los comandos LLM que configures tú mismo.

Conclusión

Worktrunk reduce el trabajo repetitivo en torno a los worktrees de Git, lo que importa en cuanto varios agentes de código se ejecutan en paralelo. La herramienta es joven y cambia rápido, y no documenta ninguna métrica: la observación se apoya en sus logs y en la instrumentación de los agentes. Pruébala en un repositorio sin riesgo antes de generalizarla.

span.observer es un blog independiente de la comunidad, no afiliado a Worktrunk ni a su autor, ni a Dynatrace LLC. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba siempre los comandos y opciones en su documentación oficial.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Parcours Terraform Dynatrace SaaS : la formation en 3 modules

Curso Terraform Dynatrace SaaS: la formación en 3 módulos

Next Post
agent-desktop computer use : piloter un bureau par agent IA

agent-desktop computer use: manejar un escritorio con un agente de IA

Related Posts