TUT — Take Ur Turn

English | 简体中文

여러 코딩 에이전트 — 서로 다른 모델, 서로 다른 CLI 도구 — 가 동일한 프로젝트에서 협업합니다: 컨텍스트는 자동으로 공유되고, 워크플로우는 자동으로 진행되며, 인간은 승인 게이트에서만 개입합니다.

TUT는 로컬 머신에서 실행되는 다중 에이전트 협업 시스템입니다. 핵심은 컨텍스트 허브(Context Hub) — 에이전트 간 공유 메모리 역할을 하는 로컬 MCP 서버(추가 전용 태스크 로그)입니다. 태스크 상태는 순수 함수에 의해 레코드 시퀀스에서 파생됩니다; Notifier는 상태 변경을 폴링하여 수동 또는 자동 모드에서 설계 → 구현 → 검토 → 수정 루프를 구동합니다; 인간은 승인 지점에서만 결정을 내립니다.

문제점

여러 에이전트를 조정하는 기존 방식은 파일 핸드오프(design.md / review.md 전달)입니다. 여기에는 세 가지 문제점이 있습니다:

• 컨텍스트가 파일 핸드오프로 전달됨: 핸드오프 파일은 결론만 전달합니다 — 추론 과정과 폐기된 대안은 손실됩니다. 다음 에이전트는 "무엇"은 얻지만 "왜"는 얻지 못합니다

• 워크플로우가 수동으로 구동됨: 검토-수정 루프는 일반적으로 2-3회 실행되며, 각각 수동으로 트리거되고, 매번 프롬프트가 재조정되고 컨텍스트가 다시 브리핑됩니다

• 도구가 서로 격리됨: 에이전트 세션은 서로를 볼 수 없습니다; 통합된 상태나 오케스트레이션 진입점이 없습니다

TUT의 해결책: 프로세스 메모리를 허브에 넣고(워크플로우 이유로 쓰기가 거부되지 않음), 워크플로우 상태를 로그의 파생 뷰로 전환하며(저장되지 않고 강제되지 않음), "시작 버튼을 누르는 사람"을 수동/자동 두 가지 모드로 만듭니다. 인간은 워크플로우의 라우터가 아닌 중요한 게이트입니다.

Related MCP server: kitty-hive

핵심 메커니즘

• 추가 전용 레코드: 에이전트는 5개의 MCP 도구(create / publish / read / list / decide)를 통해 태스크 로그에 레코드를 추가합니다 — design, code_changes, review, revision, note, decision. 레코드는 절대 삭제되지 않습니다; 처음부터 시작하는 누구든 로그만으로 모든 결정과 그 근거를 재구성할 수 있습니다

• 파생 상태: 태스크 상태(현재 상황, 누구의 차례인지)는 저장되지 않고 강제되지 않습니다 — 순수 함수에 의해 레코드 시퀀스에서 계산된 뷰입니다. 상태 테이블 외부의 조합(예: 단독 태스크에서 리뷰 게시)도 디스크에 저장되지만, needs_attention을 설정하여 인간이 처리할 수 있도록 합니다

• 승인 게이트: 리뷰가 통과하면 파생 상태가 pending_approval이 되고, 인간이 결정 레코드(승인/거부)를 게시해야 계속 진행됩니다. 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(에이전트 호스트, 에이전트가 상주할 터미널 창 제공; brew install herdr로 설치, 프로젝트 홈페이지 https://github.com/herdrdev/herdr), 그리고 최소 하나의 코딩 에이전트 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 <서브명령>이 항상 작동합니다(아래에서는 tut로 표기).

워크스페이스 시작 (전원 스위치, 멱등성 — 두 개의 시스템 창: 허브 창 + 알림 창):

tut up

태스크 시작 (한 문장 요구사항을 아키텍트 창으로 전송; 그런 다음 tut list를 폴링하여 태스크가 나타날 때까지 대기):

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

그런 다음 에이전트는 자체 창에서 MCP 도구를 통해 허브를 읽고 쓰면서 태스크를 진행합니다; tut status는 개요를 보여주고, Notifier는 승인이 필요할 때 알리며, tut decide <task_id> --decision approve --by <your-name>으로 결정을 내립니다.

Notifier의 사이드 채널(즉시 차단 알림, 완료 교차 확인)은 Herdr가 각 창의 에이전트 상태 변경을 scripts/on-agent-event.sh로 전달하는 것에 의존합니다 — 일회성 환경 설정(Herdr 플러그인); 배선 지침은 design/system-design.md의 섹션 7.2를 참조하세요.

에이전트 CLI 온보딩 (일회성)

허브는 Streamable HTTP를 통해 http://127.0.0.1:3001/mcp에서 MCP 도구를 노출합니다(tut serve가 실행되는 즉시 온라인; 상태 비저장, 세션 스트림 없음). 참여할 모든 에이전트 CLI에 대해 한 번 구성:

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 도구에 일대일로 매핑되므로, 에이전트는 셸에서 간단히 호출할 수 있습니다(스킬의 역할별 "도구 치트 시트" — MCP | CLI 매핑 — 은 정확히 이러한 CLI를 위해 만들어졌습니다; 두 채널을 혼합할 수 있습니다; 동일한 태스크에서 각 역할이 자체 채널을 사용하는 것은 완전히 호환됩니다).

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 서브명령은 이에 일대일로 매핑됩니다.

일반적인 워크플로우

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는 여전히 인간의 게이트

구성

세 가지 구성 표면, 성격과 위치가 다름:

① 프로젝트 런타임 구성 — .context-hub/config.json (gitignored, 프로젝트당 하나)

허브 및 Notifier 동작을 제어합니다. 변경 사항은 다음 폴링 주기에 적용됩니다 — 재시작 불필요:

② 워크스페이스 구성 — scripts/workspace.json (리포지토리와 함께 제공)

기본 라인업: 역할 → { label, 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/에 있습니다 (아키텍트 / 실행자 / 리뷰어 / 호스트 — 동작 템플릿이지 신원 바인딩이 아닙니다: 이를 로드하는 모든 에이전트가 해당 종류의 작업을 수행할 수 있습니다).

문서

• 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