wtx

Gestor de worktrees de Git con servidor MCP integrado. Crea, inspecciona y limpia espacios de trabajo aislados desde tu terminal — o deja que tus agentes de código con IA lo hagan por sí mismos.

Los agentes de código con IA en paralelo dejaron obsoletos los malabarismos con git stash — pero git worktree add ../foo -b foo && cd ../foo && cp ../.env . es una tarea que nadie quiere repetir cinco veces al día. wtx convierte los worktrees en un flujo de una sola palabra para humanos y para agentes:

$ wtx new fix-login
✔ created worktree fix-login
  path:   ~/code/myapp/.worktrees/fix-login
  branch: wt/fix-login (new)
  copied: .env, .env.local

Tu agente obtiene el mismo poder a través de MCP:

{ "name": "create_worktree", "arguments": { "name": "fix-login", "setup": "npm install" } }

Por qué wtx

• Una herramienta, dos interfaces. Una CLI rápida para ti y un servidor MCP (wtx mcp) para Claude Code, Cursor, Codex o cualquier agente compatible con MCP.

• Cero dependencias. Un único binario de Node.js que solo invoca a git. Nada que auditar, nada que romper.

• Consciente de la higiene. Cada worktree muestra su uso de disco y su última actividad. Recupera gigabytes de clones de node_modules obsoletos con wtx clean --dry-run.

• Seguro por defecto. Se niega a borrar worktrees sucios, nunca toca el checkout principal, elimina ramas solo cuando están del todo fusionadas y oculta .worktrees/ mediante .git/info/exclude (sin ensuciar el .gitignore).

• Con todo incluido. Copia los archivos de entorno en cada worktree nuevo y ejecuta automáticamente el hook de configuración de tu proyecto.

Instalación

npm install -g wtx        # or: brew install wtx (planned)

Requiere Node.js ≥ 18 y cualquier git moderno.

Inicio rápido

$ cd myapp
$ wtx new feat-search          # isolated workspace at .worktrees/feat-search on branch wt/feat-search
$ cd $(wtx path feat-search)   # jump in
$ wtx ls                       # see every workspace, its state and size
NAME       BRANCH         STATUS       AGE      SIZE     PATH
myapp*     main           ✓ clean      2d ago   412 MB   ~/code/myapp
feat-api   wt/feat-api    ● dirty (1)  3h ago   38 MB    ~/code/myapp/.worktrees/feat-api
$ wtx clean --dry-run          # preview reclaimable space
· feat-api (branch merged, 38 MB)
would free: 38 MB · kept 0 worktree(s)

Comandos

Flags universales: --json (salida legible por máquina), --base <ref>, --setup <cmd>, --no-copy, --no-setup.

Úsalo desde agentes de IA (MCP)

Añádelo a la configuración de tu cliente MCP:

// e.g. claude_desktop_config.json / opencode.json / .mcp.json
{
  "mcpServers": {
    "wtx": { "command": "npx", "args": ["-y", "wtx", "mcp"] }
  }
}

El servidor expone cuatro herramientas: list_worktrees, create_worktree, remove_worktree, clean_worktrees. Todas aceptan un repo_path opcional; de lo contrario, se usa el directorio de trabajo del servidor. Las respuestas son JSON, así que los agentes pueden encadenarlas: crear → trabajar → eliminar sin cambiar de rama en tu checkout principal.

Ejemplo de prompt para tu agente: "Configura un espacio de trabajo llamado oauth-fix basado en develop, ejecuta pnpm install dentro y dime la ruta."

Configuración

Puedes dejar un wtx.config.json (o .wtxrc) en la raíz del repositorio:

{
  "dir": ".worktrees",
  "copyFiles": [".env", ".env.local"],
  "setup": "pnpm install",
  "branchPrefix": "wt/"
}

Modelo de seguridad

• El worktree principal nunca se elimina con rm ni clean.

• Los worktrees sucios siempre se conservan con clean, y rm necesita --force.

• Las ramas solo se eliminan cuando ya están lucas integradas en la rama por defecto (origin/HEAD → main → master como fallbreak).

• Los directorios de worktrees están en .worktrees/, excluidos mediante .git/info/exclude para que el .gitignore no se modifique.

• Los nombres se regularizan; se rechazan trayectos como ../evil.

Comparativa

Desarrollo

git clone https://github.com/willkhinz/wtx && cd wtx
npm install
npm test        # build + 32 integration/unit tests
node dist/src/cli.js help

Arquitectura: src/core.ts (motor), src/cli.ts (interfaz para humanos), src/mcp.ts (interfaz para agentes). La implementación de MCP es JSON-RPC 2.0 nuevo, delimitado por nuevas líneas y sin dependencias.

Roadmap

• wtx exec <name> -- <cmd> para ejecutar comandos en todos los worktrees

• Abrir sesiones de tmux / iTerm por worktree

• Fórmula de Homebrew

• GitHub Action: comentar los PR with previsualizaciones por worktree

Licencia

MIT