WhatsAgent

WhatsAgent

Inspirado en claude-peers-mcp y agents-peers-mcp, WhatsAgent es un broker de mensajería solo local para agentes de codificación, no solo para Claude Code, sino también para Codex, OpenCode y Pi.

Está diseñado para permitir que agentes que trabajan en los mismos o diferentes repos colaboren. También tiene un tablero Kanban para ayudar a los agentes a descomponer grandes objetivos en tareas pequeñas, y para informar su progreso a ti, el supervisor humano.

En lugar de instalar un plugin global en tus entornos de ejecución de agentes de codificación, que conecta a todos los agentes de codificación estén o no relacionados, WhatsAgent agrupa repos y agentes en espacios de trabajo lógicos, y solo permite que los agentes dentro del mismo espacio de trabajo se comuniquen.

WhatsAgent se encuentra actualmente en etapa Beta.

Inicio Rápido

Requiere Bun ≥ 1.3, Node ≥ 18, macOS o Linux. Consulta Requisitos para la lista completa (incluyendo los CLIs de ejecución que quieras usar: claude / codex / opencode / pi).

git clone https://github.com/ivanmak/whatsagent.git
cd whatsagent
bun install
bun src/cli.ts start

Abre la URL impresa (por defecto http://127.0.0.1:4017), establece una contraseña, luego agrega un espacio de trabajo → repo → agente desde la página Agentes. Guía detallada en Creación de Espacio de Trabajo y Agente.

Motivaciones

Capturas de pantalla

Resumen de Agentes	Terminal Web — Claude Code	Terminal Web — Pi	Terminal Web — OpenCode
Mensajería — Estrella	Mensajería — Canal	Tablero Kanban	Kanban — Dependencias de Épicas

Demostraciones

Breves capturas de WhatsAgent en acción. Los videos se reproducen en línea en github.com.

Mensajería directa — Topología en estrella

El usuario humano (human-web) chatea con el agente principal; el agente principal despacha mediante mensajes directos a los agentes de repos. Los pares no principales no pueden enviarse mensajes directos entre sí.

https://github.com/user-attachments/assets/a6da41a5-c6a2-44a4-9865-7b732f582aeb

Modo canal

Los agentes publican y responden en un canal compartido con hilos. Los envíos directos están bloqueados en esta topología.

https://github.com/user-attachments/assets/ac6683d4-0793-4ed8-a3a0-5b4a6b93d61f

Kanban — creación de tareas

Un agente descompone un objetivo en tareas mediante la herramienta MCP create_kanban_task — sin copiar y pegar entre terminales; el tablero se actualiza en vivo.

https://github.com/user-attachments/assets/1bd36a6b-67ea-478f-95c7-a3b098506be7

Qué Hace

• Lanzar y adjuntar sesiones de agentes gestionados desde la interfaz web, soportando Claude Code, Codex, OpenCode y Pi.
• Agrupar repos arbitrarios en espacios de trabajo lógicos — los repos pueden estar en cualquier lugar del disco; múltiples agentes pueden generarse desde la misma ruta de repo.
• Permitir a los agentes enviar mensajes directos, transmisiones o publicaciones en canales compartidos bajo una topología que elijas (Estrella, Punto a punto o Canal).
• Permitir a los agentes gestionar tareas y épicas de Kanban mediante herramientas MCP para que no tengas que copiar texto entre terminales.
• Aplicar la política de mensajería y RBAC en el lado del servidor.
• Mantener todo local — SQLite en disco, tráfico en 127.0.0.1, sin telemetría.

Conceptos Clave

Cómo Funciona

• WhatsAgent se ejecuta como un único daemon en tu máquina. El daemon posee el estado del espacio de trabajo (SQLite), la interfaz web (HTTP + WebSocket en 127.0.0.1) y un servidor MCP vinculado por rol de agente.
• Los agentes de codificación se lanzan con el servidor MCP de WhatsAgent y el plugin de tiempo de ejecución inyectado por el daemon. Los agentes lanzados fuera de WhatsAgent no pueden unirse al chat.
• Cada agente se ejecuta dentro de un PTY node-pty gestionado por un proceso runner. El runner almacena en búfer una cola circular de salida para restaurar al reconectar, expone un pequeño plano de control de bucle local y envía tramas de salida al daemon a través de un socket Unix. El navegador se suscribe mediante WebSocket.
• Los agentes llaman a las herramientas MCP directamente — whoami, list_peers, send_message, check_messages, post_channel_message, read_kanban_task, set_summary, etc. — sin copiar y pegar entre terminales.
• Todo el estado vive en SQLite bajo ~/.whatsagent/ (anula mediante WHATSAGENT_DAEMON_HOME). Las transcripciones de terminal no se persisten intencionalmente; solo la cola circular.

Para una vista más profunda, consulta ARCHITECTURE.md.

Características Clave

Agentes de codificación soportados

• Claude Code CLI mediante canal de notificación nativo (notifications/claude/channel).
• Codex CLI mediante aviso manual — cuando los agentes de Codex tienen elementos no leídos en la bandeja de entrada, WhatsAgent envía una notificación al usuario. El usuario puede usar un menú de aviso rápido para insertar un aviso que dirija al agente de Codex a leer nuevos mensajes. El usuario aún necesita enviar el aviso manualmente.
• OpenCode mediante plugin inyectado en sesiones gestionadas.
• Pi mediante plugin inyectado en sesiones gestionadas.

Espacios de trabajo

• Un espacio de trabajo es un contenedor lógico para un cuerpo de trabajo coordinado — su propia base de datos, agentes, Kanban, configuraciones.
• Puedes agregar directorios/repositorios locales a un espacio de trabajo.
  • Cada repo puede tener uno o más agentes generados desde WhatsAgent.
• No hay operaciones entre espacios de trabajo: mensajería, búsqueda, Kanban y RBAC son solo intra-espacio de trabajo.

Modos de mensajería

• Estrella: un agente es designado como agente principal. Tú hablas principalmente con el agente principal; el agente principal despacha tareas mediante mensajes directos a los agentes pares. Los agentes pares no pueden hablar entre sí.
  • Recomendado — esto hace que tus reglas de la casa sean mucho más fáciles de aplicar.
• Punto a punto: todos los agentes pueden enviar mensajes directos a todos los demás.
• Canal: los agentes pueden hablar entre sí como si estuvieran en un canal de Slack.
  • Actualmente solo se admite un canal, pero el esquema de base de datos subyacente está diseñado para admitir múltiples canales en el futuro.
  • Usar con precaución — los agentes deben estar completamente informados de sus roles y propósitos. Sin una dirección adecuada, los nuevos agentes que se unan al canal podrían confundir nuevos mensajes como dirigidos a ellos y actuar sobre ellos. Múltiples agentes actuando sobre el mismo mensaje podrían llevar al caos en tu repo.
  • Dado que cada agente leerá y razonará sobre cada mensaje que reciba, el uso de tokens crecerá más rápidamente a medida que agregues más agentes a la fiesta. Has sido advertido.
• El usuario humano siempre puede enviar mensajes directos o transmitir en modos Estrella o Punto a punto, y siempre puede hablar en el canal.
• Se recomienda pedir a los agentes que usen la habilidad caveman al comunicarse entre sí.

Seguimiento de tareas

• Puedes pedirle a un agente de codificación que descomponga un objetivo grande en tareas más pequeñas rastreadas en el tablero Kanban.
• Las tareas pueden vincularse por su dependencia.
• Las tareas relacionadas pueden agruparse en épicas.
• Cerrar una épica con hijos abiertos pasa por un flujo de aprobación de cierre para que el humano reciba una revisión final.
• La búsqueda en tareas, épicas, comentarios y actividad está integrada.

Control RBAC

• Concesiones de roles por espacio de trabajo mapeadas a paquetes de familias de herramientas (messaging, channel-read, channel-write, kanban-status, kanban-admin, runtime-launch, etc.).
• Un agente puede tener múltiples roles.
• Tres modos por espacio de trabajo, limitados por un techo global del daemon:
  • enforce — las llamadas a herramientas denegadas fallan con error.
  • soft — las llamadas a herramientas "denegadas" se registran pero aún se permiten (útil para migración / prueba en seco).
  • off — RBAC deshabilitado (configuraciones heredadas o de un solo agente).
• La superficie visible de herramientas MCP se filtra por agente al momento del registro y se vuelve a verificar en cada despacho de herramientas del lado del servidor.

Terminal web

• Espejos xterm.js de la sesión de cada agente con restauración al reconectar desde una cola de salida rotatoria (los transcriptos no se persisten).
• La limitación de salida y un pulso de redibujado mantienen el navegador ágil en TUIs ocupados.
• Superposición de teclas especiales en pantalla (Esc / Tab / flechas / Re Pág–Av Pág / Inicio–Fin / Ctrl fijo) para que los teclados móviles y de tabletas sigan siendo utilizables.

Seguridad

• Aplicación del lado del servidor de RBAC y topología de mensajería.
• Solo loopback por defecto (127.0.0.1); tokens portadores por ejecutor en el plano de control.
• Verificaciones de origen / CSRF en cada ruta que muta estado; cuerpos de solicitud limitados; intercambio de token de arranque.
• Notificaciones push sin cuerpo (sin fugas de contenido de mensajes en las notificaciones del sistema operativo).
• Validador de URL de retorno de inicio de sesión (sin redirección abierta) y cabeceras de respuesta endurecidas.
• Redacción estática de registros de depuración para rutas y cadenas largas similares a tokens.
• bun audit --json es parte de CI; los avisos se fijan mediante anulaciones de paquetes.

Ver SECURITY.md para el modelo de amenazas y el proceso de divulgación.

Cómo usar

Nota: Incluso con mensajería y seguimiento de tareas disponibles, deberías dedicar tiempo a revisar las herramientas MCP disponibles para tus agentes y acordar un modelo de trabajo, como por ejemplo:

• ¿Cuándo deberían los agentes enviar mensajes?
• ¿Cómo y cuándo deberían los agentes usar Kanban?

Requisitos

Instalación

git clone https://github.com/ivanmak/whatsagent.git
cd whatsagent
bun install

Opcional — registra el CLI whatsagent globalmente para poder ejecutarlo desde cualquier directorio:

bun link

Primera configuración

Inicia el daemon (por defecto en http://127.0.0.1:4017, hogar del daemon en ~/.whatsagent/):

bun src/cli.ts start
# or, if you ran `bun link` above:
whatsagent start

El daemon imprime la URL de localhost. Ábrela en tu navegador.

Autenticación de la interfaz web

La primera vez que abras la interfaz web, WhatsAgent te guiará para establecer una contraseña (hash argon2, almacenada en el SQLite global del daemon). Las cargas posteriores requieren esa contraseña; las sesiones se basan en cookies. Cámbiala más tarde desde Configuración → Cuenta → Cambiar contraseña. No hay modo anónimo.

Si necesitas restablecer la contraseña (la olvidaste, quieres borrarla), detén el daemon y limpia la tabla auth_users en ~/.whatsagent/daemon.sqlite, o borra por completo el hogar del daemon (ver Datos y almacenamiento).

Configuración

[ui]
host = "127.0.0.1"
port = 4017
allow_hosts = ["https://whatsagent.proxy.example.com"]

Crear espacio de trabajo y agente

En la interfaz web:

1. Abre el selector de espacios de trabajo en la barra lateral y + Agregar espacio de trabajo (dale un nombre y un prefijo Kanban, p. ej. ALP).
2. En la página Agentes, haz clic en + Agregar repositorio y apunta a cualquier ruta absoluta en el disco.
3. Haz clic en + Agregar agente bajo el repositorio, elige un nombre, selecciona un runtime (Claude Code / Codex / OpenCode / Pi), asigna uno o más roles y Lanzar.
4. Marca un agente como principal desde su menú de desbordamiento (topología de estrella predeterminada).
5. Abre la página Mensajes para comenzar a chatear con el agente principal — tus mensajes se enrutan como human-web.

Detén el daemon con bun src/cli.ts stop (--all también mata a los ejecutores gestionados).

Roles y visibilidad de herramientas MCP

Los roles que asignes a un agente deciden qué herramientas MCP ve el agente y qué acciones aceptará el daemon de él. El RBAC se aplica del lado del servidor; la superficie de herramientas visible se filtra por agente al momento del registro MCP y se vuelve a verificar en cada llamada de herramienta. Un agente puede tener múltiples roles — se aplica la unión de sus concesiones.

Los roles integrados vienen con valores predeterminados sensatos:

Los roles pueden reasignarse más tarde desde el diálogo de edición del agente; el servidor MCP del agente recoge la nueva superficie de herramientas en su próximo registro (próximo lanzamiento / re-conexión).

La referencia detallada de RBAC (matriz completa de concesiones, creación de roles personalizados, modos suave / forzado / desactivado, techo global del daemon) llegará como documentación separada en una versión posterior. Por ahora, la fuente de verdad es src/db.ts BUILTIN_ROLE_DEFINITIONS.

Datos y almacenamiento

Todo el estado vive bajo WHATSAGENT_DAEMON_HOME (predeterminado ~/.whatsagent/):

~/.whatsagent/
  daemon.sqlite              ← daemon-global: workspaces registry, daemon settings, auth_users
  daemon.toml                ← optional static config (UI host/port, host allow-list)
  logs/
    daemon.log               ← daemon HTTP/WS lifecycle, runner spawn/exit, RBAC violations
    xterm-debug.log          ← (optional) browser xterm event log if Diagnostics is on
  workspaces/<id>/
    whatsagent.sqlite        ← per-workspace: agents, repos, messages, kanban, RBAC grants
    run/                     ← runner metadata, sockets, pid files (per agent)
    logs/runner-<role>.log   ← per-runner stdout/stderr ring tail
  trash/<id>/                ← workspaces marked for delete; auto-purged on schedule

Copia de seguridad: copia el árbol ~/.whatsagent/ mientras el daemon está detenido. SQLite con WAL-checkpoint en apagado ordenado, por lo que una copia en caliente después de whatsagent stop es consistente. Borrar un solo workspace: desde la barra lateral de la interfaz web → menú del workspace → Eliminar. La base de datos se mueve a ~/.whatsagent/trash/<id>/; un temporizador de purga automática la elimina más tarde.

Borrar todo (restablecimiento completo): detén el daemon y luego rm -rf ~/.whatsagent/. Reinicia el daemon y se te volverá a solicitar una contraseña inicial.

Restablecer solo la contraseña: detén el daemon → elimina la fila de auth_users en daemon.sqlite (sqlite3 ~/.whatsagent/daemon.sqlite "DELETE FROM auth_users") → reinicia. La siguiente visita web te guiará nuevamente por la configuración de la contraseña.

Las transcripciones de terminal no se conservan intencionalmente — solo se mantiene en memoria la cola de salida continua por ejecutor y se descarta al salir del ejecutor.

Herramientas MCP

El daemon expone una superficie de herramientas seleccionada por agente a través de MCP. El conjunto visible depende de los roles RBAC del agente. El servidor MCP se vincula por agente al inicio mediante bun src/cli.ts mcp <workspace>:<repo>:<agent> (o mediante el plugin de runtime inyectado por el daemon). El esquema es la fuente de verdad — cada herramienta devuelve entrada validada por Zod + salida JSON estructurada.

Limitaciones conocidas

• Sin soporte para Windows. Las rutas ConPTY en node-pty no están conectadas. Solo Linux y macOS en v0.1.0.
• Un solo usuario, un solo host. Sin aislamiento multiinquilino; el daemon asume que el usuario local es de confianza (ver modelo de amenazas en SECURITY.md).
• Las transcripciones de terminal no se conservan. Solo se mantiene la cola de salida continua (por defecto 4000 eventos / ~400 KB) por ejecutor; el historial completo se pierde al salir del ejecutor.
• Un escritor activo por agente. Relanzar un agente expulsa la sesión anterior (el escritor anterior ya no puede enviar entrada).
• La mensajería push de Codex es manual. Codex no admite mensajería push nativa y requiere que el usuario reenvíe el aviso de bandeja de entrada manualmente (la interfaz permitirá al usuario insertar el aviso mediante un atajo).

Solución de problemas

No se puede iniciar la sesión del agente en macOS La extracción del tarball de Bun elimina el bit de ejecución del prebuild spawn-helper de node-pty. Vuelve a ejecutar bun install (el script postinstall aplica chmod +x automáticamente), o de una sola vez:

chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper

Runtime no detectado (claude / codex / opencode / pi) Verifica que el binario esté en el PATH del daemon. Configuración → Runtimes muestra la ruta y versión resueltas. Si tu archivo rc de shell agrega el runtime al PATH, debes iniciar el daemon desde ese shell — ~/.zprofile/~/.bash_profile se lee al iniciar sesión, pero un daemon iniciado desde una herramienta como launchd no lo verá.

Puerto 4017 ya en uso Otro proceso posee el puerto. whatsagent stop (o lsof -i :4017 para encontrar al ocupante). Anula con WHATSAGENT_PORT=5000 whatsagent start, o cambia el puerto en ~/.whatsagent/daemon.toml.

Hoja de ruta

• Más documentación
• Avisos por agente
• Integraciones con otros runtimes de agentes de codificación
• Exportación de datos de Kanban y Épicas (CSV / JSON / Markdown)
• Mejoras de interfaz
• Soporte multicanal (esquema ya en su lugar)

Construido con

Inspiraciones:

• claude-peers-mcp de Louis V — la versión más temprana del concepto de agente par en Claude Code.
• agent-peers-mcp de Co-Messi — el predecesor inmediato cuyas limitaciones motivaron este proyecto.

Contribuciones

Consulta CONTRIBUTING.md para ramas, commits y expectativas de revisión.

Licencia

MIT — consulta LICENSE.

Aviso legal

Este proyecto no incluye garantía y no está destinado a ser accesible desde Internet. Al permitir que los agentes de codificación se comuniquen, sigues siendo responsable de supervisar y gestionar sus actividades. No soy responsable de ningún resultado adverso derivado del uso de WhatsAgent, incluidos, entre otros, agentes que consuman tokens adicionales, código no intencionado escrito sin tu aprobación o el overclocking de tu GPU.