En resumen: para ejecutar varios agentes de Claude Code en paralelo, asigna a cada sesión su propio git worktree (claude -w <name> lo hace con un solo flag), envía a segundo plano las sesiones que no estés supervisando con claude --bg y define el orden de integración antes de que terminen los agentes, ya que las ramas aisladas siguen entrando en conflicto al fusionarse. Cuando dos sesiones comparten el mismo checkout, el commit de un agente termina arrastrando el código a medio escribir del otro. Esta guía está pensada para desarrolladores que ya usan Claude Code y quieren tener entre dos y cinco sesiones activas al mismo tiempo.
Todo empieza con una segunda terminal. Claude Code está refactorizando el módulo de autenticación en la primera, así que abres otra y le pides a una nueva sesión que arregle ese test de fechas tan inestable. Luego, una tercera para la documentación. Veinte minutos después, tienes tres sesiones escribiendo en el mismo directorio de trabajo, git status muestra archivos que no recuerdas haber pedido y nadie sabe qué sesión modificó config.ts.
Ejecutar varios agentes de Claude Code es fácil: basta con abrir más terminales. Ejecutarlos sin que las sesiones corrompan el trabajo de las demás requiere tomar tres decisiones: dónde residen los archivos de cada sesión, cómo monitorear las sesiones que no tienes en pantalla y en qué orden se integran sus ramas. Este artículo aborda estos tres puntos mediante los comandos nativos de Claude Code y dos fallos que reprodujimos en un repositorio de prueba. Si los worktrees son nuevos para ti, lee primero nuestra guía sobre git worktrees con agentes de programación basados en IA o la documentación de referencia de git worktree.
Por qué ejecutar varios agentes de Claude Code rompe un checkout compartido
Ejecutar varios agentes de Claude Code en paralelo implica tener dos o más sesiones trabajando sobre el mismo repositorio al mismo tiempo, cada una con su propia tarea y su propia ventana de contexto. Las sesiones no saben de la existencia de las demás. Cada una lee archivos, los edita, ejecuta las pruebas y hace commits como si estuviera sola.
Un checkout tiene un único directorio de trabajo, un único índice y un único HEAD, por lo que esa ilusión de estar «a solas» se desmorona rápidamente. Reprodujimos el caso más habitual en un repositorio de Python de prueba, simulando los agentes con dos scripts de terminal. El agente B guardó una función truncate() a medio escribir en textutils.py. El agente A termina su propia tarea en un archivo diferente y hace commit tal como le indican muchos prompts, con git add -A && git commit:
$ git show --stat --format='%an: %s' HEAD
agent-a: add slugify
slug.py | 2 ++
textutils.py | 4 ++++
2 files changed, 6 insertions(+)
$ python3 -m pytest -q
1 error in 0.09s
El commit del agente A arrastra la función inconclusa del agente B, y la suite de pruebas ya ni siquiera puede importarse. No se sobrescribió nada: como el índice era compartido, el commit de A se llevó por delante el trabajo en curso de B, y ahora el historial dice que el agente A escribió código roto. La variante de este problema en la que ambos tocan el mismo archivo se analiza en qué ocurre cuando dos agentes de programación editan el mismo archivo.
Ejecutar varios agentes de Claude Code asignando un worktree a cada uno
La solución consiste en usar un directorio de trabajo independiente para cada sesión, y Claude Code incluye esta opción de forma nativa mediante un flag:
# interactive sessions, one task each, each in its own worktree
claude -w auth-refactor
claude -w flaky-date-test --tmux # opens the session in its own tmux or iTerm2 pane
# fire-and-forget work: starts in the background and prints an id
claude --bg "update the README examples for the new config format"
Según la documentación sobre worktrees, claude -w <name> crea un worktree en .claude/worktrees/<name>/ sobre una nueva rama llamada worktree-<name>, y una segunda terminal con un nombre distinto obtiene una segunda sesión aislada. Al probarlo, git marcó el nuevo worktree como locked, lo que evita que git worktree prune lo elimine en plena ejecución de una sesión activa. Por su parte, las sesiones en segundo plano iniciadas con --bg o /bg se trasladan a su propio worktree dentro de .claude/worktrees/ antes de editar cualquier archivo, de acuerdo con la página de agent view.
Tres detalles de configuración que te ahorrarán una tarde entera de problemas:
- Ignora la carpeta. Como los worktrees residen dentro del repositorio,
git statusmostrará.claude/como no rastreado (untracked) en el checkout principal hasta que agregues.claude/worktrees/a.gitignore, algo que la propia documentación recomienda. - Ten en cuenta que es un checkout limpio. Un worktree nuevo no incluye
node_modules, virtualenv ni.env. Especifica los archivos ignorados por git que necesites copiar (como.env) en un archivo.worktreeincludey ten presente que deberás ejecutar la instalación de dependencias en cada worktree. - Limpia las ejecuciones desatendidas manualmente. Las sesiones interactivas ofrecen eliminar su worktree al salir. En cambio, las ejecuciones iniciadas con
claude -pnunca hacen limpieza automática, por lo que deberás eliminarlas congit worktree unlocky luegogit worktree remove.
Las sesiones en segundo plano se gestionan desde la terminal. Las siguientes descripciones proceden de claude --help en la versión 2.1.283:
| Comando | Qué hace |
|---|---|
claude --bg "<task>" |
Inicia la sesión en segundo plano y regresa de inmediato, mostrando un id |
claude agents |
Abre agent view, la lista de sesiones en ejecución (--json para scripts) |
claude logs <id> |
Muestra la salida reciente de terminal de una sesión en segundo plano |
claude attach <id> |
Abre una sesión en segundo plano en la terminal actual |
claude stop <id> |
La detiene; la conversación se conserva y claude attach <id> la reabre |
--bg no se puede combinar con -p. Si buscas una distribución automatizada mediante scripts (fan-out), la guía de Anthropic para trabajar con Claude Code muestra un bucle de shell sobre claude -p con --allowedTools y --permission-mode dontAsk. Combínalo con -w para que cada ejecución cuente con su propio directorio.
Los agentes aislados de Claude Code siguen colisionando al momento de fusionar ramas
Los worktrees evitan que las sesiones interfieran entre sí mientras trabajan, pero no garantizan que sus cambios sean compatibles. Aplicamos el mismo tipo de modificación en dos ramas de worktree distintas —añadiendo una función al final de textutils.py en cada una— y luego intentamos fusionar ambas:
$ git merge agent/slugify
Fast-forward
$ git merge agent/truncate
Auto-merging textutils.py
CONFLICT (content): Merge conflict in textutils.py
Automatic merge failed; fix conflicts and then commit the result.
Ninguno de los dos agentes hizo nada incorrecto. Ambos añadieron código en el mismo punto y git no puede decidir el orden por sí solo. En una base de código real con cuatro o cinco sesiones simultáneas, este es el escenario habitual en cualquier archivo que todos tocan: tablas de rutas, exportaciones en __init__.py, changelogs o lockfiles. La diferencia frente a un checkout compartido es que ahora el conflicto es evidente, visible y atribuible. Tres buenas prácticas permiten minimizarlo:
- Divide las tareas por archivo, no por funcionalidad. Si dos tareas necesitan modificar el enrutador, deben considerarse una sola tarea, o bien ejecutarse una después de la otra de forma secuencial.
- Fusiona en un orden definido y haz rebase del resto. Integra la primera rama y luego indícale a la siguiente sesión que haga rebase sobre
mainy vuelva a ejecutar sus pruebas antes de que tú la revises. La sesión que escribió el código tiene el contexto necesario para resolver su propio conflicto. - Nombra cada worktree según su tarea.
claude -w fix-date-testes mucho más útil queclaude -w agent2cuando consultesgit worktree listuna hora después.
El verdadero límite rara vez lo impone git: suele ser el tiempo que te lleva revisar cinco diffs. Nuestro artículo sobre por qué la revisión humana es el cuello de botella con agentes en paralelo explica cómo dimensionar esa cola de trabajo.
Subagentes, equipos de agentes o sesiones independientes para Claude Code
Claude Code ofrece ahora varias formas de trabajar en paralelo, y la visión general de agentes paralelos las compara en detalle. No son intercambiables; el aspecto más determinante es el nivel de aislamiento:
| Opción | Qué se ejecuta | Aislamiento de archivos | Cuándo usarlo |
|---|---|---|---|
| Subagentes | Asistentes dentro de una misma sesión, cada uno con su propia ventana de contexto | Checkout compartido, a menos que el subagente configure isolation: worktree |
Una tarea requiere investigación paralela, una pasada de revisión o lecturas simultáneas |
/batch |
Un cambio dividido entre 5 y 30 subagentes | Un worktree por subagente | Un cambio mecánico extenso distribuido en muchos archivos |
| Equipos de agentes (agent teams) | Una sesión principal más compañeros de equipo que comparten una lista de tareas y se envían mensajes entre sí | Ninguno: la documentación aconseja particionar el trabajo | Los compañeros necesitan comunicarse en plena tarea; experimental, desactivado por defecto |
Sesiones independientes (-w, --bg, Desktop) |
Sesiones autónomas | Un worktree por sesión | Tareas independientes que revisas una por una |
Sesiones en la nube (claude --cloud) |
Sesiones en máquinas virtuales aisladas que clonan la rama que subiste | Una máquina virtual por sesión | Trabajo que no debería acaparar los recursos de tu portátil |
Para tareas independientes, utiliza sesiones separadas con worktrees. Emplea equipos de agentes cuando las partes dependan entre sí y los compañeros deban coordinarse; además, asigna archivos distintos a cada uno, ya que la página sobre equipos de agentes es tajante: «Si dos compañeros editan el mismo archivo, se producirán sobrescrituras». Elijas la opción que elijas, el consumo de cuota es compartido. La documentación de agent view lo explica sin rodeos: «ejecutar diez agentes en paralelo consume cuota aproximadamente diez veces más rápido que ejecutar uno solo».
El papel de Sharkly al ejecutar varios agentes de Claude Code
Si ejecutas dos o tres sesiones en tu propio portátil y revisas personalmente cada diff, los comandos anteriores son más que suficientes y probablemente no necesites Sharkly. La situación cambia cuando las sesiones pertenecen a varias personas, o cuando responder a la pregunta «¿en qué sesión está el arreglo del test de fechas?» lleva más tiempo del que costó programar la solución.
Ya dispones de agentes de programación; Sharkly los convierte en un equipo de trabajo. Cada tarea se convierte en un Task. Se la asignas a un Agent que se ejecuta sobre el Runtime de Claude Code en uno de tus Computers, y al definir el Assignee se inicia la ejecución. Con el directorio de trabajo por defecto, Create temporary directory, cada Task obtiene su propio directorio y las ejecuciones vinculadas a un repositorio reciben un git worktree aislado: el mismo aislamiento que ofrece claude -w, pero sin que nadie tenga que nombrar los worktrees a mano. Cuando un Agent necesita reutilizar un entorno que ya existe en un Computer local, Run in isolated worktrees entrega el resultado de cada Task en su propia rama agent/<agent>/<task>. El parámetro Max concurrency (assigned tasks) en el Agent limita cuántas ejecuciones se realizan en simultáneo, formalizando el límite de capacidad de revisión mencionado antes en un lugar visible para todo el equipo.
El progreso, el historial de ejecución y los resultados se registran en el Task, y cualquier asunto que requiera intervención humana llega a Inbox. Nada se fusiona por su cuenta: una persona revisa los cambios del worktree, decide si conservarlos, fusionarlos o descartarlos, y marca el Task como Done. Las ejecuciones se siguen facturando a tu propio plan de Claude Code, ya que Sharkly no vende tokens. La página de características de Agents muestra la configuración, y cómo ejecuta Sharkly agentes en paralelo profundiza en los detalles de ejecución.
Si ya has superado el límite de las tres terminales y necesitas que el resultado de cada sesión de Claude Code esté centralizado en un único lugar donde un revisor pueda gestionarlo, ese es precisamente el problema para el que fue diseñado Sharkly.
Preguntas frecuentes
¿Cuántos agentes de Claude Code puedo ejecutar al mismo tiempo? La documentación no impone un límite máximo para sesiones independientes. Los subagentes tienen un valor predeterminado de 20 ejecuciones simultáneas, y la página de equipos de agentes sugiere comenzar con 3 a 5 compañeros. Los límites reales dependen del consumo de tu plan, la CPU y memoria de tu ordenador, y cuántos resultados eres capaz de revisar en un día; vale la pena calcular esa estimación de capacidad de revisión antes de abrir una sexta sesión.
¿Las sesiones paralelas de Claude Code comparten mis límites de uso? Sí. En los planes Pro y Max, los límites de uso se comparten entre Claude y Claude Code, con una ventana de cinco horas y un límite semanal, por lo que cada sesión paralela consume del mismo saldo. Si se ha configurado la variable ANTHROPIC_API_KEY, Claude Code factura directamente a través de la API.
¿Copia claude --worktree mi archivo .env y las dependencias? No. Cada worktree es un checkout completamente limpio. Añade a .worktreeinclude los archivos ignorados por git que necesites (como .env) y ejecuta el paso de instalación de dependencias en cada worktree.
¿Puedo ejecutar Claude Code y Codex en el mismo repositorio en paralelo? Sí, aplicando la misma regla: un worktree por sesión y un orden de integración definido. Nuestra guía sobre cómo ejecutar Claude Code y Codex juntos en la misma base de código aborda la parte del enrutamiento.
