TUT — Take Ur Turn

English | 简体中文

Múltiples agentes de codificación — diferentes modelos, diferentes herramientas CLI — colaborando en el mismo proyecto: el contexto se comparte automáticamente, el flujo de trabajo avanza por sí solo y los humanos solo intervienen en los puntos de aprobación.

TUT es un sistema de colaboración multiagente que se ejecuta en tu máquina local. Su núcleo es el Context Hub — un servidor MCP local que actúa como memoria compartida entre agentes (un registro de tareas de solo adición). El estado de la tarea se deriva de la secuencia de registros mediante una función pura; el Notificador consulta los cambios de estado y dirige el bucle diseño → implementación → revisión → revisión en modo manual o automático; los humanos solo toman decisiones en los puntos de aprobación.

El Problema

La forma convencional de coordinar múltiples agentes es la transferencia de archivos (pasando design.md / review.md). Tiene tres puntos débiles:

• El contexto viaja mediante transferencia de archivos: los archivos de transferencia solo contienen conclusiones — se pierden el razonamiento y las alternativas descartadas. El siguiente agente recibe el "qué", pero no el "por qué"

• El flujo de trabajo se impulsa manualmente: el bucle revisión–revisión suele ejecutarse 2-3 rondas, cada una activada manualmente, con indicaciones reajustadas y contexto reexplicado cada vez

• Las herramientas están aisladas entre sí: las sesiones de los agentes no pueden verse entre sí; no hay un estado unificado ni un punto de entrada de orquestación

La respuesta de TUT: poner la memoria del proceso en el Hub (las escrituras nunca se rechazan por motivos de flujo de trabajo), convertir el estado del flujo de trabajo en una vista derivada del registro (nunca almacenada, nunca impuesta), y hacer que "quién presiona el botón de inicio" sea una elección de dos modos — manual / automático. Los humanos son la puerta crítica del flujo de trabajo, no su enrutador.

Related MCP server: kitty-hive

Mecanismos Centrales

• Registros de solo adición: los agentes añaden registros al registro de tareas a través de 5 herramientas MCP (create / publish / read / list / decide) — diseño, code_changes, revisión, revisión, nota, decisión. Los registros nunca se eliminan; cualquiera que empiece desde cero puede reconstruir cada decisión y su fundamento solo a partir del registro

• Estado derivado: el estado de la tarea (dónde se encuentra, de quién es el turno) no se almacena ni se impone — es una vista calculada a partir de la secuencia de registros mediante una función pura. Las combinaciones fuera de la tabla de estados (por ejemplo, publicar una revisión en una tarea en solitario) aún se guardan en disco, pero establecen needs_attention para que un humano pueda manejarlo

• Puerta de aprobación: una vez que una revisión pasa, el estado derivado se convierte en pending_approval, y un humano debe publicar un registro de decisión (approve / reject) antes de que continúe algo. close es válido en cualquier estado — los humanos conservan la autoridad para finalizar una tarea en cualquier momento

• Variantes de flujo: elige --flow full|direct|solo al crear una tarea — full ejecuta el bucle completo; direct omite la etapa de diseño (el repositorio ya tiene un diseño); solo omite la revisión para cambios pequeños — sin revisión pero no sin aprobación (directo a la puerta de aprobación)

• Progresión manual / automática: en manual (el predeterminado), se notifica al humano cuando es el turno de alguien y comienza el siguiente paso; en automático, el Notificador lanza el siguiente agente directamente a través del lanzador (con confianza graduada mediante la lista blanca de roles), y los humanos solo toman decisiones de decide

Arquitectura

┌─────────────────────────────── local machine ────────────────────────────────┐
│                                                                              │
│  coding agent ──MCP read/write──► Context Hub ──► storage (local JSON)       │
│       ▲                            (memory + state projection)               │
│       │ launch                          ▲                                    │
│  Agent Host ──state events──► Notifier ─┘                                    │
│  (signal source + launcher, pluggable)   │ reads derived state (GET /state)  │
│                                          │                                   │
└──────────────────────────────────────────┼───────────────────────────────────┘
                                           ▼ notifications
                                        Channel ──► human
     manual: the human starts the next one | auto: the Notifier starts it via the launcher

El estado de la tarea se deriva de la secuencia de registros:

designing → implementing → reviewing ─┬─ pass       → pending_approval → human decide(approve) → approved → closed
                                       ├─ fail_code  → revising → revision → back to reviewing
                                       └─ fail_design → sent back to designing

Inicio Rápido

Requisitos previos: Node.js ≥ 20, Herdr (el Host de Agentes, que proporciona los paneles de terminal donde viven los agentes; instalar con brew install herdr, página de inicio del proyecto https://github.com/herdrdev/herdr), y al menos una CLI de agente de codificación. Plataformas: solo macOS / Linux (el lanzador es un shell POSIX; el soporte de Windows de Herdr aún está en beta).

git clone https://github.com/ianf-ai/take-ur-turn.git
cd take-ur-turn
npm install
npm run build

La salida de compilación es dist/cli.js. Usa npm link para poner el comando tut en tu PATH; si prefieres no enlazar, node dist/cli.js <subcomando> siempre funciona (referido como tut a continuación).

Inicia el espacio de trabajo (el interruptor de encendido, idempotente — dos paneles del sistema: panel hub + panel notify):

tut up

Inicia una tarea (envía un requisito de una oración al panel del Arquitecto; luego consulta tut list hasta que aparezca la tarea):

tut new "add a --url flag to the CLI's mode subcommand"

A partir de ahí, los agentes avanzan la tarea leyendo y escribiendo el Hub a través de herramientas MCP desde sus propios paneles; tut status muestra la visión general, el Notificador te notifica cuando se necesita una aprobación, y tú tomas la decisión con tut decide <task_id> --decision approve --by <tu-nombre>.

Los canales secundarios del Notificador (alertas de bloqueo instantáneas, comprobaciones de finalización) dependen de que Herdr reenvíe los cambios de estado del agente de cada panel a scripts/on-agent-event.sh — una configuración de entorno única (un plugin de Herdr); consulta las instrucciones de conexión en la sección 7.2 de design/system-design.md.

Incorporación de CLI de Agente (única vez)

El Hub expone sus herramientas MCP a través de Streamable HTTP en http://127.0.0.1:3001/mcp (en línea tan pronto como tut serve esté activo; sin estado, sin flujo de sesión). Configura una vez para cada CLI de Agente que participe:

Codex CLI (~/.codex/config.toml):

[mcp_servers.tut]
url = "http://127.0.0.1:3001/mcp"

Otros clientes MCP que soporten Streamable HTTP: apúntalos a la misma URL.

Una vez configurado, el agente ve 5 herramientas: context.create / context.publish / context.read / context.list / context.decide.

CLI sin soporte MCP sobre HTTP: usa el canal CLI equivalente — los subcomandos tut create / publish / read / list / decide se corresponden uno a uno con las herramientas MCP, por lo que un agente puede simplemente llamarlos desde el shell (las "hojas de trucos de herramientas" por rol en las habilidades — un mapeo MCP | CLI — están hechas exactamente para estas CLI; los dos canales se pueden mezclar; en la misma tarea, cada rol usando su propio canal es totalmente compatible).

Entornos sin forma de configurar MCP (por ejemplo, restricciones de sandbox en algunas sesiones): recurre al canal CLI como se indicó anteriormente.

Resumen de Comandos

Ejecutar tut sin argumentos imprime el USO completo. Citado textualmente:

tut serve [--port <n>] [--root <dir>]
tut notify [--url <u>] [--interval <s>] [--event-port <p>] [--stall-timeout <m>]
tut mode <manual|auto> [--url <u>]
tut start-next [<task_id>] [--url <u>] [--force]
tut create --title <t> --description <d> --creator <c> --role <r> [--flow <full|direct|solo>] [--cast <role=agent,...>] [--url <u>]
tut publish <task_id> --role <r> --content-type <t> --summary <s>
             (--body <text> | --payload-file <md>)
             [--verdict <pass|fail_code|fail_design>] [--commits <a,b>]
             [--ref-version <n>] [--expected-version <n>] [--agent <a>] [--model <m>] [--url <u>]
tut read <task_id> [--since-version <n>] [--json] [--url <u>]
tut list [--status <s>] [--json] [--url <u>]
tut decide <task_id> --decision <approve|reject|close> --by <b> [--reason <text>] [--url <u>]
tut new "<one-sentence requirement>" [--pane <label>]
tut assign <role> <agent>
tut up [--url <u>] [--dry-run]
tut ack <task_id> [--note <text>] [--url <u>]
tut status [--json] [--url <u>]

El canal equivalente del lado del agente son las 5 herramientas MCP (context.create / context.publish / context.read / context.list / context.decide); los subcomandos CLI se corresponden uno a uno con ellas.

Flujo de Trabajo Típico

Architect publishes design
    ↓ derived: designing → implementing
Executor reads context → codes the implementation (runs tests) → publishes code_changes
    ↓ derived: implementing → reviewing
Reviewer reads context → reviews (each finding carries a closing condition) → publishes review
    ├─ pass        → pending_approval → human decide(approve) → approved
    └─ fail_code   → revising → Executor publishes revision → back to reviewing
(The Notifier polls state changes: in manual mode it notifies the human to start the next step; in auto mode it can advance automatically)

El diagrama anterior es el flujo predeterminado, full. Las variantes se eligen al crear la tarea (fijadas en el momento de la creación, inmutables una vez persistidas):

• direct: el repositorio ya tiene un diseño, por lo que se omite la etapa de diseño — la tarea comienza en implementación; la revisión y la aprobación humana proceden como de costumbre

• solo: los cambios pequeños omiten la revisión — code_changes deriva pending_approval directamente para que un humano apruebe / rechace. Sin revisión, pero no sin aprobación: approve sigue siendo la puerta del humano

Configuración

Tres superficies de configuración, diferentes en naturaleza y ubicación:

① Configuración de tiempo de ejecución del proyecto — .context-hub/config.json (ignorado por git, uno por proyecto)

Gobierna el comportamiento del Hub y el Notificador. Los cambios surten efecto en el siguiente ciclo de sondeo — no es necesario reiniciar:

② Configuración del espacio de trabajo — scripts/workspace.json (incluido con el repositorio)

Alineación predeterminada: rol → { label, agent } (etiqueta del panel + la CLI de Agente que ocupa ese asiento). Se resuelve para tareas creadas sin una asignación explícita; editar con tut assign <role> <agent>. routes.json permanece como respaldo de formato heredado.

③ Parámetros de invocación — banderas CLI y variables de entorno

También hay una configuración única de entorno: el plugin de cableado de eventos de Herdr (consulta la nota de cableado al final de Inicio rápido).

Desarrollo

Las dependencias se enumeran en package.json: las dependencias de ejecución son @modelcontextprotocol/sdk + zod (zod se declara explícitamente para que comparta una única instancia con el SDK); no hay otras dependencias de ejecución.

npm install        # install dependencies
npm test           # run tests (vitest)
npm run typecheck  # type-check
npm run build      # compile to dist/

Las instrucciones de comportamiento para los roles de agente se encuentran en skills/ (arquitecto / ejecutor / revisor / anfitrión — plantillas de comportamiento, no vinculaciones de identidad: cualquier agente que cargue una puede realizar ese tipo de trabajo).

Documentación

• design/system-design.md — Diseño del sistema (actualmente autoritativo): arquitectura, reglas de derivación de estado, esquemas de herramientas MCP, contratos de módulos, decisiones tecnológicas

• design/context-design.md — Diseño del contexto: qué incluye (alcance / tipos de registro / plantillas de envoltura y cuerpo de carga útil) y cómo se gestiona

Los documentos de diseño y las habilidades están actualmente en chino; el código, la salida del CLI y las convenciones de commits están en inglés.

Solución de problemas y limitaciones conocidas

Solución de problemas:

• El agente informa que no puede ver las herramientas *context.*: asegúrate de que tut serve se esté ejecutando (curl http://127.0.0.1:3001/state responde significa que está vivo); verifica que la configuración MCP del CLI apunte al endpoint /mcp; algunas sesiones de CLI pueden estar aisladas del loopback de localhost — en ese caso, haz que ese agente use el canal de CLI (tut read / tut publish) en su lugar; el comportamiento es completamente equivalente

• Puerto 3001 ya en uso (EADDRINUSE): cambia de puerto con tut serve --port <n> y apunta los comandos restantes a la nueva dirección mediante --url (incluida la sonda de aprovisionamiento de tut up)

• Lineup personalizado perdido después de npm i -g: tut assign escribe el scripts/workspace.json interno del paquete (dentro de node_modules), que un upgrade restablece — si necesitas un lineup/layout personalizado, clona el repositorio e instala desde él

Limitaciones conocidas (compensaciones de diseño, no errores):

• El panel de un agente es una sola sesión: cuando varias tareas esperan al mismo agente a la vez, las solicitudes redondas llegan una tras otra en la misma sesión (ejecución serializada, contexto compartido)

• El Notificador observa el estado con granularidad de sondeo: los estados intermedios dentro de una ventana de sondeo no se observan (los números de versión pueden verse saltar); la reproducción de los registros es la fuente de verdad, y cualquier estado intermedio se puede reconstruir a partir del registro

• En modo automático no hay una forma criptográfica de verificar que un registro de decisión "realmente provino de un humano" — la solución de respaldo actual es la auditoría de notificaciones más el rastreo a través del campo by; se deja una solución más estructurada para el escenario de implementación multimáquina

Créditos

El alojamiento de agentes es proporcionado por Herdr — un requisito previo de tiempo de ejecución instalado por separado; este paquete no distribuye su código.

Licencia

Apache-2.0