오케스트레이션

코딩 에이전트 하나가 다른 Claude Code와 Codex 세션에게 일을 나눠 맡기고, 끝나기를 기다렸다가 결과를 읽습니다. 워커마다 tmux 창이 따로 있어서 데스크탑 앱, 폰, 브라우저에서 하나하나 지켜볼 수 있습니다.

에이전트 하나가 코디네이터가 되어 다른 에이전트들에게 일을 나눠 맡깁니다. 워커는 하나하나가 실제 동작하는 Claude Code나 Codex 세션이고, 각자의 tmux 창에서 실행됩니다. 그래서 다른 창과 똑같이 데스크탑 앱, 폰 앱, 브라우저에서 워커를 들여다보고 끼어들 수 있습니다. 사람은 보통 한 번 부탁하고, 명령은 코디네이터가 실행합니다.

위 그림은 예시 실행입니다. 한 장치의 코디네이터 아래에 워커 둘이 있고, 계정의 다른 장치에 워커가 하나 더 있습니다. 선을 누르면 그 선을 따라 주고받은 기록이, 카드를 누르면 그 워커의 터미널이 보입니다. 실행은 대화하던 에이전트에게 부탁해서 시작합니다. 예: /sophonz:orchestrate 테스트는 Codex, README는 Claude에게. 워커는 같은 계정의 다른 장치에서 실행할 수도 있습니다. 시뮬레이터가 설치된 Mac이 그 예입니다. 해당 장치에서 먼저 st orch accept-remote on으로 허용해 두면 됩니다.

기본 개념

• 실행(run): 코디네이터 하나가 맡은 일 묶음입니다. 목표, 워커, 작업이 여기에 딸립니다. st orch start로 만들고, 실행이 없으면 첫 st worker start나 st task create가 하나 만듭니다.
• 코디네이터: 일을 나눠 맡기고 결과를 확인하는 에이전트입니다. st가 공유하는 세션의 pane에서 실행되는 Claude Code나 Codex면 어느 것이든 됩니다. 코디네이터는 맨 위에 고정된 역할이 아니라 자리입니다. 코디네이터도 자기 워커를 데리고 통째로 다른 코디네이터의 워커가 될 수 있고, 그래도 누구의 대화도 사라지지 않습니다. 그러면 이름 뒤에 team of N이 붙습니다(st 0.3.88 이상).
• 워커(worker): 자기 tmux 창에서 실행되는 Claude Code나 Codex 세션입니다. 코디네이터가 st worker start로 새로 띄우거나, 이미 실행 중이던 에이전트를 워커로 데려옵니다. 일을 마치면 st worker done으로 보고합니다.
• 작업(task): st가 기억하는 이름 붙은 일입니다. 다른 작업이 끝나기를 기다리게 할 수 있고(st task create --deps), 기다리던 작업이 끝나면 워커가 맡습니다.
• 결정 게이트: 사람만 답해야 하는 질문입니다. 폰, 데스크탑 앱, 웹 터미널 가운데 한 곳에서 답할 때까지 에이전트가 멈춥니다.
• worktree: 워커에게만 주는 git worktree와 브랜치입니다(--worktree). 파일, 빌드, 테스트가 다른 워커와 섞이지 않습니다.
• 팀: 워커를 데리고 일하던 코디네이터가 다른 코디네이터의 워커로 들어가면, 그 코디네이터와 워커들이 팀이 됩니다. 팀을 미리 만드는 방법은 없습니다. 코디네이터는 데려와지는 순간 팀장이 되고, 그때부터 team of N 표시가 붙습니다. 팀장은 자기 실행을 그대로 갖고 팀 전체의 결과를 모아 한 번 보고하며, 팀 안의 깊이는 팀장부터 다시 셉니다(st 0.3.88 이상). 팀을 워커로 데려오기를 보세요.
• 서브에이전트: Claude Code가 Task 도구로 자기 안에서 띄우는 에이전트입니다. 창이 없고, st는 지켜보기만 합니다.

워커와 서브에이전트는 이렇게 다릅니다.

계층으로 보면 이렇습니다. st가 관리하는 것은 tmux 창(코디네이터와 워커)이고, 서브에이전트는 그것을 띄운 에이전트가 관리합니다.

배지는 그것을 관리하는 쪽입니다. 창은 모두 st, 서브에이전트는 그것이 실행되는 에이전트입니다.

• 깊이는 두 가지로 셉니다(st 0.3.88 이상).

  • 한 실행(팀) 안에서는 그 실행의 코디네이터 아래 두 단계까지입니다.
  • 팀이 팀을 받아 이어진 전체 사슬은 맨 위 코디네이터부터 가장 아래 워커까지 네 단계까지입니다. 다른 장치를 거쳐도 같습니다.

  데려온 팀은 자기 실행을 그대로 가지고 팀장부터 다시 세기 때문에, 팀을 데려오면 전체가 두 단계보다 깊어질 수 있습니다. st 0.3.87 이하는 팀까지 모두 맨 위 코디네이터 아래 두 단계로 셌습니다.

• 에이전트 그래프에서 서브에이전트는 자기 에이전트 카드 아래에 가는 선으로 이어집니다. Codex에는 서브에이전트가 없습니다.

st가 하는 일

• 워커는 st가 여는 tmux 창입니다. st worker start는 코디네이터의 세션에 워커 이름으로 새 창을 열고, 코디네이터 pane의 폴더에서 claude나 codex를 띄웁니다. 워커를 보세요.
• 과제는 st가 입력합니다. 에이전트의 입력창이 뜨면 st가 "과제는 이 파일에 있으니 읽고 하라"는 한 줄을 칩니다. 권한 질문 같은 다른 화면 위에는 치지 않고, 그 줄이 실제로 들어갔는지 확인합니다.
• 시작은 훅으로 확인합니다. st worker start는 에이전트 훅으로 워커가 턴을 시작한 것을 확인한 뒤에야 돌아옵니다. st worker wait도 같은 훅으로 워커가 일하는 중인지, 입력을 기다리는지, 끝났는지 압니다.
• 관계는 st를 다시 시작해도 남습니다. 누가 누구에게 일을 맡겼는지는 st를 다시 시작해도 그대로 있고, pane을 닫으면 함께 사라집니다. 실행의 목표와 워커의 보고는 ~/.sophonz/orch/<실행>/run.json에 남습니다.
• 관계는 에이전트를 따라갑니다. tmux 서버가 내려갔다가 st가 세션을 되살리면 pane은 새 id로 돌아옵니다. st 0.3.88부터는 st가 10초쯤 안에 코디네이터와 워커를 다시 찾아 관계를 되돌려 놓습니다. 에이전트가 실수로 tmux를 멈추는 명령은 훅이 거절합니다. tmux 재시작 뒤를 보세요.
• 워커는 보고합니다. 일을 마친 워커는 st worker done --summary "<한 일과 확인한 방법>"을 실행하고, 코디네이터는 st worker read로 그 요약과 워커의 마지막 답을 읽습니다. st도 코디네이터에게 알립니다. 코디네이터의 턴 사이에, 워커가 끝났다는 것과 읽는 방법을 담은 한 줄이 그 pane에 입력됩니다(st 0.3.92 이상).

준비

tmux(Windows에서는 psmux, 아래 참고), 실행 중인 st 0.3.67 이상, 에이전트 훅이 필요합니다.

st hooks install      # 먼저. 워커가 일을 시작했는지 st가 훅으로 확인합니다
st plugin install     # Claude Code 플러그인과 Codex 스킬

설치하면 새로 연 Claude Code 세션에 /sophonz:orchestrate가 생기고, Codex에는 sophonz-orchestrate와 sophonz-worker 스킬이 들어갑니다. 에이전트 스킬과 플러그인을 보세요.

그다음 st가 공유하는 세션의 pane에서 Claude Code를 열고 이렇게 부탁합니다.

/sophonz:orchestrate API 테스트는 Codex에게, README 정리는 다른 Claude에게 맡기고
둘 다 끝나면 결과를 확인해서 알려 줘.

그러면 코디네이터가 대략 이런 순서로 명령을 실행합니다.

st orch start --objective "API 테스트 추가와 README 정리"
st worker start --agent codex  --name api-tests --task api-tests.md
st worker start --agent claude --name readme    --task readme.md
st worker wait --timeout 15m      # 둘 다 끝날 때까지
st worker read api-tests          # 워커의 마지막 답과 요약

보이는 곳

• 창 목록. 워커는 이름이 붙은 평범한 tmux 창입니다. 그래서 데스크탑 앱의 사이드바, 폰 앱의 창 목록, 웹 터미널의 창 탭에 그대로 나오고, st ls의 AGENTS 수에도 들어갑니다. 상태 점과 알림도 다른 에이전트와 같습니다. 게이트는 선택지가 버튼으로 달린 알림으로 폰에 옵니다.
• 데스크탑 앱의 에이전트 그래프. 이 컴퓨터의 세션 가운데 위임이 있는 세션이면 pane 머리에 ◇ Agents와 노드 수가 나옵니다(⇧⌘G, Windows와 Linux는 Ctrl+Alt+Shift+G). 코디네이터에서 워커마다 굵은 초록 선이 이어지고, 카드에는 코디네이터인지 워커인지와 끝난 워커의 요약이 나옵니다. 일하는 중인 카드는 테두리가 밝아지고 상태 점이 깜빡입니다. 카드를 누르면 그 pane으로 가고, 에이전트 카드를 다른 에이전트 카드에 끌어 놓으면 그 에이전트의 워커로 데려옵니다. Claude 에이전트 팀과 서브에이전트도 같은 그래프에 나옵니다. 데스크탑 앱 0.1.17 이상(데려오기는 0.1.21 이상)이 필요합니다. 데스크탑 앱을 보세요.
• 사이드바 카드. 데스크탑 앱과 웹 터미널에서는 코디네이터와 워커가 카드 하나로 묶입니다. 코디네이터 행에 coordinator 배지가 붙고, 그 아래 Workers · 2 working, 1 done 같은 머리 줄로 워커를 접고 펼칩니다(웹 터미널을 한국어로 보면 워커 · 작업 중 2, 끝남 1). 처음에는 펼쳐져 있습니다. 끝난 워커는 맨 아래 Completed (N)(끝난 워커 N명) 묶음으로 들어가고, 열기 전까지 접혀 있습니다. 다른 장치의 워커에는 장치 아이콘과 ↳ 부모 · 장치 표시가 붙습니다. 창 행을 다른 에이전트 행에 끌어 놓으면 그 에이전트의 워커로 데려오고, 행 메뉴에서 놓아 줍니다. 데스크탑 앱은 0.1.31 이상이 필요합니다. 웹 터미널에서 끌어 놓아 데려오기는 st 0.3.85 이상, 카드로 묶기는 st 0.3.86 이상이 필요합니다. 데스크탑 앱의 에이전트 데려오기를 보세요.
  • 카드는 트리로 그려집니다. 코디네이터에서 워커마다 가는 안내선이 내려갑니다. 자기 팀을 이끄는 워커는 회색이 한 단계 진한 상자로 묶이고, 그 아래에 자기 워커가 들여 나오며, 이름 뒤에 에이전트 그래프에서처럼 team of N이 붙습니다. 카드 바탕은 중립적인 회색이고, 에이전트 색은 점과 아이콘에만 남습니다. 카드 안의 행에는 에이전트 명령 이름이 나오지 않습니다.
  • 강조되는 행은 그 앱이나 그 브라우저 탭에서 앞에 띄운 창 하나뿐이고, 그 행과 그 행이 든 카드의 테두리가 더 밝아집니다. 다른 클라이언트(폰, 다른 attach)가 앞에 띄운 창은 강조되지 않습니다.
  • 코디네이터가 사라진 워커(pane이 닫혔거나, tmux가 다시 시작된 뒤 st가 아직 찾지 못한 경우)는 목록에 남고, ⚠와 사라진 코디네이터, Release가 함께 나옵니다.
  • 다른 세션의 행을 누르면 그 세션으로 갑니다. 지금 앞에 있는 세션을 누르면 그 세션이 접히고, 작은 ▾/▸는 어느 행이든 접고 폅니다.
  • 데스크탑 앱 0.1.33 이상, 웹 터미널은 st 0.3.88 이상에서 이렇게 보입니다. 팀 표시는 그 장치에 st 0.3.88 이상이 있어야 나옵니다.
• 웹 터미널. 위임이 있는 세션이면 터미널 오른쪽 위에 Agents 카드가 떠서 코디네이터와 워커를 각자의 상태와 함께 보여 줍니다. 하나를 누르면 그 창으로 갑니다(st 0.3.85 이상). 패널 머리의 ◇ Agents는 데스크탑 앱과 같은 에이전트 그래프를 열고, 그 그래프의 워커 카드에는 Release가 있습니다(st 0.3.87 이상). 둘 다 계정의 다른 장치에 있는 에이전트도 보여 주고, 누르면 그 장치에서 그 창을 엽니다(st 0.3.92 이상).
• 폰 앱. 에이전트 차트, 창 목록, 터미널의 에이전트 카드에 나옵니다. 폰에서 보기: 에이전트 차트를 보세요. 에이전트를 길게 누르면 워커로 맡기기…와 놓아 주기가 있습니다. iPhone과 Android도 보세요.

폰에서 보기: 에이전트 차트

iPhone과 Android 앱은 누가 누구에게 일을 맡겼는지를 위에서 아래로 이어지는 카드 트리로 보여 줍니다. 맨 위가 코디네이터이고 그 아래에 워커, 팀원, 서브에이전트가 들여 놓입니다. 선은 st 워커가 굵은 초록, 에이전트 팀이 파랑, 서브에이전트가 가는 회색이고, 아래쪽 에이전트가 일하는 동안만 진해집니다. 카드마다 에이전트 아이콘과 이름, 코디네이터·워커·서브에이전트·팀원 표시, 상태와 그 상태로 지난 시간이 나오고, 다른 장치의 에이전트에는 장치 아이콘과 이름이 붙습니다.

• 여는 곳. 장치 화면 상태 줄의 에이전트 N 칩(그 장치 전체), 위임이 있는 세션의 창 목록 위 워커 버튼, 터미널 메뉴의 에이전트에서 엽니다.
• 범위. 위쪽에서 이 창(터미널에서 열었을 때), 이 세션, 이 머신, 모든 머신(로그인했을 때)을 고릅니다. 다른 장치의 워커와 코디네이터는 어느 범위에서든 장치 표시와 함께 같은 트리에 들어갑니다. 위임이 없으면 "다른 에이전트에게 일을 맡긴 에이전트가 없습니다."가 나옵니다.
• 누르면. pane이 있는 카드는 그 장치의 터미널을 그 창과 pane에서 엽니다. 다른 장치에 있으면 그 장치부터 엽니다. 서브에이전트와 팀원 카드는 종류, 상태, 부모, 시작 시각, Main › 부모 › 이것 경로를 보여 줍니다.
• 터미널의 에이전트 카드. 화면에 띄운 창의 에이전트가 코디네이터나 워커면 터미널 오른쪽 위에 ⑂ N 알약이 생깁니다. 누르면 코디네이터와 워커가 나오고, 줄을 누르면 그 pane으로 갑니다. 키바는 가리지 않습니다.
• 창 목록. 코디네이터 창 카드에는 코디네이터 표시와 ⑂ 워커 N 알약이 붙고, 알약으로 그 아래의 워커를 접고 폅니다. 같은 장치의 워커는 그 아래로 들여 놓이고, 다른 세션이면 세션 이름이 함께 붙습니다.

장치의 st는 0.3.70 이상(그래프와 데려오기), 다른 장치까지 보려면 0.3.85 이상이어야 합니다. iPhone은 v0.1.93, Android는 v0.1.94부터 있습니다.

목적별 명령

모든 st 명령과 플래그는 st 명령 레퍼런스에 있습니다.

알아 둘 것

• tmux가 필요합니다. Windows에서는 대신 psmux 3.4.0을 씁니다(st 0.3.97 이상). 거기서는 실행 중인 에이전트를 워커로 데려올 수 있지만, st가 Windows에서 새 워커를 띄우지는 않습니다. zellij와 멀티플렉서 없음에는 워커가 없습니다. 명령은 st가 실행 중일 때, st가 공유하는 세션의 pane 안에서만 동작합니다.
• 새 워커는 코디네이터와 같은 세션에 뜹니다(--machine이면 그 장치의 st-remote 세션에 뜹니다). 데려온 워커는 다른 세션에 있어도, 다른 장치에 있어도 됩니다.
• 훅이 없으면 st가 워커의 시작을 확인하지 못해서 st worker start가 30초 뒤 실패합니다. 먼저 st hooks install을 실행하세요.
• 에이전트가 처음 여는 폴더라 신뢰 확인이나 로그인 화면이 뜨면 과제를 입력하지 못합니다. 90초 뒤 실패하고 창은 그대로 둡니다. 그 창에서 화면을 넘기거나 st worker stop <id> --yes로 닫으세요.
• 워커도 워커를 띄울 수 있지만 그 실행의 코디네이터 아래 두 단계까지이고, 전체 사슬은 네 단계까지입니다(st 0.3.88 이상).
• st의 Claude Code 훅은 에이전트가 서버를 지정하지 않거나 자기가 든 서버를 지정한 tmux kill-server, tmux를 겨냥한 pkill이나 killall을 실행하려 하면 거절합니다(st 0.3.88 이상). Codex 에이전트는 아직 검사하지 않습니다.
• 사람이 셸에서 직접 st worker start를 치면 워커는 그래프에 나오지만, 셸은 에이전트가 아니어서 셸에서 워커로 가는 선은 그려지지 않습니다.
• 앱과 그래프에서는 보기, 워커로 데려오기, 놓아 주기를 할 수 있습니다. 워커에게 말을 걸려면 그 창에 직접 치거나 채팅으로 보냅니다.

이 섹션의 문서

• 워커: 띄우기, 기다리기, 읽기, 데려오기.
• 작업, 범위, worktree: 순서, 워커마다 고칠 수 있는 범위, 같은 과제를 여러 번 시도하기.
• 결정 게이트: 사람에게 묻는 질문.
• 다른 장치의 워커: 같은 계정의 다른 장치에서 실행되는 워커.
• 에이전트 스킬과 플러그인: 에이전트에게 명령을 알려 주는 것.