Cómo Sharkly ejecuta agentes en paralelo sin conflictos de merge

Ejecuta dos agentes de programación en el mismo checkout y te toparás con el problema en menos de una hora. Un agente cambia de rama mientras el otro está a mitad de una edición. Los cambios preparados desaparecen dentro de un commit al que no pertenecen. Los tests pasan contra un archivo que el otro agente reescribió a medias. Nada de esto es culpa del modelo. Un árbol de trabajo de git es estado mutable compartido, y dos procesos que modifican estado compartido sin coordinarse acabarán corrompiéndolo.

El remedio habitual es bien conocido: dar a cada agente su propio árbol de trabajo. Los worktrees de Git permiten que un mismo repositorio sirva varios directorios con checkout a la vez, de modo que las ramas paralelas nunca tocan los mismos archivos en disco. Muchos equipos se lo montan con scripts propios; nuestra guía para usar worktrees de git con agentes de programación con IA recorre esa configuración por tu cuenta.

Este artículo trata del otro camino: qué ocurre cuando el aislamiento, la preparación de directorios, los límites de concurrencia y la limpieza los gestiona la plataforma en lugar de tus scripts de shell.

TL;DR

Sharkly ejecuta agentes de IA en paralelo sin conflictos de merge dando a cada ejecución de Task su propio directorio aislado en un Computer conectado. Un servicio local en ese Computer recibe cada ejecución en cola, prepara el directorio de la tarea (para el trabajo respaldado por un repositorio, un worktree de git independiente por ejecución), inicia el Runtime seleccionado y transmite el progreso, los eventos de traza y el resultado de vuelta al Task. Los límites de concurrencia del Agent y del Computer acotan cuántas ejecuciones se llevan a cabo a la vez, y nada se fusiona por su cuenta: el resultado vuelve al Task, donde una persona revisa el cambio y decide el paso de merge y release. Los Agents nunca comparten un árbol de trabajo, así que los Tasks en paralelo no pueden pisarse los cambios entre sí.

El fallo que Sharkly está diseñado para evitar

Conviene ser preciso sobre qué sale mal cuando los agentes comparten un checkout, porque cada síntoma se corresponde con una pieza de la solución.

El estado de rama es global por árbol de trabajo, así que cuando el agente A hace checkout de su propia rama, los archivos del agente B cambian bajo sus pies a mitad de ejecución. El índice también es global, así que git add y git commit entremezclan trabajo de distintas tareas. El estado sin rastrear choca: los artefactos de compilación y las instalaciones de dependencias de una ejecución contaminan los resultados de los tests de otra. Y la deuda de limpieza se acumula, porque cada copia ad hoc del repositorio hecha para esquivar los tres primeros problemas se queda en disco hasta que alguien se acuerda de que existe.

Un único directorio compartido solo puede ejecutar un agente de forma segura. Si estás haciendo malabares con paneles de tmux y mucha disciplina, nuestro artículo sobre ejecutar varios agentes de Claude Code en paralelo explica por qué ese techo llega tan rápido.

La pila de ejecución: Agent, Computer, Runtime y Task

Sharkly no sustituye a Claude Code, Codex ni a otras herramientas de ejecución. Añade la capa compartida de tareas, Computer, contexto, control y revisión en torno a las herramientas que tu equipo ya utiliza. Esa posición como capa determina cómo funciona la ejecución en paralelo, porque la función de Sharkly es coordinar ejecuciones, no escribir código.

Cuatro roles se reparten el trabajo, y cada uno tiene exactamente una función:

• El Agent define cómo debe gestionarse el trabajo: sus instrucciones, Skills, repositorios y ajustes de ejecución. Un Agent no es el host de ejecución.
• El Computer aporta el host y los recursos locales: una máquina local, un servidor remoto, un contenedor o un host en la nube compatible. El artículo hermano sobre los Computers en Sharkly explica cómo conectarlos.
• El Runtime lleva a cabo la sesión real del agente. Es la herramienta concreta instalada en ese Computer, como Claude Code, Codex o Gemini CLI.
• El Task sigue siendo el registro compartido para el equipo: objetivo, estado, conversación, traza de ejecución y resultado.

Lo que los une es un pequeño servicio local en el Computer. Registra el Computer, detecta los Runtimes instalados, recibe las ejecuciones en cola, prepara el directorio de la tarea para cada ejecución, inicia el Runtime y devuelve los resultados. Es él quien inicia la conexión con el servidor, así que una configuración típica no necesita ningún puerto de entrada.

Esa separación es lo que hace viable el paralelismo. Como el servicio local prepara el directorio de trabajo en cada ejecución, y no lo elige el Agent, dos Agents asignados a dos Tasks pueden apuntar al mismo repositorio en el mismo Computer sin ver jamás los archivos del otro. Para saber cómo se configuran los Agents, consulta Agents en Sharkly.

Qué ocurre cuando se inicia una ejecución

Asigna un Task a un Agent y sácalo de Backlog: Sharkly comprueba la disponibilidad de ejecución, pone en cola una ejecución elegible y la envía al Computer seleccionado. A partir de ahí toma el control el servicio local. Antes de que arranque el Runtime, puede que tenga que esperar a que haya capacidad de concurrencia, preparar un directorio temporal aislado o esperar a que se libere uno especificado, obtener los repositorios configurados, proyectar las variables de entorno permitidas y construir la invocación del Runtime.

Solo entonces se inicia el Runtime. La ejecución pasa por estados explícitos: Queued, Dispatched, Waiting for local directory, Running y, por último, Completed, Failed o Canceled. Esos estados aparecen en el registro de ejecución del Task, así que «¿por qué no ha pasado nada todavía?» tiene una respuesta consultable en lugar de una suposición. Una ejecución detenida en Queued porque se ha alcanzado el límite de concurrencia no se ve igual que una detenida en Waiting for local directory, y la diferencia te indica qué ajuste tocar.

Fíjate en lo que no aparece: en ningún momento decide el Agent dónde ejecutarse. El Agent aporta las instrucciones; la infraestructura aporta el aislamiento.

Worktrees aislados: cómo funciona el modo Temporary

Los Agents admiten dos modos de directorio de trabajo, y el modo pensado para el trabajo en paralelo es el modo Temporary. Cada Task recibe un directorio aislado y, para el trabajo respaldado por un repositorio, el servicio local puede preparar un git worktree independiente para cada ejecución a partir de los datos del repositorio en caché.

Esa sola frase resume toda la historia de la prevención de conflictos. Un worktree da a cada ejecución su propio directorio con checkout y su propio estado de rama, a la vez que comparte los objetos subyacentes del repositorio. Los cuatro fallos anteriores desaparecen por construcción: no hay puntero de rama compartido, ni índice compartido, ni artefactos de compilación compartidos, y los directorios los puede limpiar la plataforma más adelante. Como los worktrees proceden de datos en caché y no de un clon nuevo, el coste de arranque se mantiene razonable, aunque una ejecución todavía puede necesitar acceso a la red para actualizar el repositorio.

La documentación es clara sobre cuándo usarlo: el modo Temporary se recomienda para cambios de código en paralelo y para cualquier situación en la que varios Tasks puedan modificar la misma base de código a la vez.

Merece la pena dejar claro un límite: el aislamiento evita colisiones en el árbol de trabajo, no conflictos semánticos. Si dos Tasks reescriben la misma función, ambas ejecuciones terminan sin problemas en sus propios worktrees, y aun así una persona tendrá que reconciliar el solapamiento durante la revisión. La solución es delimitar bien los Tasks para que no apunten al mismo código la misma tarde: una decisión de planificación, no de infraestructura.

Cuándo el aislamiento es la opción equivocada: el modo Specified

El segundo modo existe porque un directorio nuevo por ejecución no sale gratis. En el modo Specified, el Agent se ejecuta dentro de un directorio local absoluto configurado de su grupo, reutilizando el repositorio, las dependencias y las cachés que ya hay allí. Solo está disponible en Computers locales.

Este intercambio tiene una consecuencia ineludible: un directorio especificado atiende una ejecución a la vez y, cuando todos los directorios configurados están ocupados, la siguiente ejecución espera. Un Agent que deba ejecutar varios Tasks de forma simultánea en modo Specified necesita varios directorios en su grupo.

El aislamiento compra seguridad a cambio de preparación; la reutilización compra velocidad a cambio de serialización. Sharkly te obliga a elegir explícitamente por Agent, lo que es mejor que descubrir el intercambio en un árbol de trabajo corrupto.

Límites de concurrencia: en paralelo, pero acotados

El paralelismo sin límites es un fallo en sí mismo. Cada ejecución simultánea consume CPU, memoria, disco, capacidad del proveedor de modelos y ancho de banda del repositorio; ocho agentes machacando un portátil dan peores resultados que tres trabajando con holgura.

Sharkly acota la concurrencia en dos niveles. El Computer tiene un límite de concurrencia de tareas como host, y cada Agent tiene un número máximo de Tasks en ejecución simultánea más un timeout por Task. Los valores por defecto son conservadores: en modo Temporary, un Agent recibe el 50 por ciento del límite del Computer; en modo Specified, coincide con el número de directorios configurados. Si lo pones por encima del número de directorios, el producto avisa de que las escrituras pueden chocar entre tareas. Ese aviso es la tesis de este artículo comprimida en un solo cuadro de diálogo.

La recomendación de la documentación sobre subir los límites es de lo más sensata: aumenta la concurrencia solo cuando el Computer y el Runtime actuales gestionen la carga existente de forma fiable.

Seguimiento del progreso y revisión antes del merge

El aislamiento sería un lastre si además implicara invisibilidad. Cinco agentes en cinco directorios ocultos es exactamente cómo el trabajo desaparece en terminales privadas. Por eso todo lo que produce la ejecución vuelve al registro compartido.

Mientras una ejecución está activa, el Task muestra su estado de ejecución. La actividad reúne los comentarios y los cambios de la tarea en una línea temporal; el registro de ejecución anota cuándo empezó y terminó la ejecución, las llamadas a herramientas y los eventos del Runtime, el origen del desencadenante y cualquier detalle de error; el informe del Agent se guarda como un comentario vinculado a su traza de ejecución. El contexto, el progreso, los bloqueos y los resultados permanecen visibles desde la solicitud hasta el release, aunque las ediciones de archivos ocurrieran en un directorio que ninguna persona llegó a abrir.

Y después llega el punto de control. Aquí nada se fusiona por su cuenta. Los Agents investigan, ejecutan, prueban e informan. Las personas marcan la dirección, otorgan autoridad y aceptan el resultado. Cuando una ejecución termina, el Agent puede dejar el Task a la espera de revisión humana, algo que aparece en la bandeja de entrada de la persona responsable. Los worktrees aislados hacen que la ejecución en paralelo sea segura; el punto de control de revisión la hace fiable.

Una pieza más cierra el círculo: la limpieza. Las ejecuciones de los Agents dejan directorios de trabajo y artefactos en el Computer, y una limpieza configurable recupera las ejecuciones terminadas tras un periodo de retención, con un umbral mínimo de espacio libre como red de seguridad. El trabajo en ejecución o en cola, las ejecuciones fijadas y las ejecuciones fallidas que aún requieren investigación nunca se tocan. Esta es la tarea que las configuraciones por tu cuenta olvidan sistemáticamente hasta que el disco se llena.

Qué automatiza Sharkly frente a la configuración por tu cuenta

Si has leído nuestra guía de worktrees por tu cuenta, la correspondencia es directa. El git worktree add que automatizas por agente se convierte en el servicio local preparando un directorio aislado por ejecución. La decisión de «cuántos agentes son demasiados» se convierte en límites de concurrencia explícitos, con avisos cuando un ajuste no es seguro. El git worktree prune que olvidas se convierte en una limpieza basada en retención. Y la parte que ningún script te da, un registro compartido de qué ejecución hizo qué y si una persona lo aceptó, es el propio Task.

El criterio honesto para decidir también se aplica aquí. Puede que un desarrollador en solitario que ejecuta dos agentes en una máquina no necesite una plataforma; un script de worktrees y algo de disciplina bastan para llegar lejos. Recurre a Sharkly cuando la coordinación cueste más que escribir código: varias personas asignando trabajo, varios Computers, ejecuciones que necesitan cola y revisión. En cualquier caso, conservas los Runtimes que ya tienes; el uso de modelos sigue funcionando con las suscripciones o claves de API configuradas en esas herramientas.

Empezar es deliberadamente sencillo. Conecta un Computer, crea un Agent en modo Temporary y asígnale un Task de bajo riesgo. La guía de primeros pasos recorre el primer ciclo en unos diez minutos, la documentación de Sharkly cubre cada concepto en profundidad y qué es Sharkly completa la plataforma en torno a la ejecución.

Preguntas frecuentes

¿Cómo evita Sharkly los conflictos de merge entre agentes en paralelo?

Cada ejecución de Task recibe su propio directorio aislado en el Computer, y las ejecuciones respaldadas por un repositorio pueden tener cada una un git worktree independiente preparado por el servicio local. Los Agents nunca comparten un checkout, un índice ni archivos sin rastrear, así que las ejecuciones simultáneas no pueden sobrescribir el trabajo en curso de las demás. Los solapamientos en los que dos Tasks cambian el mismo código a propósito siguen siendo reconciliados por una persona en el momento de la revisión.

¿Tengo que configurar los worktrees de git yo mismo para usar Sharkly?

No. En modo Temporary, el servicio local prepara el directorio de la tarea en cada ejecución, incluidos los worktrees para el trabajo respaldado por un repositorio. Configuras el modo en el Agent una sola vez; no hay comandos de worktree por ejecución que automatizar. Para entender el mecanismo subyacente, consulta la documentación de git worktree.

¿Cuántos agentes pueden ejecutarse en paralelo en un mismo Computer?

El Computer tiene su propio límite de concurrencia de tareas, y cada Agent tiene un número máximo de Tasks en ejecución simultánea. Por defecto, un Agent en modo Temporary recibe el 50 por ciento del límite del Computer, y uno en modo Specified obtiene una ranura por cada directorio configurado. Las ejecuciones que superan el límite esperan en la cola.

¿Sharkly fusiona automáticamente los cambios del agente?

No. El resultado, las evidencias y la traza de la ejecución vuelven al Task, y una persona revisa el resumen de cambios antes de que se publique nada. Quien revisa acepta, solicita cambios o decide el paso de merge y release. La automatización se detiene donde hace falta el criterio del equipo.

¿Cuándo debería usar el modo Specified en lugar de worktrees aislados?

Úsalo cuando preparar un directorio nuevo por ejecución resulte realmente caro: un repositorio muy grande, estado generado o cachés costosos, o herramientas ligadas a una única ruta local. Asume que cada directorio especificado atiende una ejecución a la vez. Para todo lo demás, el modo Temporary es la opción predeterminada recomendada.