TUT — Take Ur Turn

English | 简体中文

複数のコーディングエージェント（異なるモデル、異なるCLIツール）が同じプロジェクトで協調作業を行います。コンテキストは自動的に共有され、ワークフローは自律的に進行し、人間は承認ゲートでのみ介入します。

TUTは、ローカルマシン上で動作するマルチエージェント協調システムです。その中核はContext Hubです。これは、エージェント間の共有メモリとして機能するローカルMCPサーバー（追記専用のタスクログ）です。タスクの状態は、純粋関数によってレコードシーケンスから導出されます。Notifierは状態変化をポーリングし、手動または自動モードで設計→実装→レビュー→修正のループを駆動します。人間は承認ポイントでのみ判断を下します。

問題点

複数のエージェントを調整する従来の方法は、ファイルの受け渡し（design.md / review.md を回す）です。これには3つの問題点があります。

• コンテキストはファイルの受け渡しで移動する：受け渡しファイルには結論のみが含まれ、推論や破棄された代替案は失われます。次のエージェントは「何を」は得られますが、「なぜ」は得られません。

• ワークフローは手動で駆動される：レビュー・修正ループは通常2〜3ラウンド実行され、毎回手動でトリガーされ、プロンプトが再調整され、コンテキストが再説明されます。

• ツールは互いに分離されている：エージェントセッションは互いを認識できず、統一された状態やオーケストレーションのエントリポイントがありません。

TUTの答え：プロセスメモリをHubに配置し（書き込みはワークフロー上の理由で拒否されない）、ワークフロー状態をログの導出ビューにし（保存も強制もされない）、「誰がスタートボタンを押すか」を手動/自動の2モード選択にします。人間はワークフローのルーターではなく、重要なゲートとなります。

Related MCP server: kitty-hive

中核メカニズム

• 追記専用レコード：エージェントは5つのMCPツール（create / publish / read / list / decide）を介してタスクログにレコードを追加します。design、code_changes、review、revision、note、decision。レコードは決して削除されません。ゼロから始める誰でも、ログだけからすべての決定とその根拠を再構築できます。

• 導出状態：タスクの状態（どこまで進んでいるか、誰の手番か）は保存も強制もされません。純粋関数によってレコードシーケンスから計算されたビューです。状態テーブル外の組み合わせ（例：単独タスクでのレビューの公開）もディスクに書き込まれますが、needs_attentionが設定され、人間が対処できるようになります。

• 承認ゲート：レビューが合格すると、導出状態はpending_approvalになり、人間が決定レコード（approve / reject）を公開するまで何も続行できません。closeはどの状態でも有効で、人間はいつでもタスクを終了する権限を持ちます。

• フローバリアント：タスク作成時に--flow full|direct|soloを選択します。fullは完全なループを実行、directは設計段階をスキップ（リポジトリに既に設計がある）、soloは小さな変更でレビューをスキップします。レビューは不要ですが、承認は不要ではありません（直接承認ゲートへ）。

• 手動/自動進行：手動（デフォルト）では、誰かの手番になったときに人間に通知され、次のステップを開始します。自動では、Notifierがランチャーを介して直接次のエージェントを起動し（ロールホワイトリストによる段階的信頼）、人間はdecide呼び出しのみを行います。

アーキテクチャ

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

タスク状態はレコードシーケンスから導出されます：

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

クイックスタート

前提条件：Node.js ≥ 20、Herdr（Agent Host。エージェントが動作するターミナルペインを提供。brew install herdrでインストール。プロジェクトホームページ https://github.com/herdrdev/herdr）、および少なくとも1つのコーディングエージェントCLI。プラットフォーム：macOS / Linuxのみ（ランチャーはPOSIXシェル。HerdrのWindowsサポートはまだベータ版）。

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

ビルド出力はdist/cli.jsです。npm linkを使用してtutコマンドをPATHに追加します。リンクしたくない場合は、node dist/cli.js <subcommand>が常に機能します（以下ではtutと表記）。

ワークスペースを起動（電源スイッチ、冪等。2つのシステムペイン：hubペイン + notifyペイン）：

tut up

タスクを開始（1文の要件をArchitectのペインに送信。その後、tut listをポーリングしてタスクが表示されるまで待機）：

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

その後、エージェントは自身のペインからMCPツールを介してHubを読み書きすることでタスクを進めます。tut statusで概要を表示し、Notifierは承認が必要なときに通知します。tut decide <task_id> --decision approve --by <your-name>で判断を下します。

Notifierのサイドチャネル（即時ブロックアラート、完了クロスチェック）は、Herdrが各ペインのエージェント状態変更をscripts/on-agent-event.shに転送することに依存しています。これは1回限りの環境設定（Herdrプラグイン）です。配線手順については、design/system-design.mdのセクション7.2を参照してください。

エージェントCLIオンボーディング（1回限り）

HubはMCPツールをStreamable HTTP経由でhttp://127.0.0.1:3001/mcpに公開します（tut serveが起動するとすぐにオンライン。ステートレス、セッションストリームなし）。参加するすべてのエージェントCLIに対して1回設定します。

Codex CLI（~/.codex/config.toml）：

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

Streamable HTTPをサポートする他のMCPクライアント：同じURLを指定します。

設定後、エージェントは5つのツールを認識します：context.create / context.publish / context.read / context.list / context.decide。

MCP-over-HTTPをサポートしないCLI：同等のCLIチャネルを使用します。tut create / publish / read / list / decideサブコマンドはMCPツールに1対1で対応するため、エージェントはシェルから直接呼び出すことができます（スキル内のロール別「ツールチートシート」— MCP | CLIマッピング — はまさにこれらのCLI向けに作られています。2つのチャネルは混在可能で、同じタスクで各ロールがそれぞれのチャネルを使用しても完全に互換性があります）。

MCPを設定する方法がない環境（例：一部のセッションでのサンドボックス制限）：上記のようにCLIチャネルにフォールバックします。

コマンド概要

tutを引数なしで実行すると、完全なUSAGEが表示されます。以下にそのまま引用します：

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

エージェント側の同等チャネルは5つのMCPツール（context.create / context.publish / context.read / context.list / context.decide）です。CLIサブコマンドはそれらに1対1で対応します。

典型的なワークフロー

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)

上の図はデフォルトのフローであるfullです。バリアントはタスク作成時に選択されます（作成時に固定され、永続化後は不変）。

• direct：リポジトリに既に設計があるため、設計段階をスキップします。タスクは実装から開始。レビューと人間の承認は通常通り行われます。

• solo：小さな変更はレビューをスキップします。code_changesから直接pending_approvalが導出され、人間がapprove / rejectを行います。レビューは不要ですが、承認は不要ではありません。approveは依然として人間のゲートです。

設定

3つの設定面があり、性質と場所が異なります。

① プロジェクト実行時設定 — .context-hub/config.json（gitignore対象、プロジェクトごとに1つ）

HubとNotifierの動作を管理します。変更は次のポーリングサイクルで反映されます。再起動は不要です。

② ワークスペース設定 — scripts/workspace.json（リポジトリに同梱）

デフォルトのラインナップ：ロール → { label, agent }（ペインラベル + その席を占有するAgent CLI）。明示的なキャストなしで作成されたタスクに対して解決されます。tut assign <role> <agent>で編集します。routes.jsonはレガシーフォーマットのフォールバックとして残ります。

③ 呼び出しパラメータ — CLIフラグと環境変数

また、一度だけ必要な環境設定として、Herdr イベント配線プラグインがあります（クイックスタート 末尾の配線に関する注釈を参照）。

開発

依存関係は package.json に記載されています。ランタイム依存関係は @modelcontextprotocol/sdk + zod（zod は明示的に宣言されており、SDK と単一インスタンスを共有）です。その他のランタイム依存関係はありません。

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

エージェントロールの動作指示は skills/ にあります（アーキテクト / エグゼキュータ / レビューア / ホスト — 動作テンプレートであり、ID バインディングではありません。テンプレートを読み込んだエージェントはその種の作業を実行できます）。

ドキュメント

• design/system-design.md — システム設計（現在は信頼できる情報源）：アーキテクチャ、状態導出ルール、MCP ツールスキーマ、モジュール契約、技術選択

• design/context-design.md — コンテキスト設計：何を含めるか（スコープ / レコードタイプ / ペイロードエンベロープと本文テンプレート）とその管理方法

設計ドキュメントとスキルは現在中国語です。コード、CLI 出力、コミット規約は英語です。

トラブルシューティングと既知の制限

トラブルシューティング：

• エージェントが context. ツールを認識できないと報告する*：tut serve が実行中であることを確認してください（curl http://127.0.0.1:3001/state が応答すれば動作中です）。CLI の MCP 設定が /mcp エンドポイントを指していることを確認してください。一部の CLI セッションは localhost ループバックからサンドボックス化されている場合があります。その場合は、そのエージェントに CLI チャネル（tut read / tut publish）を使用させてください。動作は完全に同等です。

• ポート 3001 が既に使用中（EADDRINUSE）：tut serve --port <n> でポートを切り替え、残りのコマンドを --url で新しいアドレスに向けてください（tut up のプロビジョニングプローブも含む）。

• npm i -g 後にカスタムラインナップが失われる：tut assign はパッケージ内部の scripts/workspace.json（node_modules 内）に書き込みます。アップグレードによりリセットされます。カスタムラインナップ/レイアウトが必要な場合は、リポジトリをクローンしてそこからインストールしてください。

既知の制限（設計上のトレードオフであり、バグではありません）：

• エージェントのペインは単一セッションです。複数のタスクが同時に同じエージェントを待機する場合、ラウンドプロンプトは同じセッション内で次々に到着します（直列実行、共有コンテキスト）。

• Notifier はポーリング粒度で状態を観測します。ポーリングウィンドウ内の中間状態は観測されません（バージョン番号がジャンプすることがあります）。レコードの再生が信頼できる情報源であり、中間状態はログから再構築できます。

• 自動モードでは、決定レコードが「本当に人間から来た」ことを暗号的に検証する方法はありません。現在のフォールバックは、通知監査と by フィールドによるトレースです。より構造化されたソリューションは、マルチマシン展開シナリオのために残されています。

クレジット

エージェントホスティングは Herdr によって提供されています。これは別途インストールするランタイム前提条件です。このパッケージはそのコードを配布しません。

ライセンス

Apache-2.0