multi-agents

Haz que varios agentes de IA trabajen juntos, en paralelo, sobre el mismo proyecto, en una sola PC o en varias.

Claude Code, Codex, OpenCode, Gemini CLI, Aider o un script propio: da igual qué agente use cada puesto, ni si están en la misma PC o en máquinas distintas. Con multi-agents todos se conectan a un hub común donde pueden:

• 💬 Enviarse mensajes directos o a todos (all).

• ❓ Preguntar y decidir a través del hub: cuando un agente necesita una decisión, la pregunta (con opciones) llega a quien hizo el pedido, aunque esté en otra PC o en el dashboard, en vez de quedarse esperando en una consola que nadie mira.

• 📋 Repartirse el trabajo en un tablero de tareas (crear, reclamar de forma atómica, pasar a revisión, revisar y cerrar).

• 🔒 Bloquear archivos o carpetas antes de editarlos para no pisarse.

• 👀 Verse entre ellos: quién está conectado, con qué herramienta y modelo, en qué rama y qué está haciendo. El estado se actualiza solo según lo que hace cada agente.

• 📢 Enterarse de todo: el hub anuncia a todos los cambios de las tareas y guarda un historial de actividad (tareas, bloqueos, conflictos, conexiones).

• 🖥️ Seguir todo en un dashboard web en vivo, desde donde los humanos también pueden mandar mensajes, responder preguntas, crear tareas y cambiar su estado.

Novedades de la v0.2: preguntas por el hub, estado automático, anuncios, historial, revisión entre agentes, rama por tarea y init --write. Ver el CHANGELOG.

Es agnóstico de agente y de modelo: cualquier cliente con soporte MCP funciona sin cambios. Los que no tienen MCP pueden usar la CLI desde la terminal, y también hay una API HTTP. Funciona con GitHub, con cualquier remoto git (GitLab, Bitbucket, Gitea…) o sin control de versiones.

 PC 1: Claude Code ──MCP──┐
 PC 2: Codex       ──MCP──┤
 PC 3: OpenCode    ──MCP──┼──► HUB (HTTP) ──► Dashboard web
 PC 4: Gemini CLI  ──MCP──┤     mensajes · tareas · locks · presencia
 PC 5: Aider/otro  ──CLI──┘

Clientes compatibles

La configuración exacta de cada uno está en docs/clients.md.

Related MCP server: ACDP

Requisitos

• Node.js 20 o superior y git en cada máquina que ejecute un agente.

• Si los agentes están en máquinas distintas, estas tienen que poder llegar al hub por red: la misma LAN, Tailscale (recomendado), un túnel HTTPS o un VPS. Ver docs/setup-network.md. Si todo corre en una sola PC, basta con localhost.

Instalación

git clone https://github.com/toroc07/multi-agents.git
cd multi-agents
npm install
npm link
multi-agents --version

npm link deja disponible el comando multi-agents en toda la máquina. Para actualizar más adelante: git pull && npm install.

En PowerShell, si aparece "la ejecución de scripts está deshabilitada", ejecuta una vez Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, o usa multi-agents.cmd en su lugar.

Inicio rápido

1. Levantar el hub

En la máquina que hará de hub:

multi-agents hub --token "un-secreto-largo"

Verás las URLs del hub y el enlace al dashboard (http://<ip>:7777/#token=...). Si hay agentes en otras máquinas, necesitan la URL y el token; compártelos solo por un canal privado. Si no pasas --token, se genera uno al azar.

Opcionalmente, crea el proyecto con su flujo de trabajo. Si no lo haces, se crea solo con el flujo github cuando entra el primer agente.

multi-agents project create mi-app --workflow github \
  --repo https://github.com/yo/mi-app --hub http://localhost:7777 --token "un-secreto-largo"

2. Conectar cada agente

Cada agente trabaja en su propia copia del proyecto (por ejemplo, un git clone del repo). Dentro de esa carpeta:

multi-agents init --client claude-code --name agente-1 \
  --hub http://localhost:7777 --token "un-secreto-largo" --project mi-app --write

El nombre (--name) tiene que ser único para cada agente. Si el hub está en otra máquina, usa su IP en --hub.

--client puede ser claude-code, codex, opencode, gemini, cursor, cline, goose, generic-mcp o cli. El comando:

1. Crea .multi-agents.json con tu configuración local y lo añade a .gitignore. Es el único archivo que contiene el token.

2. Escribe o actualiza AGENTS.md con el protocolo de colaboración. Haz commit de este archivo para que todos los agentes lo lean.

3. Con --write, configura el cliente directamente:

   • Claude Code: claude mcp add;

   • Codex: ~/.codex/config.toml;

   • OpenCode, Gemini y Cursor: su archivo JSON del proyecto, respetando lo que ya tuviera y guardando una copia .bak.

   Sin --write (o para Cline y Goose), te muestra el bloque para pegarlo a mano.

La configuración del cliente solo apunta a .multi-agents.json (multi-agents connect --config …), así que no contiene secretos.

3. A trabajar

Abre tu agente en la carpeta del proyecto y dale una instrucción como:

"Revisa el tablero de multi-agents, reclama una tarea y empieza. Coordínate con los demás agentes."

Cada agente:

• reclama una tarea a la vez;

• bloquea los archivos que va a tocar;

• trabaja en una rama por tarea (agent/<nombre>/task-<id>);

• al terminar, la pasa a revisión y abre un PR;

• otro agente la revisa y la cierra, o la devuelve con cambios.

El hub anuncia cada paso a los demás. Si un agente necesita una decisión, te pregunta por el hub y tú respondes desde el dashboard con un clic. Cuando no tiene nada que hacer, espera mensajes nuevos con wait_for_messages.

Herramientas que recibe cada agente (MCP)

Cada respuesta incluye un aviso "📬 You have N unread messages", así los agentes se enteran de los mensajes aunque estén ocupados en otra cosa.

Los agentes sin MCP tienen los mismos comandos en la CLI:

multi-agents status "Implementando #3"       multi-agents agents
multi-agents msg send all "Terminé el login"  multi-agents msg read        multi-agents msg wait
multi-agents ask "¿Qué validación añado?" --options "Lanzar error|Devolver null"
multi-agents msg send --reply-to 12 "Lanzar error"
multi-agents task list --status open          multi-agents task claim 3    multi-agents task update 3 --status review --review-url <url>
multi-agents lock src/auth --reason "#3"      multi-agents unlock          multi-agents locks
multi-agents protocol

Ejecuta multi-agents help para ver la lista completa.

Flujos de trabajo por proyecto

Otras opciones de project create / project update:

• --default-branch: la rama base (por defecto main).

• --branch-pattern: el nombre de las ramas; admite {agent} y {task}. Por ejemplo "agent/{agent}", si prefieres una rama por agente.

• --max-active-tasks: cuántas tareas puede tener a la vez cada agente (por defecto 1; 0 = sin límite).

El hub no llama a la API de GitHub ni de ningún proveedor: la integración es solo de protocolo y enlaces. Detalles en docs/protocol.md.

Seguridad

• Todo el acceso a la API requiere el token del hub. Trátalo como una contraseña.

• Todos los agentes comparten el mismo token, así que cualquiera que lo tenga puede actuar con cualquier nombre de agente. Compártelo solo con quien sea de confianza.

• El tráfico va por HTTP. Para conectar PCs por internet usa Tailscale o un túnel HTTPS (ngrok, Cloudflare Tunnel) en lugar de abrir el puerto directamente. Ver docs/setup-network.md.

• El token solo se guarda en .multi-agents.json, que init añade a .gitignore. No lo subas a git. Las configuraciones MCP generadas por init no contienen secretos.

• Los mensajes, tareas y locks se guardan en texto plano en data/hub-state.json, en la máquina del hub.

Desarrollo

npm install
npm run build        # compila a dist/
npm test             # compila y ejecuta los tests unitarios y e2e (hub + agentes MCP y CLI reales)
npm run hub          # hub local con token generado

Estructura:

src/
  cli.ts             entrada de la CLI (hub, connect, init y comandos de agente)
  config.ts          configuración (variables de entorno / .multi-agents.json / --config)
  init.ts            asistente de configuración por cliente (--write)
  fileEdit.ts        edición segura de JSON, TOML, .gitignore y AGENTS.md (respeta CRLF/LF)
  hub/               servidor HTTP, estado, historial, persistencia y dashboard
  bridge/            cliente del hub, servidor MCP y comandos CLI
  shared/            tipos, rutas, actividad y protocolo de colaboración
test/                tests unitarios, de init y e2e (vitest)
docs/                documentación

Licencia

MIT