OMX - Team Orchestration

시리즈: oh-my-codex 아키텍처 해부

이 시리즈는 OpenAI Codex CLI 확장 런타임인 oh-my-codex(OMX)의 내부 구조를 단계별로 해부하는 과정이다.

편	내용	핵심
0편	Overview	3-Plane 아키텍처, OMC와의 차이, 전체 흐름
1편	Codex CLI Foundation	Codex CLI 자체의 구조와 확장 포인트
2편	OMX Integration	OMX가 Codex에 어떻게 연결되나
3편	Skill System	워크플로우를 어떻게 정의하나
4편	Prompt & Agent System	에이전트는 뭐고 어떻게 선택되나
5편	MCP Servers	어떤 MCP 도구를 쓸 수 있나
6편	State & Lifecycle	상태를 어떻게 유지하나
7편 (본문)	Team Orchestration	Team 모드는 어떻게 동작하나
8편	Native & Spark	Rust 네이티브 도구는 뭔가

---

• Team Orchestration은 N개의 독립 Codex CLI 프로세스를 tmux pane에 스폰하여 공유 task list 기반으로 병렬 작업을 수행하는 멀티 워커 오케스트레이션 시스템
• orchestrator.ts가 5-Phase 파이프라인(plan → prd → exec → verify → fix)을 제어하고, runtime.ts(3,375줄)가 워커 생성·모니터링·셧다운의 전체 라이프사이클을 관리하는 OMX의 최상위 병렬 실행 엔진
• 파일 기반 통신(inbox/mailbox)과 MCP 상태 공유로 워커 간 조율을 수행하며, Git worktree로 각 워커의 코드 변경을 격리하는 프로세스 수준 격리 아키텍처

해당 개념이 필요한 이유

• 6편에서 모드 상태 관리와 배타적/합성 규칙을 다뤘지만, **“team 모드가 합성(composable)인 이유와 내부 동작”**이 빠져 있음
• 3편의 ultrawork(프로세스 내 병렬)과 달리, team은 완전 격리된 N개 프로세스로 병렬 작업을 수행 — 왜 이 구분이 필요한지, 어떻게 조율하는지를 다룸
• Ralph + Team 연계 패턴(omx team ralph ...)은 OMX의 가장 고도화된 워크플로우 — 검증 루프와 병렬 실행의 결합

AS-IS (단일 프로세스 위임 — Ultrawork)

sequenceDiagram
    autonumber
    participant U as User
    participant CX as Codex CLI (단일 프로세스)
    participant W1 as Worker 1 (인프로세스)
    participant W2 as Worker 2 (인프로세스)

    U->>CX: "$ultrawork refactor API"
    CX->>W1: 위임 (같은 프로세스 내)
    CX->>W2: 위임 (같은 프로세스 내)
    W1-->>CX: 결과 반환
    W2-->>CX: 결과 반환
    CX-->>U: 최종 결과
    Note over CX,W2: 공유 컨텍스트 — Worker 크래시 시 전체 영향

TO-BE (프로세스 격리 — Team)

sequenceDiagram
    autonumber
    participant U as User
    participant RT as TeamRuntime (Leader)
    participant T as tmux session
    participant W1 as Worker 1 (독립 Codex CLI)
    participant W2 as Worker 2 (독립 Codex CLI)
    participant ST as .omx/state/team/

    U->>RT: "omx team 2:executor refactor API"
    RT->>T: tmux session 생성
    RT->>ST: config.json, manifest 기록
    T->>W1: pane 0 — codex CLI 스폰
    T->>W2: pane 1 — codex CLI 스폰
    W1->>ST: worker/w1/status.json 업데이트
    W2->>ST: worker/w2/status.json 업데이트
    RT->>ST: 진행 상태 모니터링
    W1-->>ST: task 완료 기록
    W2-->>ST: task 완료 기록
    RT->>RT: team-verify 페이즈
    RT-->>U: 완료 보고
    Note over W1,W2: 완전 격리 — Worker 크래시가 다른 Worker에 영향 없음

Team Pipeline 5-Phase (소스: src/team/orchestrator.ts)

Phase 정의

export type TeamPhase =
  | 'team-plan'     // 작업 분해 + 서브태스크 생성
  | 'team-prd'      // PRD + test-spec 산출물 생성
  | 'team-exec'     // Worker 병렬 실행
  | 'team-verify'   // 결과 검증
  | 'team-fix';     // 검증 실패 시 수정 루프

터미널 상태: complete, failed, cancelled

Phase 전이 규칙

stateDiagram-v2
    [*] --> team_plan: omx team 시작

    team_plan --> team_prd: 태스크 분해 완료
    team_prd --> team_exec: PRD + test-spec 생성 완료
    team_exec --> team_verify: 모든 Worker 작업 완료
    team_verify --> complete: 검증 통과
    team_verify --> team_fix: 검증 실패
    team_fix --> team_verify: 수정 완료, 재검증

    team_plan --> failed: 에러
    team_prd --> failed: 에러
    team_exec --> failed: 에러
    team_verify --> failed: 에러
    team_fix --> failed: 에러

    team_plan --> cancelled: 사용자 취소
    team_exec --> cancelled: 사용자 취소

    complete --> [*]
    failed --> [*]
    cancelled --> [*]

Phase별 에이전트 매핑

orchestrator.ts에서 각 phase에 적합한 에이전트를 라우팅한다:

Phase	에이전트	역할
team-plan	architect	태스크 분해, 서브태스크 정의
team-prd	architect	PRD, test-spec 문서 생성
team-exec	executor (기본)	실제 코드 작업 수행
team-verify	tester / verifier	결과물 검증, 테스트 실행
team-fix	executor	검증 실패 항목 수정

Worker 라이프사이클 (소스: src/team/runtime.ts)

runtime.ts — 3,375줄의 핵심 엔진

runtime.ts는 Team 모드의 메인 오케스트레이션 루프를 구현한다. 핵심 함수 3개:

함수	역할
startTeam()	tmux session 생성, Worker 스폰, task 분배 시작
monitorTeam()	주기적으로 Worker 상태 확인, 완료/실패 감지
shutdownTeam()	모든 Worker 종료, tmux session 정리, 상태 기록

Worker 상태 프로토콜

각 Worker는 파일 기반 상태 머신을 통해 라이프사이클을 관리한다:

stateDiagram-v2
    [*] --> spawned: tmux pane 생성

    spawned --> ack: Worker 부트스트랩 완료, ACK 전송
    ack --> idle: Leader가 ACK 확인
    idle --> claimed: task 할당 수락
    claimed --> executing: 작업 시작
    executing --> complete: 작업 완료
    complete --> idle: 다음 task 대기
    idle --> shutdown: 모든 task 완료 또는 Leader 지시

    executing --> failed: 에러 발생
    failed --> idle: 재시도 가능 시

    shutdown --> [*]

ACK 메커니즘: Worker가 스폰된 후 부트스트랩을 완료하면 worker/{id}/status.json에 ACK를 기록한다. Leader(runtime.ts)는 이 ACK를 확인한 후에만 task를 분배한다. 타임아웃 내에 ACK가 없으면 Worker를 실패로 처리한다.

Worker Bootstrap (소스: src/team/worker-bootstrap.ts)

부트스트랩 과정

Worker가 tmux pane에서 시작될 때 수행되는 초기화 단계:

1. AGENTS.md 오버레이 주입 — Leader의 AGENTS.md에 Team 전용 지침을 추가하여 Worker의 AGENTS.md로 주입
2. 역할 프롬프트 로딩 — role-router.ts가 Worker 역할에 맞는 프롬프트(prompts/*.md)를 선택
3. 모델/플래그 설정 — model-contract.ts의 해석 결과에 따라 --model, --full-auto 등 플래그 설정
4. inbox 생성 — worker/{id}/inbox/ 디렉토리에 초기 task 파일 배치

inbox 기반 task 분배

.omx/state/team/worker/{worker-id}/
├── identity.json      # Worker 식별 정보 (role, model, spawn 시각)
├── heartbeat.json     # 주기적 생존 신호
├── status.json        # 현재 상태 (idle, executing, complete 등)
└── inbox/             # Leader가 task를 넣으면 Worker가 가져감
    ├── task-001.json
    └── task-002.json

Worker는 inbox/ 디렉토리를 폴링하여 새 task를 감지하고, claim → execute → complete 순서로 처리한다.

파일 기반 통신 (소스: src/team/mcp-comm.ts)

Worker 간 조율 메커니즘

Team 모드의 통신은 MCP 서버가 아닌 파일 시스템 기반 메시징이다:

채널	방향	용도
inbox/	Leader → Worker	task 분배, 지시 전달
mailbox/	Worker → Leader	완료 보고, 결과 반환
status.json	Worker → Leader	상태 업데이트 (폴링)
heartbeat.json	Worker → Leader	생존 신호

dispatch 함수

mcp-comm.ts의 dispatch()는 Leader가 Worker에게 task를 전달하는 핵심 함수다:

// 1. task JSON을 worker/{id}/inbox/task-{n}.json에 기록
// 2. Worker가 폴링으로 감지
// 3. Worker가 claim하면 status.json을 "claimed"로 변경
// 4. 완료 시 mailbox/에 결과 기록

이 설계는 MCP 서버 의존 없이 순수 파일 I/O만으로 프로세스 간 통신을 구현한다. 단순하지만 tmux pane 간 격리를 유지하면서도 안정적인 조율이 가능하다.

Model Contract (소스: src/team/model-contract.ts)

Worker 모델 해석 우선순위

Worker가 사용할 LLM 모델은 3단계 우선순위로 결정된다:

순위	소스	환경 변수	예시
1	명시적 launch 인자	OMX_TEAM_WORKER_LAUNCH_ARGS	--model o3
2	Leader에서 상속	--model (Leader 실행 시)	Leader가 o3이면 Worker도 o3
3	기본 Spark 모델	OMX_DEFAULT_SPARK_MODEL	o4-mini 등

Leader / Worker 모델 분리

역할	환경 변수	의미
Leader (계획·검증)	OMX_DEFAULT_FRONTIER_MODEL	높은 추론 능력이 필요한 작업
Worker (실행)	OMX_DEFAULT_SPARK_MODEL	빠르고 비용 효율적인 코드 생성

resolveTeamWorkerLaunchArgs()가 위 우선순위를 적용하여 Worker CLI 인자를 결정한다. resolveTeamLowComplexityDefaultModel()은 단순 작업에 더 가벼운 모델을 선택한다.

Team 상태 구조 (소스: src/team/state.ts)

.omx/state/team/ 전체 맵

.omx/state/team/
├── config.json              # TeamConfig — 이름, Worker 수, 거버넌스, 정책
├── manifest-{timestamp}.json # TeamManifest — Worker 목록, 역할, 모델 정보
├── worker/
│   └── {worker-id}/
│       ├── identity.json    # 역할, 모델, 스폰 시각
│       ├── heartbeat.json   # 마지막 활동 시각, 응답 여부
│       ├── status.json      # 현재 상태 + 현재 task 정보
│       └── inbox/           # 대기 중인 task 파일들
├── tasks/
│   └── {task-id}.json       # TaskDefinition — 설명, 의존성, 할당 Worker
├── phase/
│   └── current.json         # 현재 pipeline phase + 메타데이터
├── events/
│   └── event-{timestamp}.jsonl  # Team 이벤트 로그
└── shutdown/
    └── signal.json          # 셧다운 조율 (graceful shutdown 신호)

핵심 인터페이스

interface TeamConfig {
  name: string;
  workerCount: number;
  governance: string;        // 'leader-driven' | 'consensus'
  policy: AllocationPolicy;  // task 할당 전략
}
 
interface WorkerInfo {
  id: string;
  role: string;              // 'executor', 'tester' 등
  model: string;             // 해석된 모델명
  tmuxPane: string;          // tmux pane 식별자
  status: WorkerStatus;
  currentTask?: string;
}
 
interface TeamTask {
  id: string;
  description: string;
  dependencies: string[];    // 선행 task ID 목록
  assignedWorker?: string;
  status: 'pending' | 'claimed' | 'executing' | 'complete' | 'failed';
}

Role Router (소스: src/team/role-router.ts)

Task를 Worker에게 분배할 때, role-router.ts가 키워드 휴리스틱으로 적합한 역할을 결정한다:

키워드 패턴	라우팅 역할	근거
test, spec, coverage	tester	테스트 관련 작업
refactor, implement, build	executor	구현 작업
design, plan, architecture	architect	설계 작업
review, verify, check	verifier	검증 작업

CLI에서 omx team 3:executor "..." 처럼 역할을 명시하면 라우터를 우회하고 해당 역할로 직접 배정된다.

Worker CLI 선택과 Git Worktree 격리

Worker CLI 선택

// OMX_TEAM_WORKER_CLI 환경 변수
// 'codex' — Codex CLI (기본)
// 'claude' — Claude Code CLI
// 'auto'  — 상황에 따라 자동 선택

Worker는 반드시 Codex CLI일 필요가 없다. OMX_TEAM_WORKER_CLI=claude로 설정하면 Claude Code를 Worker로 사용할 수 있다.

Git Worktree 격리 (소스: src/team/worktree.ts)

각 Worker가 같은 파일을 동시에 수정하면 충돌이 발생한다. worktree.ts가 Worker별 독립 Git worktree를 생성하여 이를 방지한다:

project/                    # 메인 리포지토리 (Leader)
project-worker-1/           # Worker 1의 worktree (독립 브랜치)
project-worker-2/           # Worker 2의 worktree (독립 브랜치)

• 각 Worker는 자신만의 작업 디렉토리와 브랜치에서 작업
• 완료 후 Leader가 merge 또는 cherry-pick으로 통합
• 브랜치 보존 정책: Ralph + Team 연계 시 검증 실패한 브랜치도 보존

4가지 병렬 패턴 비교

항목	Ultrawork	Team	Autopilot	Ralph
격리 수준	공유 컨텍스트 (인프로세스)	완전 격리 (독립 프로세스)	단계별 격리	루프별 격리
Worker 실행	같은 Codex 프로세스 내	독립 tmux pane	혼합	ultrawork 내부 위임
통신	직접 결과 반환	파일 기반 (inbox/mailbox)	직접 + MCP	직접 + architect 검증
확장성	프로세스 내 한계	N Worker 수평 확장	5단계 순차, 단계 내 병렬	while(!verified) 루프
상태 관리	모드 상태만	.omx/state/team/ 전체	모드 상태	Ralph phase contract
적합 작업	단일 작업의 병렬 분해	대규모 멀티태스크	전체 자동화 파이프라인	품질 보증이 필요한 작업

Ralph + Team 연계

omx team ralph ... — 검증 루프 + 병렬 실행의 결합

sequenceDiagram
    autonumber
    participant U as User
    participant RL as Ralph (검증 루프)
    participant TM as Team Runtime
    participant W1 as Worker 1
    participant W2 as Worker 2

    U->>RL: "omx team ralph 2:executor build API"
    RL->>RL: Planning Gate 확인 (PRD + test-spec, 6편)
    RL->>TM: team-exec 위임
    TM->>W1: 서브태스크 1 분배
    TM->>W2: 서브태스크 2 분배
    W1-->>TM: 완료
    W2-->>TM: 완료
    TM-->>RL: team-exec 완료
    RL->>RL: team-verify (검증)
    alt 검증 실패
        RL->>TM: team-fix 위임
        TM->>W1: 수정 작업 분배
        W1-->>TM: 수정 완료
        TM-->>RL: team-fix 완료
        RL->>RL: 재검증 (루프)
    else 검증 통과
        RL-->>U: 완료
    end

linked team cleanup policy

Ralph가 Team을 감싸는 경우, Ralph의 종료(complete/cancelled) 시 Team 리소스도 함께 정리된다:

• tmux session 종료
• Worker worktree 정리 (merge 완료된 것만)
• 검증 실패 브랜치는 보존 (디버깅용)

추천 워크플로우: High-Control 체인

ralplan (스펙 생성) → team (병렬 실행) → ralph (지속 검증)

ralplan으로 PRD + test-spec을 먼저 생성하여 Planning Gate를 통과시킨 후, Team 모드로 N Worker 병렬 실행, Ralph 루프로 결과를 지속 검증하는 패턴이다. 계획 통제를 유지하면서 Worker 병렬성을 최대한 활용하는 OMX의 가장 고도화된 워크플로우다.

Dynamic Scaling과 Idle Nudge

동적 스케일링 (소스: src/team/scaling.ts)

Worker 수를 런타임에 동적으로 조절하는 기능이다. 현재 환경 변수 게이트 뒤에 숨겨져 있다:

// OMX_TEAM_DYNAMIC_SCALING=true 일 때만 활성화
// - 남은 task 대비 idle Worker 비율 계산
// - 필요 시 Worker 추가 스폰 또는 idle Worker 셧다운

Idle Nudge (소스: src/team/idle-nudge.ts)

Worker가 일정 시간 이상 idle 상태를 유지하면, Leader가 nudge 메시지를 inbox에 넣어 Worker의 활동을 촉구한다. OMC에는 없는 OMX 고유 기능이다.

HUD — Team 모니터링 대시보드

src/hud/ 디렉토리가 Team 실행 상태를 실시간으로 표시하는 대시보드를 제공한다:

• Worker별 현재 상태, 진행 중인 task
• Phase 진행률
• 토큰 사용량, 경과 시간
• sparkshell(8편)과 연동하여 터미널 기반 모니터링 제공

CLI 인터페이스 (소스: src/cli/team.ts)

명령어	동작
omx team <count>:<role> "<task>"	Team 모드 시작 (Worker 수, 역할, 작업 지정)
omx team status	현재 Team 상태 조회
omx team resume	중단된 Team 재개
omx team shutdown	모든 Worker 종료 (graceful)

omx team shutdown은 shutdown/signal.json에 신호를 기록하고, 각 Worker가 현재 작업을 마친 후 순차적으로 종료한다.

OMC Team과의 비교

항목	OMC Team	OMX Team
Worker 생성	tmux + claude CLI 스폰	tmux + codex CLI 스폰 (또는 claude)
작업 분배	공유 task list	파일 기반 inbox/mailbox
통신	shared-memory MCP	파일 I/O + MCP 상태 공유
CLI 제어	Skill 내부 지시	omx team 독립 CLI 서브커맨드
Worker 수 조절	수동	scaling.ts 동적 스케일링 (게이트)
후속 계획	없음	followup-planner.ts
Idle 처리	없음	idle-nudge.ts
Git 격리	없음	worktree.ts Git worktree
Phase 관리	없음	5-Phase 파이프라인 + 상태 머신
모델 계약	없음	model-contract.ts (Leader/Worker 분리)

핵심 차이: OMC는 Team을 Skill 내부 지시로 구동하지만, OMX는 독립 CLI + 5-Phase 파이프라인 + 파일 기반 통신으로 구조화된 오케스트레이션을 제공한다. 특히 Git worktree 격리, dynamic scaling, idle nudge, followup planner 등 OMC에 없는 인프라가 추가되어 있다.

참고 문서

• OMX GitHub