agent-tasks

Gestión de tareas basada en pipelines para agentes de codificación de IA. Un servidor MCP con pipelines de etapas, colaboración multi-agente y un tablero kanban en tiempo real. Las tareas fluyen a través de etapas configurables — backlog, spec, plan, implement, test, review, done — con seguimiento de dependencias, flujos de aprobación, versionado de artefactos y comentarios en hilos.

Diseñado para agentes de codificación de IA (Claude Code, Codex CLI, Gemini CLI, Aider) pero funciona igualmente bien con cualquier cliente MCP, consumidor REST o listener de WebSocket.

¿Por qué agent-tasks?

Cuando ejecutas múltiples agentes de IA en el mismo código base, necesitan un pipeline de tareas compartido — no solo una lista plana de tareas pendientes. Necesitan etapas, dependencias, aprobaciones y visibilidad.

Related MCP server: Agent Harness Kit

Características

• Etapas de pipeline — configurables por proyecto: backlog > spec > plan > implement > test > review > done

• Dependencias de tareas — DAG con detección automática de ciclos; bloquea el avance hasta que se resuelvan

• Flujos de aprobación — aprobar/rechazar por etapas con regresión automática al rechazar

• Colaboración multi-agente — roles (colaborador, revisor, observador), reclamación, asignación

• Jerarquías de subtareas — árboles de tareas padre/hijo con seguimiento de progreso

• Comentarios en hilos — discusiones asíncronas entre agentes sobre cualquier tarea

• Versionado de artefactos — adjuntos de documentos por etapa con versionado automático y visor de diferencias

• Búsqueda de texto completo — búsqueda FTS5 en títulos y descripciones de tareas

• Tablero kanban en tiempo real — arrastrar y soltar, panel lateral, creación en línea, tema oscuro/claro

• 3 capas de transporte — MCP (stdio), API REST (HTTP), WebSocket (eventos en tiempo real)

• Puente TodoWrite — intercepta el TodoWrite integrado de Claude Code y lo sincroniza con el pipeline

• Compuertas de etapa — compuertas configurables por proyecto con reglas por etapa: requerir artefactos nombrados, cantidades mínimas de artefactos, comentarios o aprobaciones antes de avanzar

• Registro de decisiones — artefactos de decisión estructurados (elegí X sobre Y porque Z) mediante task_artifact(type: "decision")

• Propagación de aprendizajes — task_artifact(type: "learning") captura conocimientos (técnica, error, decisión, patrón); se propaga automáticamente a tareas padre y hermanas al completarse

• Afinidad de agente — task_list(next: true) prefiere enrutar tareas a agentes con historial relacionado (padre, dependencia, proyecto) como desempate

• Limpieza basada en heartbeat — falla automáticamente tareas de agentes muertos usando datos de heartbeat de agent-comm

• Hooks de limpieza de tareas — falla automáticamente tareas huérfanas al detener la sesión y limpia tareas obsoletas al iniciar la sesión

• Puente de agente — notifica a agentes conectados sobre eventos de tareas (reclamación, avance, comentario, aprobación)

• Puente de conocimiento — empuja automáticamente artefactos de aprendizaje y decisión a agent-knowledge al completar la tarea, con indexación de embeddings y auto-enlace

Inicio rápido

Instalar desde npm

npm install -g agent-tasks

O clonar desde el código fuente

git clone https://github.com/keshrath/agent-tasks.git
cd agent-tasks
npm install
npm run build

Opción 1: Servidor MCP (para agentes de IA)

Añade a la configuración de tu cliente MCP (Claude Code, Cline, etc.):

{
  "mcpServers": {
    "agent-tasks": {
      "command": "npx",
      "args": ["agent-tasks"]
    }
  }
}

El tablero se inicia automáticamente en http://localhost:3422 en la primera conexión MCP.

Opción 2: Servidor independiente (para clientes REST/WebSocket)

node dist/server.js --port 3422

Integración con Claude Code

Una vez configurado (ver Inicio rápido arriba), Claude Code puede usar las 8 herramientas MCP directamente — crear tareas, avanzar etapas, añadir artefactos, comentar y más. Consulta la Guía de configuración para pasos detallados de integración.

Herramientas MCP (8)

Consulta la referencia completa de la API para descripciones detalladas de cada herramienta y endpoint.

API REST (18 endpoints)

Todos los endpoints devuelven JSON. CORS habilitado. Consulta la referencia completa de la API para más detalles.

GET  /health                          Health check with version + uptime
GET  /api/tasks                       List tasks (status, stage, project, assignee filters)
GET  /api/tasks/:id                   Get a single task
GET  /api/tasks/:id/subtasks          Subtasks of a parent
GET  /api/tasks/:id/artifacts         Artifacts (filter by stage)
GET  /api/tasks/:id/comments          Comments on a task
GET  /api/tasks/:id/dependencies      Dependencies for a task
GET  /api/dependencies                All dependencies across all tasks
GET  /api/pipeline                    Pipeline stage configuration
GET  /api/overview                    Full state dump
GET  /api/agents                      Online agents
GET  /api/search?q=                   Full-text search

POST /api/tasks                       Create a new task
PUT  /api/tasks/:id                   Update task fields
PUT  /api/tasks/:id/stage             Change stage (advance or regress)
POST /api/tasks/:id/comments          Add a comment
POST /api/cleanup                     Trigger manual cleanup

Pruebas

npm test              # 355 tests across 13 files
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run check         # Full CI: typecheck + lint + format + test

Variables de entorno

Dependencias

Requerido: Node.js >= 20.11, better-sqlite3 (incluido)

Opcional (dependencias blandas — fail-open, solo HTTP, sin dependencia npm):

• agent-comm — Limpieza de tareas basada en heartbeat y notificaciones de eventos. agent-comm rastrea heartbeats → agent-tasks verifica heartbeats → falla automáticamente tareas de agentes muertos. También envía mensajes directos al reclamar/avanzar y publica en canales al comentar/aprobar. Sin agent-comm, la detección de agentes obsoletos y las notificaciones se omiten de forma elegante.

• agent-knowledge — Persistencia de conocimiento para aprendizajes y decisiones de tareas. Al completar la tarea, el KnowledgeBridge empuja artefactos learning y decision a agent-knowledge mediante POST /api/knowledge. Las entradas se indexan automáticamente con embeddings, se auto-enlazan a entradas similares y se sincronizan con git. Sin agent-knowledge, los artefactos permanecen solo en agent-tasks.

Documentación

• Referencia de API — las 8 herramientas MCP, 18 endpoints REST, protocolo WebSocket

• Arquitectura — estructura del código fuente, principios de diseño, esquema de base de datos

• Tablero — características del tablero kanban, atajos de teclado, capturas de pantalla

• Guía de configuración — instalación, configuración de clientes (Claude Code, OpenCode, Cursor, Windsurf), hooks

• Registro de cambios

Licencia

MIT — ver LICENSE