taskswarm

Servidor MCP que envuelve la CLI de taskswarm para la coordinación de tareas multi-agente.

Documentación

TaskSwarm

Instalación • Inicio rápido • Qué hace • Referencia de CLI • Servidor MCP • Comparación • FAQ

Servidor de eventos autohospedado y CLI que dispara una notificación local del sistema operativo y actualiza una página de estado en vivo en el instante en que una sesión de agente de codificación paralela se bloquea, necesita revisión, falla o finaliza.

Installing taskswarm-cli from npm, checking its version, then starting the TaskSwarm server and seeing the live status page URL it prints

Estás ejecutando tres sesiones de Claude Code en dos repositorios. Una de ellas encontró un aviso de permiso hace cuatro minutos y ha estado esperando desde entonces, esperando por ti. No lo sabías, porque nada te lo dijo. Simplemente volviste a la pestaña para verificar.

TaskSwarm es un servidor de eventos autohospedado que soluciona eso. Cada sesión de agente informa su estado, y en el instante en que una se bloquea, necesita revisión, falla o finaliza, TaskSwarm dispara una notificación local del sistema operativo y actualiza una página de estado en vivo. Sin terminales en espera. Sin cuenta. Sin dependencia de la nube.

Instalación

TaskSwarm se distribuye como dos distribuciones independientes, igualmente de primera categoría, del mismo servidor de eventos: un paquete npm (este código base, TypeScript) y un paquete PyPI (taskswarm-cli, Python, python/). Elige el que se ajuste a tu cadena de herramientas; el servidor y el CLI no necesitan ser de la misma distribución que el agente desde el que informas.

npm (JS/TS): disponible en npm como taskswarm-cli:

npm install -g taskswarm-cli
taskswarm start

¿Prefieres no instalar globalmente? npx taskswarm-cli start ejecuta el mismo binario sin paso de instalación.

pip (Python): disponible en PyPI como taskswarm-cli (renombrado del paquete original taskswarm, que ha dejado de recibir actualizaciones y apunta aquí):

pip install taskswarm-cli
taskswarm start

Consulta python/README.md para la guía específica de Python. Ambas distribuciones hablan el mismo protocolo de red (el mismo esquema de eventos, la misma regla de deduplicación de notificaciones), por lo que un servidor iniciado en Python y un CLI npm que informa a él (o viceversa) funcionan juntos sin problemas.

Inicio rápido

# Terminal 1: start the server
node dist/cli.js start
# TaskSwarm server listening on http://127.0.0.1:4173
# Live status page: http://127.0.0.1:4173/?token=<your-token>

# Terminal 2: report a session's status as it works
node dist/cli.js agent report-status --task my-fix --repo ./api --state running
node dist/cli.js agent report-status --task my-fix --repo ./api --state done

Abre la URL de la página de estado en vivo que imprime start. La fila para my-fix se actualiza al instante en que cada llamada a report-status aterriza, sin refrescar. Esta es la salida real de ese flujo, capturada mientras se escribía este README:

{
  "sessions": [
    {
      "session_id": "my-fix",
      "latest": { "repo": "./api", "agent_type": "generic", "status": "done", "...": "..." },
      "history": [
        { "status": "running", "timestamp": "2026-07-15T23:46:41.376Z" },
        { "status": "done", "timestamp": "2026-07-15T23:46:41.436Z" }
      ]
    }
  ]
}

Conéctalo directamente a Claude Code en lugar de llamar a report-status manualmente:

node dist/cli.js hooks install claude-code

Esto escribe hooks de Stop/Notification en .claude/settings.json para el proyecto actual. Cada turno que Claude Code termina, y cada aviso de permiso o espera de inactividad que muestre, ahora se informa automáticamente a TaskSwarm.

Running taskswarm hooks install claude-code and inspecting the Stop/Notification entries it writes into .claude/settings.json

Realiza un seguimiento local de tareas independientemente del estado de sesión en vivo (una lista de tareas ligera, no el feed de eventos):

node dist/cli.js task add --title "Fix flaky test" --repo ./api
node dist/cli.js task list

Adding two tasks with taskswarm task add, then listing them with taskswarm task list in human-readable and --json form

Qué hace

Notificaciones push, desde un tablero que no tienes que mantener abierto. En el momento en que una sesión pasa a blocked, needs-review, failed o done, TaskSwarm dispara una notificación nativa del sistema operativo (osascript en macOS, un fallback de campana de terminal en otros lugares). La latencia de entrega medida está abajo. Ninguno de paperclip, Vibe Kanban o Multica (ver comparación debajo) hace esto; los tres son tableros que tienes que estar mirando.
Una página de estado en vivo que se actualiza mediante eventos enviados por el servidor, no mediante sondeo. Una tabla plana: sesión, repo, tipo de agente, estado, marca de tiempo del último evento. Sin botón de refrescar.
Integración real de hooks de Claude Code, verificada contra la referencia publicada de hooks. taskswarm hooks install claude-code escribe entradas de hooks Stop y Notification en .claude/settings.json, apuntando al binario exacto de Node y al script de CLI que ya están en disco. Deliberadamente evita npx; ver el comentario de código en src/adapters/claude-code-adapter.ts para saber por qué la resolución flotante de registro en cada disparo de hook es un riesgo de cadena de suministro. Una advertencia declarada claramente: el hook Stop de Claude Code se dispara por turno, no por tarea, por lo que una sesión larga de múltiples turnos actualmente informa done después de cada turno, no solo el final.
Un script de envoltura de respaldo para Codex, Cursor o cualquier otra cosa. taskswarm agent report-status --task <id> --repo <path> --state <state> es la misma primitiva que el adaptador de Claude Code llama internamente. Cualquier script que envuelva a cualquier agente CLI puede llamarlo directamente.
Una API local protegida por token de portador, vinculada a loopback por defecto. POST /events y la página en vivo requieren ambos el token que TaskSwarm genera en la primera ejecución (~/.taskswarm/config.json, escrito en 0600). Rota con taskswarm token rotate.
Diseñado nativamente para agentes. Cada subcomando incluye una bandera --json con un esquema estable, incluida la salida de errores, para que un script que llame a este CLI nunca tenga que extraer texto formateado para humanos.
ntfy.sh es opt-in, nunca por defecto. El único canal de notificación que sale de tu máquina, y está desactivado a menos que lo actives. La afirmación de autohospedado se mantiene de principio a fin sin él.

[!NOTE] La notificación push nativa del sistema operativo solo se dispara en macOS, mediante osascript. En Linux y Windows, TaskSwarm recurre a una línea de consola más una campana de terminal en lugar de una notificación del sistema, aún local, aún sin ntfy.sh a menos que optes por ello.

Referencia de CLI

Capturado directamente de la salida de --help del CLI construido (node dist/cli.js <command> --help):

Comando	Descripción	Opciones clave
`taskswarm start`	Inicia el servidor TaskSwarm e imprime la URL de la página de estado en vivo	`--json`
`taskswarm task add`	Registra una nueva tarea	`--title <title>` (requerido), `--repo <path>` (requerido), `--json`
`taskswarm task list`	Lista las tareas rastreadas, enriquecidas con estado en vivo cuando el servidor es alcanzable	`--json`
`taskswarm agent report-status`	Informa una transición de estado para una tarea/sesión al servidor local	`--task <id>` (requerido), `--repo <path>` (requerido), `--state <state>` (requerido, uno de `queued\|running\|blocked\|needs-review\|done\|failed`), `--blocked-reason <text>`, `--agent-type <type>` (`claude-code\|codex\|cursor\|generic`, por defecto `generic`), `--json`
`taskswarm token rotate`	Genera un nuevo token de portador, invalidando el anterior	`--json`
`taskswarm hooks install <adapter>`	Instala hooks para una integración de agente (actualmente `claude-code`)	`--scope <project\|local\|user>` (por defecto `project`), `--project-dir <path>`, `--json`
`taskswarm hooks claude-code-relay`	Interno: lee un payload de hook desde stdin y lo retransmite. Se instala automáticamente; no está pensado para ejecutarse manualmente.	ninguna

Cada subcomando también toma -h, --help. taskswarm --version imprime el número de versión del paquete instalado, leído en vivo desde package.json (para que siempre coincida con la versión que realmente tienes instalada, en lugar de un número fijo que quedaría desactualizado aquí).

Un fallo real, para referencia

$ node dist/cli.js agent report-status --task foo --repo /tmp/x --state bogus
error: option '--state <state>' argument 'bogus' is invalid. Allowed choices are queued, running, blocked, needs-review, done, failed.

$ node dist/cli.js agent report-status --task foo --repo /tmp/x --state blocked
Error: could not reach TaskSwarm server at http://127.0.0.1:4173 -- is it running? (`taskswarm start`)

Ambos salen con código de error distinto de cero y un mensaje en inglés claro y sin traza de pila, incluso bajo --json.

Servidor MCP

La distribución de Python de TaskSwarm incluye un servidor Model Context Protocol, por lo que un agente compatible con MCP (Claude Desktop, Claude Code, un orquestador) puede llamar a TaskSwarm directamente como herramienta en lugar de recurrir al CLI y analizar texto.

pip install "taskswarm-cli[mcp]"

Expone una herramienta, run, un envoltorio genérico de subprocesos: pásale la misma lista de argumentos que pasarías en la línea de comandos, y se conecta al binario taskswarm instalado, analiza el JSON resultante y lo devuelve. Cada modo de fallo (binario faltante, error de lanzamiento, timeout, salida no cero, salida no analizable) retorna como un dict de {"error": ...} ordinario en lugar de lanzar excepción, para que una llamada incorrecta no pueda colgar el servidor.

run(args=["task", "list", "--json"])
# -> {"result": [{"id": "84c94aca-...", "title": "Fix flaky test", "repo": "/tmp/x", "created_at": "2026-08-09T17:37:00.949Z", "status": "unknown"}]}

Para registrarlo con un cliente compatible con MCP, como Claude Desktop, añádelo a la configuración de servidor del cliente:

{
  "mcpServers": {
    "taskswarm": {
      "command": "taskswarm-mcp"
    }
  }
}

Esto asume que taskswarm-mcp ya está en PATH (instalado mediante el extra mcp de arriba). Si lo instalaste en otro lugar, reemplaza "command" con la ruta completa al script de consola. Este servidor es actualmente solo para Python; la distribución npm aún no incluye un servidor MCP.

Comparación

Verificado en vivo contra los metadatos de API de GitHub de cada proyecto y su README, 2026-07-15. Las propias cifras de TaskSwarm se miden, no se estiman. La metodología está debajo de la tabla.

	TaskSwarm	paperclip	Vibe Kanban	Multica
Estrellas	pre-lanzamiento	73,818	27,389	40,638
Licencia	MIT	MIT	Apache-2.0	Código disponible (Apache-2.0 modificado; restringe el uso comercial alojado)
Estado de mantenimiento	activo	activo (commits hoy)	en retirada: la empresa cerró, el README lleva un banner de cierre, último commit 2026-04-24, unos 3 meses desactualizado al momento de escribir esto	activo (commits hoy)
Notificación push/escritorio al cambiar de estado	sí: notificación local del sistema operativo por defecto, ntfy.sh opcional	no encontrado en el README	no encontrado en el README	no encontrado en el README
Interfaz principal	tabla de estado en vivo (SSE)	tablero Kanban completo + organigrama	tablero Kanban completo	tablero Kanban completo
Autoalojado, sin cuenta	sí	sí	sí (guía de autoalojamiento, Docker)	sí (Docker)
Huella de memoria en reposo	~39 MB (medido)	no medido (fuera de alcance)	no medido (fuera de alcance)	no medido (fuera de alcance)
Arranque en frío (arranque del servidor hasta que es accesible)	~0.19 s (medido)	no medido	no medido	no medido

TaskSwarm no intenta superar a ninguno de estos tres en tableros. paperclip y Multica están construidos para gestionar una lista completa de agentes como un organigrama, y Vibe Kanban (mientras duró) era un espacio de trabajo completo de planificación y revisión. TaskSwarm se mantiene enfocado: lo único que ninguno de los tres ofrece es una señal push cuando una sesión te necesita, y ese es todo el producto aquí.

Metodología de referencia (para que puedas reproducirla): medido en macOS 26.5.1, Apple Silicon (arm64), Node v24.4.0, npm 11.15.0, 2026-07-15.

Arranque en frío: desde el lanzamiento del proceso hasta que un curl recibe HTTP 200 desde la URL de la página de estado en vivo, cronometrado con time.perf_counter(), promediado en ejecuciones repetidas (158 a 188 ms observados).
Memoria en reposo: ps -o rss en el proceso node dist/cli.js start en ejecución, unos segundos después del arranque sin sesiones activas (38.4 a 39.4 MB observados en las ejecuciones).
Latencia de ingesta de eventos a despacho de notificación: tiempo de reloj de pared para que una solicitud POST /events devuelva 201, en 20 solicitudes con status: blocked (la ruta de código que llama sincrónicamente a notify(), que genera el proceso de notificación del sistema operativo, antes de que se envíe la respuesta HTTP). Mediana 3.1 ms, media 5.8 ms, p95 24.1 ms, n=20.
Tiempo total hasta el primer tablero (un usuario real por primera vez, git clone nuevo): npm install (2.05 s) más npm run build (0.78 s) más start hasta que la página en vivo es accesible (0.15 s), totalizando 2.99 s, en una máquina con caché npm local caliente. El objetivo era menos de 60 segundos; el resultado medido real es aproximadamente 20 veces menor.

Los números no listados para las otras tres herramientas no son marcadores de posición estimados. Realmente no se midieron, porque ejecutar sus pilas completas (Rust, PostgreSQL, Docker Compose) no estaba en el alcance de esta pasada. Sus conteos de estrellas, términos de licencia y estado de mantenimiento anteriores son hechos verificados en vivo, no puntos de referencia.

Dónde se sitúa TaskSwarm en el panorama más amplio de 2026

paperclip, Vibe Kanban y Multica son los comparables más cercanos con tablero completo, pero no son el panorama completo. Ejecutar varios agentes de codificación en paralelo se convirtió en uno de los rincones más activos del código abierto en 2026: el propio Informe de Tendencias de Codificación Agéntica 2026 de Anthropic nombra la coordinación multiagente como una de las ocho tendencias que remodelan cómo se construye el software, y OpenAI informó que solo Codex superó los 5 millones de usuarios semanales para junio de 2026. Toda una ola de interfaces de orquestación se lanzó junto con ese crecimiento. Aquí es donde se sitúa TaskSwarm junto a las herramientas más nuevas de agentes paralelos que cubren un flujo de trabajo similar con una forma diferente, verificado en vivo el 2026-07-18:

Herramienta	Estrellas	Licencia	Qué es realmente
TaskSwarm	pre-lanzamiento	MIT	Servidor de eventos solo de notificación; sin interfaz que debas mantener abierta
Claude Squad	8,135	AGPL-3.0	Gestor de terminal basado en tmux para sesiones de agentes paralelos, sin función de notificación encontrada en su README
Superset	12,483	Elastic License 2.0 (código disponible)	Editor de código completo construido alrededor de agentes paralelos; "recibe notificaciones cuando necesitan atención" según su propio README
Nimbalyst	1,257	MIT	Espacio de trabajo visual de escritorio con una aplicación móvil complementaria que envía notificaciones; se sincroniza a través de un servidor de colaboración alojado
Paneflow	35	GPL-3.0	Espacio de trabajo de paneles nativo en Rust con cola de atención y notificaciones de escritorio
Conductor (Melty Labs)	código cerrado, sin repositorio público	propietario	Panel de worktree solo para macOS; no instalable desde npm o PyPI

Cada uno de estos te da un lugar para observar a tus agentes trabajar. TaskSwarm está construido sobre la suposición opuesta: no estás observando, así que te empuja a ti en su lugar. Adyacente a esto, el protocolo estandarizado de integración de agentes MCP creció hasta convertirse en su propia categoría principal durante el mismo período, más de 10,000 servidores MCP públicos activos y más de 97M de descargas mensuales de SDK según la actualización del ecosistema de Anthropic de diciembre de 2025 -- el mismo cambio subyacente hacia agentes que se conectan a puntos de integración estándar, que es la misma razón por la que el adaptador de script envolvente de TaskSwarm (taskswarm agent report-status) es deliberadamente agnóstico al protocolo en lugar de estar atado al formato de gancho de un solo agente.

Qué es TaskSwarm y por qué existe

Ejecutar un agente de codificación es una conversación. Ejecutar tres o cuatro en paralelo se convierte en un problema de cambio de pestañas: nada te empuja el estado, así que terminas revisando terminales visualmente solo para descubrir que uno de ellos ha estado esperando en un aviso de permiso durante diez minutos. TaskSwarm existe para cerrar esa brecha: una señal push para el momento en que una sesión realmente necesita a un humano.

El núcleo (servidor de eventos, CLI, página de estado en vivo, integración de gancho de Claude Code) tiene licencia MIT y es gratuito para autoalojar, para uso individual, para un equipo, para cualquier cosa. No hay nivel alojado ni nivel de pago actualmente. El núcleo autoalojado es todo el producto en este momento.

Preguntas frecuentes

¿Esto reemplaza mi tablero Kanban / Linear / GitHub Projects? No. Esos rastrean elementos de trabajo que un humano planifica. TaskSwarm rastrea el estado de las sesiones de agentes en vivo y te avisa al instante en que cambia. Trabajo diferente.

¿Necesito específicamente Claude Code? No. taskswarm hooks install claude-code es la única integración nativa verificada que se envía actualmente. Codex, Cursor o cualquier otra cosa funciona a través de la misma primitiva que el adaptador llama internamente: taskswarm agent report-status, invocable desde cualquier script envolvente alrededor de cualquier agente CLI.

¿A dónde van mis datos? A ningún lugar, por defecto. El servidor se vincula a 127.0.0.1, requiere un token de portador para cada solicitud, y escribe el estado en ~/.taskswarm/ (o donde apunte TASKSWARM_HOME) en tu propio disco. El único canal opcional que sale de tu máquina es ntfy.sh, y está desactivado a menos que lo habilites explícitamente.

¿Esto va a empezar a cobrarme más tarde? El núcleo con licencia MIT sigue siendo gratuito. Todo lo descrito en este README es el producto completo tal como existe hoy, no una prueba ni un nivel limitado de algo más grande.

¿Por qué no usar simplemente tmux y mirar los paneles? Ese es el statu quo al que este proyecto responde. Funciona hasta que ejecutas más de dos o tres sesiones a la vez, momento en el que pasas más tiempo revisando paneles que escribiendo código.

¿Qué pasa si el servidor no está en ejecución cuando llamo a un comando? Los comandos que lo necesitan fallan rápidamente con un mensaje específico (could not reach TaskSwarm server at http://127.0.0.1:4173 -- is it running? (taskswarm start)), no con un trace de pila. task add y task list aún funcionan sin el servidor; solo omiten el enriquecimiento de estado en vivo.

¿Qué es TaskSwarm, exactamente? Un servidor de eventos autoalojado más una CLI. Las sesiones de agentes, o un script envolvente alrededor de cualquier agente, le reportan el estado (taskswarm agent report-status), y él empuja una notificación local del sistema operativo y actualiza una página de estado SSE en vivo al instante en que una sesión pasa a blocked, needs-review, failed o done. No lanza, programa ni ejecuta agentes por sí mismo; solo rastrea y empuja el estado de sesiones que ya se están ejecutando en otro lugar. ¿Cuáles son los requisitos de plataforma e instalación? El paquete npm (taskswarm-cli) necesita Node.js >=18.18.0, según el campo engines en package.json. El paquete PyPI (también taskswarm-cli) necesita Python >=3.9, según pyproject.toml, que también declara Operating System :: OS Independent. Un detalle específico de la plataforma en la práctica: la notificación push nativa del sistema operativo solo se activa en macOS, mediante osascript (ver src/notify/os-notify.ts). En Linux y Windows, TaskSwarm cae en una línea de consola más una campana de terminal en lugar de una notificación del sistema, igualmente local, y sin ntfy.sh a menos que se opte por ello.

¿Cómo se compara TaskSwarm con un competidor específico, como Vibe Kanban o paperclip? Consulta las tablas comparativas anteriores para el desglose completo, pero la versión corta: paperclip y Multica están construidos para ejecutar y visualizar una lista completa de agentes como un organigrama, y Vibe Kanban era un espacio de trabajo de planificación y revisión completo antes de que la empresa que lo respaldaba cerrara (su README lleva un aviso de cierre en el momento de escribir esto). Ninguno de los tres lista una función de notificación push/escritorio en su propio README. TaskSwarm omite el tablero por completo y solo hace una cosa: enviar una señal en el instante en que una sesión te necesita.

¿Puedo usar TaskSwarm en un producto comercial o de pago? Sí. El núcleo (servidor de eventos, CLI, página de estado en vivo, integración con el hook de Claude Code) tiene licencia MIT sin restricción de campo de uso, por lo que autoalojarlo dentro de un producto comercial, un servicio de pago o una herramienta interna es válido. Ese es un punto de diferencia real con Multica en la tabla comparativa anterior, que se distribuye bajo una licencia Apache-2.0 modificada que restringe explícitamente el uso comercial alojado.

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas. Antes de abrir un PR:

npm run lint
npm run typecheck
npm run test:coverage

Los tres deben pasar sin problemas. Para la distribución de Python, cd python && pip install -e ".[dev]" && pytest. Consulta CONTRIBUTING.md para la lista de verificación completa que cubre ambos códigos fuente.

Licencia

MIT. Consulta LICENSE. Libre para autoalojar, modificar y redistribuir, individualmente o en equipo. No existe ninguna versión alojada o de pago en esta versión.