TUT — Take Ur Turn

English | 简体中文

Mehrere Codierungsagenten – verschiedene Modelle, verschiedene CLI-Tools – arbeiten gemeinsam am selben Projekt: Der Kontext wird automatisch geteilt, der Workflow schreitet von selbst voran, und Menschen greifen nur an Genehmigungspunkten ein.

TUT ist ein Multi-Agenten-Kollaborationssystem, das auf Ihrem lokalen Rechner läuft. Sein Kern ist der Context Hub – ein lokaler MCP-Server, der als gemeinsamer Speicher zwischen den Agenten fungiert (ein anfügbares Aufgabenprotokoll). Der Aufgabenstatus wird abgeleitet aus der Aufzeichnungssequenz durch eine reine Funktion; der Notifier fragt nach Statusänderungen und treibt den Design → Implementierung → Review → Überarbeitungs-Zyklus im manuellen oder automatischen Modus voran; Menschen treffen Entscheidungen nur an Genehmigungspunkten.

Das Problem

Die herkömmliche Methode zur Koordination mehrerer Agenten ist die Dateiübergabe (Weiterreichen von design.md / review.md). Sie hat drei Nachteile:

• Kontext reist durch Dateiübergabe: Übergabedateien enthalten nur Schlussfolgerungen – die Begründung und die verworfenen Alternativen gehen verloren. Der nächste Agent bekommt das "Was", aber nicht das "Warum"

• Der Workflow wird manuell gesteuert: Der Review-Überarbeitungs-Zyklus läuft typischerweise 2-3 Runden, jede manuell ausgelöst, mit jedes Mal neu abgestimmten Prompts und erneutem Kontext-Briefing

• Tools sind voneinander isoliert: Agentensitzungen sehen einander nicht; es gibt keinen einheitlichen Status oder Orchestrierungseinstiegspunkt

TUTs Antwort: Legen Sie den Prozessspeicher in den Hub (Schreibvorgänge werden nie aus Workflow-Gründen abgelehnt), machen Sie den Workflow-Status zu einer abgeleiteten Ansicht des Protokolls (nie gespeichert, nie erzwungen), und machen Sie "wer drückt den Startknopf" zu einer Zwei-Modus-Wahl – manuell / automatisch. Menschen sind das kritische Tor des Workflows, nicht sein Router.

Related MCP server: kitty-hive

Kernmechanismen

• Nur-anfügbare Aufzeichnungen: Agenten fügen dem Aufgabenprotokoll Aufzeichnungen über 5 MCP-Tools hinzu (create / publish / read / list / decide) – design, code_changes, review, revision, note, decision. Aufzeichnungen werden nie gelöscht; jeder, der bei Null beginnt, kann jede Entscheidung und ihre Begründung allein aus dem Protokoll rekonstruieren

• Abgeleiteter Status: Der Aufgabenstatus (wo die Dinge stehen, wer am Zug ist) wird nicht gespeichert und nicht erzwungen – er ist eine Ansicht, die aus der Aufzeichnungssequenz durch eine reine Funktion berechnet wird. Kombinationen außerhalb der Statustabelle (z. B. Veröffentlichen eines Reviews in einer Solo-Aufgabe) landen trotzdem auf der Festplatte, setzen aber needs_attention, damit ein Mensch sich darum kümmern kann

• Genehmigungstor: Sobald ein Review bestanden ist, wird der abgeleitete Status zu pending_approval, und ein Mensch muss einen Entscheidungsdatensatz veröffentlichen (approve / reject), bevor etwas weitergeht. close ist in jedem Status gültig – Menschen behalten die Autorität, eine Aufgabe jederzeit zu beenden

• Flow-Varianten: Wählen Sie --flow full|direct|solo beim Erstellen einer Aufgabe – full führt die vollständige Schleife aus; direct überspringt die Designphase (das Repo hat bereits ein Design); solo überspringt das Review für kleine Änderungen – review-frei, aber nicht genehmigungsfrei (direkt zum Genehmigungstor)

• manueller / automatischer Fortschritt: Im manuellen Modus (Standard) wird der Mensch benachrichtigt, wenn jemand an der Reihe ist, und startet den nächsten Schritt; im automatischen Modus startet der Notifier den nächsten Agenten direkt über den Launcher (mit abgestuftem Vertrauen über die Rollen-Whitelist), und Menschen treffen nur decide-Aufrufe

Architektur

┌─────────────────────────────── 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

Der Aufgabenstatus wird aus der Aufzeichnungssequenz abgeleitet:

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

Schnellstart

Voraussetzungen: Node.js ≥ 20, Herdr (der Agent Host, der die Terminalfenster bereitstellt, in denen Agenten leben; installieren mit brew install herdr, Projekt-Homepage https://github.com/herdrdev/herdr), und mindestens ein Codierungsagent-CLI. Plattformen: macOS / Linux nur (der Launcher ist eine POSIX-Shell; Herdrs Windows-Unterstützung ist noch in der Beta-Phase).

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

Das Build-Ergebnis ist dist/cli.js. Verwenden Sie npm link, um den Befehl tut in Ihren PATH zu setzen; wenn Sie nicht linken möchten, funktioniert node dist/cli.js <subcommand> immer (im Folgenden als tut bezeichnet).

Starten Sie den Arbeitsbereich (der Hauptschalter, idempotent – zwei Systemfenster: Hub-Fenster + Notify-Fenster):

tut up

Starten Sie eine Aufgabe (sendet eine einzeilige Anforderung an das Architekten-Fenster; dann fragen Sie tut list ab, bis die Aufgabe erscheint):

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

Von dort aus treiben die Agenten die Aufgabe voran, indem sie den Hub über MCP-Tools aus ihren eigenen Fenstern lesen und schreiben; tut status zeigt die Übersicht, der Notifier benachrichtigt Sie, wenn eine Genehmigung fällig ist, und Sie treffen die Entscheidung mit tut decide <task_id> --decision approve --by <your-name>.

Die Seitenkanäle des Notifiers (sofortige Blockierungsalarme, Erledigungsprüfungen) verlassen sich darauf, dass Herdr die Agentenstatusänderungen jedes Fensters an scripts/on-agent-event.sh weiterleitet – eine einmalige Umgebungseinrichtung (ein Herdr-Plugin); siehe die Verdrahtungsanweisungen in Abschnitt 7.2 von design/system-design.md.

Agent-CLI-Onboarding (einmalig)

Der Hub stellt seine MCP-Tools über Streamable HTTP unter http://127.0.0.1:3001/mcp bereit (online, sobald tut serve läuft; zustandslos, kein Sitzungsstream). Konfigurieren Sie einmalig für jede Agent-CLI, die teilnehmen wird:

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

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

Andere MCP-Clients, die Streamable HTTP unterstützen: Richten Sie sie auf dieselbe URL aus.

Sobald konfiguriert, sieht der Agent 5 Tools: context.create / context.publish / context.read / context.list / context.decide.

CLIs ohne MCP-over-HTTP-Unterstützung: Verwenden Sie den entsprechenden CLI-Kanal – die Unterbefehle tut create / publish / read / list / decide bilden eins-zu-eins auf die MCP-Tools ab, sodass ein Agent sie einfach von der Shell aus aufrufen kann (die rollenspezifischen "Tool-Spickzettel" in den Fähigkeiten – eine MCP | CLI-Zuordnung – sind genau für diese CLIs gemacht; die beiden Kanäle können gemischt werden; bei derselben Aufgabe ist die Verwendung des eigenen Kanals durch jede Rolle vollständig kompatibel).

Umgebungen ohne Möglichkeit zur Konfiguration von MCP (z. B. Sandbox-Einschränkungen in einigen Sitzungen): Fallen Sie wie oben auf den CLI-Kanal zurück.

Befehlsübersicht

Die Ausführung von tut ohne Argumente gibt die vollständige NUTZUNG aus. Wörtlich zitiert:

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>]

Der agentenseitige äquivalente Kanal sind die 5 MCP-Tools (context.create / context.publish / context.read / context.list / context.decide); die CLI-Unterbefehle bilden eins-zu-eins darauf ab.

Typischer Workflow

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)

Das obige Diagramm ist der Standard-Flow, full. Varianten werden beim Erstellen der Aufgabe ausgewählt (festgelegt zum Zeitpunkt der Erstellung, unveränderlich nach dem Speichern):

• direct: Das Repo hat bereits ein Design, daher wird die Designphase übersprungen – die Aufgabe beginnt mit der Implementierung; Review und menschliche Genehmigung laufen wie gewohnt

• solo: Kleine Änderungen überspringen das Review – code_changes leitet direkt pending_approval für eine menschliche approve / reject-Entscheidung ab. Review-frei, aber nicht genehmigungsfrei: approve bleibt das Tor des Menschen

Konfiguration

Drei Konfigurationsoberflächen, unterschiedlich in Art und Ort:

① Projektlaufzeitkonfiguration – .context-hub/config.json (gitignoriert, eine pro Projekt)

Steuert das Verhalten von Hub und Notifier. Änderungen werden im nächsten Abfragezyklus wirksam – kein Neustart erforderlich:

② Arbeitsbereichskonfiguration – scripts/workspace.json (mit dem Repo ausgeliefert)

Standardaufstellung: Rolle → { label, agent } (Fensterbezeichnung + die Agent-CLI, die diesen Platz einnimmt). Wird für Aufgaben aufgelöst, die ohne explizite Besetzung erstellt wurden; bearbeiten mit tut assign <role> <agent>. routes.json bleibt als Legacy-Format-Fallback.

③ Aufrufparameter – CLI-Flags und Umgebungsvariablen

Es gibt auch eine einmalige Umgebungseinrichtung: das Herdr Event-Wiring-Plugin (siehe den Hinweis zur Verkabelung am Ende von Quick Start).

Entwicklung

Abhängigkeiten sind in package.json aufgeführt: die Laufzeitabhängigkeiten sind @modelcontextprotocol/sdk + zod (zod explizit deklariert, damit es eine einzelne Instanz mit dem SDK teilt); es gibt keine weiteren Laufzeitabhängigkeiten.

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

Verhaltensanweisungen für die Agentenrollen befinden sich in skills/ (Architekt / Ausführender / Prüfer / Host — Verhaltensvorlagen, keine Identitätsbindungen: jeder Agent, der eine lädt, kann diese Art von Arbeit ausführen).

Dokumentation

• design/system-design.md — Systemdesign (derzeit maßgeblich): Architektur, Zustandsableitungsregeln, MCP-Tool-Schemata, Modulverträge, Technologieentscheidungen

• design/context-design.md — Kontextdesign: was hineinkommt (Umfang / Datensatztypen / Payload-Envelope und Body-Vorlagen) und wie es verwaltet wird

Design-Dokumente und Skills sind derzeit in chinesischer Sprache; Code, CLI-Ausgabe und Commit-Konventionen sind auf Englisch.

Fehlerbehebung und bekannte Einschränkungen

Fehlerbehebung:

• Agent meldet, dass er die context.*-Tools nicht sehen kann: stellen Sie sicher, dass tut serve läuft (curl http://127.0.0.1:3001/state antwortet bedeutet, dass es aktiv ist); überprüfen Sie, ob die MCP-Konfiguration der CLI auf den /mcp-Endpunkt zeigt; einige CLI-Sitzungen können vom Localhost-Loopback isoliert sein — in diesem Fall lassen Sie diesen Agenten stattdessen den CLI-Kanal verwenden (tut read / tut publish); das Verhalten ist vollständig äquivalent

• Port 3001 bereits belegt (EADDRINUSE): wechseln Sie den Port mit tut serve --port <n> und richten Sie die restlichen Befehle über --url auf die neue Adresse (einschließlich der Bereitstellungssonde von tut up)

• Benutzerdefinierte Aufstellung nach npm i -g verloren: tut assign schreibt das paketinterne scripts/workspace.json (innerhalb von node_modules), das durch ein Upgrade zurückgesetzt wird — wenn Sie eine benutzerdefinierte Aufstellung/Layout benötigen, klonen Sie das Repository und installieren Sie daraus

Bekannte Einschränkungen (Design-Kompromisse, keine Fehler):

• Das Pane eines Agenten ist eine einzelne Sitzung: wenn mehrere Aufgaben gleichzeitig auf denselben Agenten warten, treffen Rundenaufforderungen nacheinander in derselben Sitzung ein (serialisierte Ausführung, gemeinsamer Kontext)

• Der Notifier beobachtet den Zustand in Abfragegranularität: Zwischenzustände innerhalb eines Abfragefensters bleiben unbeobachtet (Versionsnummern können springen); das Abspielen der Aufzeichnungen ist die Quelle der Wahrheit, und jeder Zwischenzustand kann aus dem Log rekonstruiert werden

• Im Auto-Modus gibt es keine kryptografische Möglichkeit zu überprüfen, ob ein Entscheidungsdatensatz "wirklich von einem Menschen stammt" — der aktuelle Fallback ist Benachrichtigungsprüfung plus Rückverfolgung über das by-Feld; eine strukturiertere Lösung bleibt dem Szenario der Mehrrechner-Bereitstellung vorbehalten

Danksagungen

Agenten-Hosting bereitgestellt von Herdr — eine separat installierte Laufzeitvoraussetzung; dieses Paket verteilt seinen Code nicht.

Lizenz

Apache-2.0