FXCode
ENTRAR →
Doc. 11 — Funciones

Trabajo en paralelo (worktrees)

Varios agentes trabajando a la vez en el mismo repo, cada uno en su worktree de git, con su sesión, avisos de choque y limpieza al terminar.

Un agente por worktree, una tarea por rama. Cuando lanzas varios agentes a la vez sobre el mismo repositorio, cada uno trabaja en su propio worktree de git: una carpeta aparte con su rama, sin pisarse los cambios. FXCode sabe quién está en cada una, avisa si dos van a chocar y te dice qué carpetas sobran cuando terminan.

Se apoya en las ramas y PR: la rama de cada línea de trabajo lleva el id de la tarea, así que el webhook de GitHub la reconoce igual.

Abrir una línea de trabajo

# Desde el repo (cualquier worktree)
fxc tasks start cm4k2x9ab0001 --worktree
# ✓ Login con GitHub: Working · feat/fxc-cm4k2x9ab0001-login-con-github
# Session: claude-code on mi-portatil (C:/code/tienda-fxc-ab0001)
#
# Worktree ready. Enter it with:
#
#   cd "C:\code\tienda-fxc-ab0001"

Con --worktree, fxc tasks start:

  1. Crea el worktree ../<repo>-fxc-<id corto> junto al principal, con la rama feat/fxc-<taskId>-<slug-del-título> (o reutiliza la rama si ya existe). Parte de --base <rama> o, si no la pasas, de la rama de origin/HEAD, main o master.
  2. Pasa la tarea a Working (el primer estado animado del catálogo; --status elige otro).
  3. Registra la sesión de trabajo.
  4. Imprime la ruta para entrar.

No ejecuta nada más: no instala dependencias ni lanza al agente. Sin --worktree, fxc tasks start <id> hace los pasos 2 y 3 en el directorio actual.

La sesión de trabajo

Cada fxc tasks start y fxc tasks finish envía el contexto de git de donde se ejecuta:

Dato De dónde sale
Rama git rev-parse --abbrev-ref HEAD
Worktree y si es el principal git rev-parse --show-toplevel y git worktree list --porcelain
Máquina el nombre del equipo (hostname)
Agente --agent <nombre> o las variables de entorno que deja cada uno: CLAUDECODE (claude-code), CODEX* (codex), CURSOR_TRACE_ID (cursor), GEMINI_CLI (gemini)… Si no hay ninguna, manual
Archivos tocados git diff --name-only <base>...HEAD más lo pendiente sin commitear, hasta 300 rutas

Con eso FXCode guarda una sesión por tarea, máquina y worktree: inicio, último latido y fin.

  • Latido. Cualquier comando fxc sobre esa tarea (tasks get, update, comment, arch link, arch focus --task…) la refresca. Para refrescarla a propósito (y enviar los archivos tocados): fxc tasks heartbeat <id>.
  • Inactiva. Una sesión sin latido en 15 minutos pasa a «inactiva»: sigue en el panel, atenuada, pero ya no cuenta para los choques.
  • Fin. fxc tasks finish <id> la cierra.

El panel «En paralelo»

Cada proyecto tiene la pestaña En paralelo: una fila por sesión abierta con la tarea, el agente, la máquina, la rama o el PR, el worktree y la última actividad. Debajo, el diagrama de la arquitectura con las piezas que tocan las sesiones activas iluminadas (las enlazadas a su tarea y las que tienen en foco). Se actualiza solo.

Posible choque

Aparece un aviso en rojo cuando dos sesiones activas tocan la misma pieza de la arquitectura, o los mismos archivos (los que manda la CLI en los latidos). La pieza se marca en rojo en el diagrama. Es un aviso, no un bloqueo: dos agentes pueden tocar la misma API sin pisarse, pero conviene saberlo antes de mergear.

Lo mismo desde la terminal:

fxc worktrees status --project-id <projectId>
# … tabla de sesiones …
# ! Possible clash: «Pagos recurrentes» and «Login con GitHub» (pieces api; files src/shared.ts)

Limpiar al terminar

fxc worktrees            # los worktrees del repo actual: rama, tarea, estado y si se mergeó
fxc worktrees prune      # ofrece borrar los mergeados o con la tarea terminada
fxc worktrees prune --yes

fxc worktrees asocia cada worktree a su tarea por el id de la rama o por la sesión registrada. prune propone borrar los que tienen la rama ya mergeada en la base o la tarea terminada (o el PR mergeado), y pide confirmación salvo con --yes. Nunca borra:

  • el worktree principal ni el actual;
  • uno con cambios sin commitear (lo avisa y lo deja);
  • uno bloqueado (git worktree lock);
  • uno cuya rama está «mergeada» pero cuya tarea sigue en Working (una rama recién creada, sin commits, también está contenida en la base).

Borra con git worktree remove. En Windows, si falla por rutas demasiado largas, elimina la carpeta y ejecuta git worktree prune. Las ramas no se borran.

En la web, el panel muestra «N worktrees para limpiar» con la máquina y la carpeta de cada uno. La web no puede borrar nada en tu máquina: ejecuta fxc worktrees prune en el repo de cada una.

Desde un agente por MCP

Herramienta Qué hace
report_work_session Abre o refresca la sesión de una tarea (end: true la cierra). En el MCP local toma el contexto de git del directorio del servidor; en el remoto se le pasan branch, worktreePath, hostname, agent y files
parallel_work El panel del proyecto: sesiones, posibles choques y worktrees para limpiar

Regla para agentes

Al lanzar trabajo en paralelo, abre cada línea con fxc tasks start <id> --worktree y trabaja dentro de esa carpeta. Al terminar, fxc tasks finish <id> desde el worktree y, cuando la rama esté mergeada, fxc worktrees prune.