Worktrees en Orca: aísla a tus agentes para que no se pisen

En el tutorial anterior vimos qué es Orca y montamos una sesión de tres agentes en cinco minutos. Pero hay un concepto que merece un artículo entero porque es la razón de ser de Orca: los worktrees.

Si has usado Claude Code o Codex en terminal, te has pegado con esto: lanzas un agente para un bug, quieres lanzar otro para una feature, y ambos trabajan sobre el mismo checkout. Haces stash, creas una rama, cambias, vuelves, y cuando uno termina no sabes qué estado dejó el árbol. Es fricción constante.

Los worktrees de Orca eliminan ese problema de raíz. Cada tarea vive en su propio checkout físico, con su propia rama, sus propios terminales y su propio browser. Los agentes no pueden pisarse aunque ejecuten el mismo comando al mismo tiempo.

Qué es un worktree de Orca

Un worktree no es una rama más en tu checkout. Es un checkout completo y separado en disco. Cuando creas un worktree en Orca, pasa esto:

• Se crea un git worktree real en una ruta física distinta
• Se genera una rama nueva (o se usa la que indiques) como base
• Se abren terminales propios para ese worktree
• Se abre una ventana de Chromium propia (si la necesitas)
• Se calcula el diff contra la rama base en tiempo real

Cuando lo borras, se va todo: rama, directorio, terminales, browser. No hay limpieza manual.

Crear un worktree desde la UI

Es el flujo más común:

1. En el sidebar, junto al nombre de tu repo, click en +
2. Escribe un nombre de tarea. Ej: fix-login-race
3. Orca crea el worktree en segundo plano — puedes seguir trabajando
4. Cuando termina, se abre un terminal con un combobox de agentes
5. Elige Claude Code, Codex, o cualquiera de los 25+ soportados
6. El agente arranca con el directorio correcto y tus credenciales reenviadas

Eso es todo. Tienes un agente trabajando en un checkout aislado sin tocar tu rama principal.

Crear un worktree desde el CLI

Si estás scriptando o un agente necesita crear worktrees programáticamente, el CLI lo hace todo:

# Crear un worktree con un agente y un prompt inicial
orca worktree create --name fix-login-race --agent codex --prompt "arreglar el bug de login en auth.ts" --json

# Crear un worktree sin agente (para ti o para añadirlo después)
orca worktree create --name refactor-api --json

# Listar todos los worktrees activos
orca worktree ps --json

# Ver detalle de un worktree concreto
orca worktree show --worktree name:fix-login-race --json

La respuesta de create incluye un campo id con el formato repoId::worktreePath. Guarda ese valor entero: lo necesitas para cualquier comando posterior (terminales, browser, borrado).

Worktrees con parentesco

Por defecto, un worktree nuevo se basa en la rama principal del repo. Pero puedes crear worktrees hijos de otros worktrees:

# Worktree hijo del worktree activo (stacked)
orca worktree create --name add-validation --parent-worktree active --json

# Worktree hijo de un worktree concreto
orca worktree create --name add-validation --parent-worktree name:fix-login-race --json

# Worktree independiente (sin parentesco)
orca worktree create --name experiment-42 --no-parent --json

El parentesco sirve para trabajo encadenado: primero arreglas un bug, luego desde ese worktree creas otro para añadir tests encima del fix. Orca mantiene la relación para que el diff del hijo se calcule contra el padre, no contra main.

Shared directories: el problema que todo worktree tiene

Un worktree nuevo es un checkout limpio. Eso significa que node_modules no existe, .env no está, y las caches están vacías. En un proyecto real, eso te deja un worktree inutilizable hasta que hagas pnpm install y configures todo a mano.

Orca lo resuelve con tres mecanismos:

1. orca.yaml — directorios symlinkados

Crea un fichero orca.yaml en la raíz de tu repo:

worktree:
  sharedDirectories:
    - node_modules
    - .cache
    - .turbo
    - .next

Cuando Orca crea un worktree, materializa esos directorios del checkout principal al nuevo. En Linux usa symlinks (instantáneo, sin espacio extra). En macOS usa clone-copy.

Esto significa que tu worktree nuevo tiene node_modules disponible sin ejecutar pnpm install. Para proyectos grandes, esto ahorra minutos enteros por worktree.

2. .worktreeinclude — ficheros copiados

Para ficheros que no pueden ser symlinked (como .env, que cada worktree puede necesitar modificar de forma independiente):

# .worktreeinclude (raíz del repo)
.env
.env.local
.vscode/settings.json

Orca copia estos ficheros al nuevo worktree. Cada worktree tiene su propia copia, independiente del original.

3. Worktree Shared Paths (UI)

En Settings → Repository puedes configurar rutas compartidas sin tocar ficheros del repo. Útil cuando no quieres commitear un orca.yaml (por ejemplo, en proyectos donde no eres el único maintainer).

Workflow real: tres agentes en paralelo sobre el mismo bug

Aquí es donde los worktrees brillan. Imagina que tienes un bug de race condition en el login. No sabes si el problema está en el frontend, en el backend, o en la integración. Lanzas tres worktrees:

# Agente 1: Codex investigando el backend
orca worktree create --name fix-race-backend --agent codex --prompt "investigar race condition en /api/auth/session, reproducir y arreglar" --json

# Agente 2: Claude Code en el frontend
orca worktree create --name fix-race-frontend --agent claude --prompt "revisar el formulario de login, hay un race condition entre el submit y el redirect" --json

# Agente 3: Otro enfoque distinto
orca worktree create --name fix-race-alt --agent claude --prompt "reescribir el flujo de auth usando el patrón de redirect-after-post" --json

Los tres worktrees son checkouts físicos independientes. Los tres agentes trabajan en paralelo sin pisarse. Cada uno genera su propio diff contra main.

Cuando terminan, abres los tres diffs en Orca, comparas enfoques, eliges el ganador, haces commit y push. Los otros dos se borran con un click.

# Ver todos los worktrees activos
orca worktree ps --json

# Borrar el worktree perdedor
orca worktree rm --worktree name:fix-race-alt --force --json

Esto es algo que no puedes hacer con git worktree puro + terminales sueltas. La diferencia es que Orca gestiona el ciclo de vida completo: creación, agentes, diffs, borrado.

Estado del worktree: comentarios y status

Orca te deja añadir comentarios cortos a cada worktree para trackear progreso:

# Actualizar el comentario del worktree activo
orca worktree set --worktree active --comment "bug reproducido, probando fix en session.ts" --json

# Cambiar el status (todo, in-progress, in-review, completed)
orca worktree set --worktree active --workspace-status in-review --json

El comentario aparece en la lista de worktrees de la UI. Si tienes cinco agentes corriendo, un vistazo al sidebar te dice en qué está cada uno.

Branching desde issues de GitHub y Linear

Orca no te obliga a salir del IDE para crear worktrees desde issues reales:

• GitHub: ve la lista de PRs e issues dentro de Orca, click en uno, y se crea un worktree con el nombre del issue como rama
• Linear: abre un issue de Linear desde Orca, crea el worktree con el ID del issue (ej: ENG-142), y cuando terminas puedes crear el PR con el issue referenciado

Esto convierte el worktree en la unidad de trabajo natural: un issue = un worktree = un agente trabajando.

Diff viewer: lo que el agente cambió

Cada worktree tiene su diff contra la rama base. Pero el diff viewer de Orca no es un git diff plano:

• Annotate AI Diff: puedes dejar comentarios inline sobre líneas concretas del diff. Esos comentarios se pueden mandar de vuelta al agente como feedback.
• Attribution: Orca trackea qué agente escribió qué líneas. Si tienes tres worktrees y mergearon partes de varios, sabes qué tocó cada uno.
• Conflict resolution: si hay conflictos al mergear, el diff viewer los muestra inline con herramientas de resolución.

Borrar worktrees: limpieza sin rastro

# Borrar un worktree concreto
orca worktree rm --worktree name:fix-race-alt --force --json

# Borrar desde la UI: click en la X del worktree en el sidebar

Al borrar, Orca elimina:

• El directorio físico del worktree
• La rama de git (si no se ha mergeado)
• Los terminales asociados
• Las pestañas de browser
• El estado de UI (splits, scrollback)

Si la rama se ha mergeear a main, Orca te pregunta antes de borrarla. Si no se ha mergeado y usas --force, se va sin pregunta.

Worktrees remotos (SSH)

Orca soporta worktrees en máquinas remotas vía SSH. El concepto es el mismo, pero el checkout vive en el servidor:

• El agente corre en la máquina remota (donde puede tener más RAM, GPU, o acceso a servicios internos)
• Tú ves el diff y el terminal desde tu Orca local
• Los puertos que el agente abre se forwardan a tu laptop automáticamente

Es útil cuando tu repo necesita build steps pesados o cuando el agente tiene que acceder a servicios que solo están en tu red interna.

Patrones de uso que funcionan

Después de meses usando worktrees a diario, estos son los patrones que más valor dan:

1. Race N agents

Un bug, N enfoques. Creas tres worktrees con el mismo prompt, distintos agentes. Gana el que produce el diff más limpio. Es el patrón que más tiempo ahorra cuando no sabes por dónde empezar.

2. Stacked worktrees

Trabajo encadenado: worktree A arregla un bug, worktree B (hijo de A) añade tests sobre ese fix, worktree C (hijo de B) refactoriza el módulo entero. Cada uno se mergea en orden, y los diffs son incrementales.

3. One issue, one worktree

Cada issue de Linear o GitHub genera un worktree. El agente trabaja ahí, tú revisas el diff, haces commit y cierras el issue. El worktree se borra. Es el flujo más limpio para mantenimiento de código existente.

4. Spike and discard

Creas un worktree para probar una idea rápida. Si funciona, haces commit y lo mergeas. Si no, lo borras sin que haya tocado tu rama principal. Cero limpieza.

Lo que no hace un worktree

• No es un container. Un worktree es un checkout de git, no un entorno aislado a nivel de sistema. Si tu proyecto necesita Docker, el worktree no lo gestiona.
• No es una rama virtual. Es un checkout físico real. Ocupa espacio en disco (menos con symlinks para node_modules).
• No se sincroniza solo. Si haces git pull en tu checkout principal, los worktrees no se actualizan automáticamente. Cada uno es independiente hasta que lo mergeas.

Próximos pasos

En el siguiente tutorial cubriremos cómo configurar Claude Code y Hermes Agent dentro de Orca para trabajar codo con codo en el mismo proyecto, con account switching y estrategias de división de trabajo.

Si aún no has leído la introducción a Orca, empieza ahí. Este tutorial asume que ya tienes Orca instalado y un repo añadido.

Para ir más profundo en CLI, la referencia completa está en onorca.dev/docs. Los ejemplos de este artículo los puedes copiar y ejecutar directamente.

Fuentes originales: Orca Docs — Worktrees, Orca CLI reference, repo stablyai/orca en GitHub.