cmux-ai-run

/cmux-ai-run — cmux 창 분할 병렬 AI 실행

multi-ai-run과의 차이: Bash 서브프로세스(순차) 대신 cmux 패널 분할(진짜 병렬).

두 가지 실행 모드:

• 기본 모드: Background Agent(코디네이터)가 CLI 호출 + tail -f 로그 스트리밍. SendMessage 완료 감지.
• --live-mode: Claude가 cmux 명령어로 패널을 직접 제어. CLI 전송 → Read 결과 확인 → 에러 시 즉시 대응.

---

패널 레이아웃

┌─────────────────────┬──────────────────────────┐
│  Claude             │  codex-runner 로그        │
│  (현재 패널)        │  $ tail -f codex.log      │
│  오케스트레이터     │  [진행 상황 실시간 표시]   │
│                     ├──────────────────────────┤
│                     │  gemini-runner 로그       │
│                     │  $ tail -f gemini.log     │
│                     │  [진행 상황 실시간 표시]   │
└─────────────────────┴──────────────────────────┘

---

Prerequisites

cmux ping || { echo "cmux 필요"; exit 1; }
# 모델 설정 확인 (프로젝트 오버라이드 우선)
CONFIG="${PROJECT_ROOT}/.claude/cmux-ai-models.yaml"
[ ! -f "$CONFIG" ] && CONFIG="${CLAUDE_PLUGIN_ROOT}/skills/cmux-ai-run/config/models.yaml"

---

모델 설정

기본값 (config/models.yaml):

• Codex: gpt-5.4, effort=high
• Gemini: gemini-3-flash-preview
• Claude: opus

프로젝트별 오버라이드: .claude/cmux-ai-models.yaml 생성 (동일 형식)

---

실행 순서

Step 1: 태스크 분석 + 라우팅

TASKS.md 또는 명시된 태스크를 분석해 AI별로 그룹화:

codex_tasks: [코드 생성, 리팩토링, 테스트 작성, API 구현]
gemini_tasks: [UI 컴포넌트, 디자인 구현, 스타일링]
claude_tasks: [아키텍처 결정, 플래닝, 복잡한 추론]

라우팅 기준은 config/models.yaml의 routing 섹션 참조. 태스크에 [model:gemini] 태그가 있으면 강제 라우팅.

Step 2: 로그 파일 + Agent Teams 세션 + cmux 패널 생성

# 로그 파일 먼저 생성 (tail -f가 즉시 열 수 있도록)
mkdir -p .claude/cmux-ai/runs
touch .claude/cmux-ai/runs/codex-runner.log
touch .claude/cmux-ai/runs/gemini-runner.log

# Agent Teams 세션 생성
TeamCreate(name="cmux-ai-run-{project}-{timestamp}", description="Parallel AI task execution")
TaskCreate(team_name=..., subject="codex-tasks", description="{codex_tasks_list}")
TaskCreate(team_name=..., subject="gemini-tasks", description="{gemini_tasks_list}")

# cmux 패널 생성 + 즉시 tail -f 실행
CODEX_SURFACE=$(cmux new-split right 2>&1 | awk '{print $2}')
GEMINI_SURFACE=$(cmux new-split down --surface $CODEX_SURFACE 2>&1 | awk '{print $2}')

# 패널에 로그 스트리밍 시작 (에이전트 작업이 보임)
cmux send --surface $CODEX_SURFACE \
  "tail -f .claude/cmux-ai/runs/codex-runner.log
"
cmux send --surface $GEMINI_SURFACE \
  "tail -f .claude/cmux-ai/runs/gemini-runner.log
"

cmux set-status "codex" "running" --icon gear --color "#007aff"
cmux set-status "gemini" "running" --icon brush --color "#5856d6"
cmux set-progress 0.2 --label "Agents starting..."

Step 3: 병렬 에이전트 실행

각 에이전트(Claude 서브에이전트)는 코디네이터로서 실제 AI CLI를 호출하고, 진행 로그를 기록하며, 완료 시 SendMessage로 보고:

Agent(
  subagent_type="builder",
  team_name="cmux-ai-run-{project}-{timestamp}",
  name="codex-runner",
  run_in_background=true,
  prompt="""
    너는 Codex CLI 코디네이터다. 직접 코드를 작성하지 말고,
    실제 codex CLI를 호출해서 작업을 수행하라.

    ## 수행할 태스크
    {codex_tasks_list}

    ## 실행 방법
    각 태스크마다:
    1. 프롬프트 파일 작성:
       Write("{task_prompt}") > .claude/cmux-ai/runs/codex-task-{N}.md
    2. 로그 기록:
       Bash: echo "[$(date +%H:%M:%S)] ▶ {task 이름} — codex exec 실행" >> .claude/cmux-ai/runs/codex-runner.log
    3. codex CLI 호출:
       Bash: codex exec "$(cat .claude/cmux-ai/runs/codex-task-{N}.md)" 2>&1
    4. 결과 확인 후 로그:
       Bash: echo "[$(date +%H:%M:%S)] ✅ {task 이름} done" >> .claude/cmux-ai/runs/codex-runner.log
    5. 에러 시:
       Bash: echo "[$(date +%H:%M:%S)] ⚠️  {에러 내용}" >> .claude/cmux-ai/runs/codex-runner.log

    ## 완료 후
    Bash: echo "[$(date +%H:%M:%S)] ━━━━━━━━━━━━━━━━━━━━━━━━━" >> .claude/cmux-ai/runs/codex-runner.log
    Bash: echo "[$(date +%H:%M:%S)] 🏁 codex-runner ALL DONE" >> .claude/cmux-ai/runs/codex-runner.log
    SendMessage(
      to="team-lead",
      message="{결과 전체 요약}",
      summary="codex-runner: DONE — {완료된 태스크 수}개 완료"
    )

    ## Fallback
    codex CLI 실행 실패 시 → Claude가 직접 해당 태스크 수행 후 로그에 "[FALLBACK] Claude 직접 처리" 기록.
  """
)

Agent(
  subagent_type="builder",
  team_name="cmux-ai-run-{project}-{timestamp}",
  name="gemini-runner",
  run_in_background=true,
  prompt="""
    너는 Gemini CLI 코디네이터다. 직접 작업하지 말고,
    실제 gemini CLI를 호출해서 작업을 수행하라.

    ## 수행할 태스크
    {gemini_tasks_list}

    ## 실행 방법
    각 태스크마다:
    1. 프롬프트 파일 작성:
       Write("{task_prompt}") > .claude/cmux-ai/runs/gemini-task-{N}.md
    2. 로그 기록:
       Bash: echo "[$(date +%H:%M:%S)] ▶ {task 이름} — gemini -y -p 실행" >> .claude/cmux-ai/runs/gemini-runner.log
    3. gemini CLI 호출:
       Bash: gemini -y -p "$(cat .claude/cmux-ai/runs/gemini-task-{N}.md)" 2>&1
    4. 결과 확인 후 로그:
       Bash: echo "[$(date +%H:%M:%S)] ✅ {task 이름} done" >> .claude/cmux-ai/runs/gemini-runner.log
    5. 에러 시:
       Bash: echo "[$(date +%H:%M:%S)] ⚠️  {에러 내용}" >> .claude/cmux-ai/runs/gemini-runner.log

    ## 완료 후
    Bash: echo "[$(date +%H:%M:%S)] ━━━━━━━━━━━━━━━━━━━━━━━━━" >> .claude/cmux-ai/runs/gemini-runner.log
    Bash: echo "[$(date +%H:%M:%S)] 🏁 gemini-runner ALL DONE" >> .claude/cmux-ai/runs/gemini-runner.log
    SendMessage(
      to="team-lead",
      message="{결과 전체 요약}",
      summary="gemini-runner: DONE — {완료된 태스크 수}개 완료"
    )

    ## Fallback
    gemini CLI 실행 실패 시 → Claude가 직접 해당 태스크 수행 후 로그에 "[FALLBACK] Claude 직접 처리" 기록.
  """
)

cmux set-progress 0.4 --label "Agents running (see panels)..."

Step 4: 완료 대기 (이벤트 기반)

메인 Claude는 두 에이전트의 SendMessage 수신 대기. 수신 시 패널의 로그에도 완료가 표시되어 있음.

cmux set-progress 0.7 --label "Waiting for agents..."

Step 5: 결과 통합 + 충돌 해결

두 SendMessage 수신 후 결과를 검토하고 프로젝트에 반영:

• 파일 충돌: 같은 파일 수정 시 Claude가 중재
• 품질 검증: lint, type-check, test 실행
• 적용: Edit/Write 도구로 프로젝트에 반영

cmux set-progress 0.9 --label "Integrating results..."
# ... Claude가 결과 통합 ...
cmux set-progress 1.0 --label "Done"
cmux log --level success -- "cmux-ai-run: All tasks complete"
cmux notify --title "cmux-ai-run Complete" --body "All agents finished"
cmux clear-status "codex"
cmux clear-status "gemini"

---

태스크 태그 (TASKS.md에서 사용)

- [ ] T1.1: Implement auth API [model:codex]
- [ ] T1.2: Create login UI component [model:gemini]
- [ ] T1.3: Design system architecture [model:claude]
- [ ] T1.4: Write integration tests  # 태그 없으면 routing 설정 기준 자동 배정

---

Fallback

상황	동작
codex CLI 없음	Claude가 직접 처리
gemini CLI 없음	Claude가 직접 처리
cmux 없음	/multi-ai-run 사용 권장
Agent 무응답 (5분)	Claude가 직접 해당 태스크 수행

---

아키텍처 요약

메인 Claude (오케스트레이터)
├── 로그 파일 생성 → cmux 패널에서 tail -f (실시간 가시화)
├── TeamCreate → 통신 채널 수립
├── Agent(codex-runner, bg) = Claude 코디네이터
│   └── codex exec "task prompt" → 진짜 Codex가 코드 작업
│   └── 로그 기록 → SendMessage(summary="DONE")
├── Agent(gemini-runner, bg) = Claude 코디네이터
│   └── gemini -y -p "task prompt" → 진짜 Gemini가 디자인 작업
│   └── 로그 기록 → SendMessage(summary="DONE")
└── SendMessage 수신 → 결과 통합 (이벤트 기반)

---

--live-mode

Claude가 cmux 패널에서 CLI를 인터랙티브 세션으로 띄우고, 프롬프트를 주입한 뒤, cmux wait-for 시그널로 완료를 감지한다. Agent/SendMessage 없이 Claude가 cmux 명령어로 직접 오케스트레이션. 패널에서 에이전트가 작업하는 모습이 실시간으로 보인다.

상세 실행 순서, CLI별 옵션, 시그널 컨벤션은 references/live-mode.md 참조.

---

설정 파일 우선순위

1. .claude/cmux-ai-models.yaml (프로젝트)
2. config/models.yaml (스킬 기본값)