워커

st worker start로 워커를 띄우는 법, 과제 파일을 쓰는 법, 워커가 코디네이터에게 지킬 일, 기다리고 읽고 보내는 법, 워커 이름을 바꾸는 법, 이미 실행 중이던 에이전트를 워커로 데려오는 법을 다룹니다.

워커는 다른 에이전트의 일을 맡아 하는 Claude Code, Codex, opencode, Pi 세션이고(opencode와 Pi는 st 0.3.113부터), tmux 창을 하나씩 따로 씁니다. 코디네이터는 st worker start로 워커를 새로 띄우거나, 이미 실행 중이던 에이전트를 워커로 데려옵니다. 이 명령은 보통 사람이 아니라 코디네이터 에이전트가 칩니다. st 0.3.67 이상과 훅(st hooks install)이 필요하고, 데려오기는 st 0.3.70 이상에서 됩니다.

워커 띄우기

st worker start --agent claude --name api-tests --task api-tests.md
st worker start --agent codex --task -            # 과제를 표준 입력으로

--agent에는 claude, codex, opencode, pi를 줍니다.

st worker start는 다음 순서로 움직입니다.

과제 파일을 ~/.sophonz/orch/<실행>/<이름>.md로 복사하고, 끝에 워커가 지킬 일(다 하면 st worker done으로 보고하기)을 덧붙입니다.
코디네이터의 세션에 워커 이름으로 새 창을 열고 에이전트를 띄웁니다. 작업 폴더는 코디네이터 pane의 폴더와 같습니다.
에이전트 입력창이 뜨면 "과제가 이 파일에 있으니 읽고 진행하라"는 한 줄을 st의 채팅 보내기로 입력합니다. 그 줄이 가리키는 파일은 프로젝트 안의 사본이라 어느 에이전트든 묻지 않고 읽습니다. 일반 checkout에서는 .git/st/<실행>/, worktree에서는 .st/<실행>/이고, st가 저장소의 .git/info/exclude에 /.st/를 넣어 git status가 깨끗하게 남습니다. git이 없는 폴더에서는 ~/.sophonz/orch/의 파일을 가리킵니다(st 0.3.102 이상). 권한 질문 같은 다른 화면이 떠 있으면 그 위에 입력하지 않고, 입력한 뒤에는 대화 기록을 보고 실제로 들어갔는지 확인합니다.
워커가 턴을 시작한 것이 훅으로 확인된 다음에야 성공으로 끝납니다.

90초 안에 그 한 줄을 입력하지 못하면(처음 여는 폴더의 신뢰 확인 화면이나 로그인 화면 때문에) 실패로 끝나고 창은 그대로 남습니다. 그 창에서 화면을 넘기거나 st worker stop <id> --yes로 닫습니다. 입력한 뒤 30초 안에 턴이 시작되지 않아도 실패합니다. 대개 훅이 설치되지 않은 경우입니다.

그 밖의 플래그는 이렇습니다.

--name <이름>: 창 이름이자 과제 파일 이름입니다. 소문자, 숫자, -만 남기고 24자에서 자릅니다. 주지 않으면 과제의 첫 줄로 이름을 짓고, 이미 있는 이름이면 번호를 붙입니다.
--split: 새 창 대신 코디네이터 옆에 pane을 나눠 띄웁니다.
--cwd <폴더>: 워커가 일할 폴더를 정합니다.
--owns "<경로>"와 --worktree: 워커끼리 서로의 작업을 건드리지 않게 합니다. 작업, 범위, worktree를 참고하세요.
--machine <장치>: 같은 계정의 다른 장치에 띄웁니다. 다른 장치의 워커를 참고하세요.

워커도 자기 워커를 띄울 수 있습니다. 다만 한 실행 안에서는 그 실행의 코디네이터 아래 두 단계까지이고, 일을 아래로 넘기는 에이전트 사슬 전체는 맨 위 코디네이터부터 가장 아래 워커까지 네 단계까지입니다. st는 두 가지를 모두 세고, 다른 장치를 거쳐도 이어서 셉니다. 그보다 깊어지는 워커는 거절합니다("too deep"). 워커로 데려온 팀은 따로 실행을 가지므로 그 팀의 워커는 팀장부터 셉니다. st 0.3.88 이상의 규칙이고, st 0.3.87 이하는 모든 워커를 맨 위 코디네이터 아래 두 단계로 셌습니다.

과제 파일 쓰기

과제 파일은 그 파일 하나만 읽고도 일할 수 있게 씁니다. 다룰 대상(파일, 컴포넌트, 명령), 바꿀 내용, 지켜야 할 제약을 적고, 이 워커가 고칠 수 있는 범위와 다른 워커가 맡은 범위를 밝힙니다. 끝으로 다 됐다는 증거가 될 테스트나 명령을 적어 둡니다.

워커가 지킬 일

일을 마치면 완료 기준을 확인하고 st worker done --summary "<한 일과 확인한 방법>"으로 보고합니다.
끝내지 못했으면 그렇게 밝힙니다. st worker done에 --outcome failed를 주거나, 요약을 blocked:로 시작합니다(실패로 읽힙니다). 기본은 --outcome succeeded입니다(st 0.3.113 이상).
결정이 필요하면 답에 질문을 남기고 멈춥니다. 코디네이터가 그 답을 읽고 st worker send로 대답합니다. 답을 받고 이어서 일하려면 st worker question "<질문>"으로 묻고 코디네이터의 st worker reply를 기다릴 수 있습니다(아래 참고). 사람만 정할 수 있는 일이면 대신 결정 게이트를 엽니다.
자기 worktree가 있으면 보고하기 전에 자기 브랜치에 커밋합니다.

워커는 이 규칙을 과제 파일 끝과 st skills get worker에서 읽습니다. Claude Code와 Codex는 st plugin install로도 받습니다. opencode와 Pi에는 플러그인이 없으므로 과제 파일 끝이 st skills get worker를 가리킵니다(st 0.4.0부터는 그 에이전트용 안내를 한 번에 읽는 st --skill도 있습니다).

기다리기, 읽기, 보내기

st worker wait --timeout 15m      # 이 pane의 모든 워커
st worker wait %15 %16 --any      # 하나라도 조건에 맞으면
st worker read %15                # 마지막 답과 done 요약
st worker send %15 "오류 경로도 테스트해 줘."
st worker send %15 --file brief.md   # 긴 브리프를 문서로 남겨 보내기
st worker list                    # 이 pane의 워커
st orch history                   # 누구에게 무엇을 맡겼고 누가 끝냈는지
st worker stop %15 --yes          # 그 pane 닫기

st worker wait [id…]는 워커가 끝나거나 입력을 기다리는 상태가 될 때까지 기다립니다. id를 주지 않으면 이 pane의 워커를 모두 기다립니다.

--any: 워커 하나만 조건에 맞아도 돌아옵니다.
--for done,waiting,idle: 어떤 상태를 기다릴지 고릅니다. 기본은 셋 다이고, 닫힌 워커(exited)는 언제나 조건에 맞는 것으로 칩니다.
--timeout 15m: 기본은 15분입니다. 시간이 다 돼도 실패가 아닙니다. st worker list로 상태를 보고 다시 기다리면 됩니다.
--check-in 3m: 그 시간이 지나면 워커마다 상태, 그 상태로 있은 시간, 제목을 알려 주고 돌아옵니다. 워커는 계속 일합니다. 시간 초과처럼 종료 코드 2입니다(st 0.4.0 이상).

종료 코드는 다 끝났으면 0, 입력을 기다리는 워커가 있으면 3, 시간 초과면 2입니다. idle인 워커도 끝난 것으로 치고, st worker wait가 그 워커 옆에 그렇다고 적어 줍니다. 그 워커의 답을 읽어 보세요.

워커는 다음 다섯 상태 가운데 하나에 있습니다.

상태	뜻
`working`	에이전트가 턴을 진행하는 중
`waiting`	질문, 권한, 게이트로 묻는 중
`done`	`st worker done`으로 보고함
`idle`	`st worker done` 없이 턴이 끝남
`exited`	pane이 없어짐

st worker read <id>는 워커의 마지막 답(마지막 프롬프트 뒤에 쓴 글)과 done 요약을 보여 줍니다.
st worker send <id> "<글>"은 같은 채팅 보내기로 워커에게 말을 더 전하고, 제대로 들어갔는지 확인합니다. send 다음의 wait는 워커가 새 턴을 시작해서 마칠 때까지 기다립니다. 앞서 한 일의 완료 표시가 남아 있어도 바로 돌아오지 않습니다(st 0.3.83 이상). 그 pane의 에이전트가 내 실행의 워커가 아니면 보내지 않습니다. 복원 뒤의 옛 id로 보낼 때 그럴 수 있습니다. 그때는 내 워커들의 id를 알려 주고, --force를 주면 그래도 보냅니다(st 0.3.90 이상).
st worker send <id> --file <파일|-> ["<메모>"] [--title T]는 긴 브리프를 보냅니다. st가 바뀌지 않는 사본과 문서를 남기고, 워커에게는 그것을 가리키는 한 줄만 입력합니다. --doc <문서>는 이 장치가 이미 가진 문서를 같은 방식으로 보냅니다(st 0.3.93 이상).
입력하지 못한 것은 사서함에서 기다립니다. 지금 입력할 수 없으면(누가 그 입력창에 치는 중이거나 질문 화면이 떠 있으면) 실패로 끝나지 않고, 그 일이 워커의 사서함에서 기다립니다. st는 워커의 턴 사이에 [st] 2 messages for you -- st worker inbox 같은 안내를 입력합니다. 워커가 부모에게 보내는 done, idle 소식도 같습니다. st worker inbox는 이 pane에 와 있는 것을 보여 주고 받은 것으로 표시합니다. --peek은 보기만 하고, --ack <id>나 --ack-all은 보여 주지 않고 표시만 하며, --wait는 무언가 올 때까지 기다립니다(st 0.3.113 이상).
답을 기다리는 질문. st worker question [<id>] "<질문>"은 다른 pane(기본은 이 워커의 코디네이터)에 묻고 답을 기다립니다. 기본 10분이고 --timeout으로 30분까지 늘릴 수 있습니다. 답이 오지 않으면 종료 코드 2이고, --resume <질문 id>로 다시 기다립니다. 질문을 받은 pane은 st worker reply <질문 id> "<답>"으로 답합니다(st 0.3.113 이상).
부모에게 알립니다. 워커가 st worker done을 실행하거나 실행하지 않은 채 턴이 끝나면, st가 아직 일하고 있는 가장 가까운 부모에게 그 턴 사이에 한 줄을 입력합니다. 워커가 끝났으니 st worker read로 읽으라는 내용입니다(st 0.3.92 이상). 부모의 에이전트가 그 줄을 받아 가면 알린 것으로 칩니다.
st orch history는 누구에게 무엇을 언제 맡겼는지, 누가 끝냈고 누가 알림을 받았는지 보여 줍니다. --run <실행>, --all, --limit N, --json을 받습니다(st 0.3.92 이상).
st worker list는 이 pane의 워커를 id, 이름, 창, 상태, 과제와 함께 보여 줍니다. 워커 아래의 워커는 그 아래에 트리로 나오고, --depth 1을 주면 이 pane 바로 아래 워커만 나옵니다(st 0.3.90 이상). 아래 워커가 목록에 없는 팀장 행 뒤에는 (team N)이, 코디네이터 pane이 사라진 워커 뒤에는 (parent gone)이 붙습니다. pane이 더 이상 없는 워커는 lost입니다. 그 워커가 실행되는 곳에서 다시 데려오세요(st 0.3.97 이상). --all을 주면 다른 장치의 워커까지 모든 실행의 워커가 나옵니다. st orch status도 같은 목록을 보여 줍니다. st 0.3.88 전에는 누가 띄웠든 이 pane이 속한 실행(run)의 워커를 모두 보여 줬습니다.
st worker stop <id> --yes는 st가 띄운, 내 실행의 워커의 pane을 닫습니다. 데려온 워커는 닫지 않습니다.

워커는 tmux pane id(%15)로도, st worker list에 보이는 이름(api-tests)으로도 가리킵니다. 다른 장치의 워커는 ci-mac/%15, ci-mac/api-tests처럼 앞에 장치 이름이 붙습니다. 이름은 이 pane의 워커와 그 아래 워커에서 먼저 찾고, 없으면 그 장치의 모든 워커에서 찾습니다. 두 워커가 같은 이름이면 st는 아무것도 하지 않고 둘을 보여 주니 id를 쓰세요. 이름은 st 0.3.90부터 씁니다. st worker만 치면 사용법이 나옵니다. orch와 worker 명령은 모두 --json을 받습니다. 플래그 값은 --name api-tests처럼 한 칸 띄워 씁니다. 전체 목록은 st 명령 레퍼런스에 있습니다.

핸드오프는 남습니다

st worker send <id> --file로 보낸 브리프는 워커의 창에 입력되지 않습니다. st가 파일로 보관하고, 워커에게는 그 위치를 알려 주는 한 줄만 입력합니다(st 0.3.93 이상).

A message from coordinator is in /path/to/project/.git/st/<run>/sent/20261021-025532-web.md ("Title", 4.1 KB). Read it and do it.

사본은 ~/.sophonz/orch/<run>/sent/에 보관되며, 파일 이름에 보낸 시각과 받는 워커가 들어갑니다(<YYYYMMDD-HHMMSS>-<worker>.md). 입력되는 줄은 과제와 마찬가지로 워커 프로젝트 안의 사본을 가리킵니다(워커 띄우기 참고). 사본은 덮어쓰지 않으며, 브리프는 장치의 문서로도 남습니다.
긴 브리프가 워커의 입력 칸이나 터미널의 스크롤백을 채우지 않고, 본문이 셸을 거치지도 않습니다.
st orch history가 실행의 핸드오프를 시각, 종류, 누가 누구에게, 제목 순으로 보여 줍니다.
```
10-22 02:49:01  done  terminal-go %12 → st-desktop %13  1. st set — PR #126…
```
기록에는 트리의 모든 변경도 남습니다. 에이전트를 데려오거나 놓아 주거나, 이름이나 역할을 바꾼 일이 누가 요청했는지, 바뀌기 전과 후의 부모와 함께 기록됩니다(st 0.3.98 이상).
에이전트 그래프 옆 History 탭이 같은 기록을 최신순으로 보여 줍니다. 데스크톱 앱(0.1.39 이상)과 웹 터미널(st 0.3.98 이상) 모두에 있습니다. 카드를 고르면 그 에이전트의 일만 보입니다. 한 줄을 누르면 그 핸드오프 문서가 열리고, 문서가 없어졌거나 바뀌었으면 st가 보관한 사본이 열립니다.

워커의 이름

워커의 이름은 라벨입니다. st worker start는 --name이나 과제의 첫 줄로 이름을 짓고, 데려온 에이전트는 tmux 창 제목을 같은 규칙으로 고쳐 이름으로 씁니다. 그래서 이름은 워커가 어느 장치에서 실행되는지 말해 주지 않습니다. 누가 "Windows CI"라고 제목을 붙인 창을 데려오면 windows-ci라는 워커가 되는데, 그게 Mac의 에이전트일 수도 있습니다. 장치를 알려 주는 것은 다른 장치 id의 / 앞(ci-mac/%7의 ci-mac)뿐입니다.

하는 일을 말해 주는 이름으로 바꾸려면 이렇게 합니다(st 0.3.96 이상).

st worker rename %15 ios-tests
st worker rename ci-mac/windows-ci ios-ci   # ci-mac/%7 is ios-ci now (was windows-ci)

id는 %15, 이름, ci-mac/%7, ci-mac/<이름> 어느 형태든 받습니다. st가 띄운 워커와 데려온 워커 모두 됩니다.
이름은 --name과 같은 규칙으로 씁니다. 소문자로 바꾸고 글자, 숫자, -가 아닌 것은 -로 바꾸므로 iOS CI는 ios-ci가 됩니다. 24자를 넘으면 자르지 않고 거절합니다.
다른 워커가 쓰는 이름은 대소문자를 가리지 않고 거절하고, 그 이름을 가진 워커의 id를 알려 줍니다. 계정의 장치와 같은 이름(slug, 이름, 호스트 이름)도 거절합니다.
새 이름은 실행 기록에도 남아서 tmux를 다시 시작한 뒤에도 돌아옵니다. 데려온 워커가 창 제목을 다시 이름으로 쓰는 것은 놓아 준 뒤 다시 데려올 때뿐입니다.
tmux 창 제목은 그대로 둡니다. 창은 사용자의 것이고 다른 pane이 함께 있을 수 있습니다. 그래서 그때부터는 이름과 창 제목이 다를 수 있습니다.

다른 장치의 워커는 다른 장치의 워커 이름 바꾸기를 보세요.

이미 대화하던 에이전트를 워커로 데려오기

st worker start로 띄운 에이전트는 빈 맥락에서 시작합니다. 이미 한참 대화하면서 코드를 읽어 둔 에이전트가 있다면 그 에이전트를 그대로 다른 에이전트의 워커로 데려올 수 있습니다. 새로 띄우는 것이 아니어서 지금까지 대화로 쌓인 맥락이 그대로 남습니다. 다른 세션에 있는 에이전트여도 됩니다. st 0.3.70 이상이 필요합니다.

데스크탑 앱과 브라우저에서. 사이드바에서 워커로 쓸 에이전트의 창 행을 끌어다 지휘할 에이전트의 창 행에 놓습니다. 데스크탑 앱에서는 에이전트 그래프에서 카드를 끌어 다른 에이전트 카드에 놓아도 됩니다. 놓을 때 보이는 표시, 놓을 수 없는 경우, 데려온 뒤 사이드바의 모양, 놓아 주는 법은 데스크탑 앱 가이드의 에이전트 데려오기에 있습니다. 데스크탑 앱 0.1.31 이상이 필요하고, 브라우저의 웹 터미널(데스크탑 레이아웃)도 st 0.3.86부터 사이드바에서 똑같이 됩니다. 코디네이터가 사라진 워커에는 사이드바에 ⚠와 Release가 나옵니다(데스크탑 앱 0.1.33 이상, 웹 터미널은 st 0.3.88 이상). 놓아 주거나, 그 행을 다른 에이전트 행에 끌어 놓아 다시 데려오면 됩니다.

폰에서. 창 목록에서 에이전트 창을 길게 누르거나 에이전트 차트의 카드를 길게 눌러 워커로 맡기기…를 고릅니다. 누구의 워커로 할까요? 시트에 계정의 장치마다 에이전트 pane이 나오고(지금 장치가 먼저), 자기 자신과 이미 자기 아래에 있는 에이전트는 빠집니다. 하나를 고르면 "api-tests: 이제 coordinator의 워커입니다. 지금까지의 대화가 그대로 남습니다."가 뜹니다. 알리지 못한 에이전트가 있으면 "api-tests에게 알리지 못했습니다"와 그 이유가 함께 나옵니다. 놓아 줄 때는 워커를 길게 눌러 놓아 주기를 고릅니다. VoiceOver와 TalkBack에서도 같은 이름의 동작으로 나옵니다.

누구의 워커로 할까요? 시트: 이 장치와 CI Mac의 에이전트 pane, 워커를 받지 않는 장치는 흐리게 표시 — 워커로 맡기기

데려온 뒤의 토스트: review: 이제 planner의 워커입니다, 알리지 못한 이유와 함께 — 데려온 뒤

명령으로. 지휘할 에이전트의 pane에서 치거나, --parent로 지휘할 에이전트를 지정해서 칩니다. 보통은 에이전트에게 "%15를 네 워커로 데려와서 테스트를 맡겨"처럼 부탁하면 됩니다.

st worker adopt %15                 # 이 pane의 워커로
st worker adopt %15 --parent %12    # %12의 워커로
st worker adopt %15 --owns "web/**" # 고칠 수 있는 범위까지 정해서
st worker release %15               # 놓아 주기

데려오면 st가 두 에이전트에게 한 줄씩 알립니다. 부모에게는 워커의 id와 일을 맡길 때 쓰는 명령(st worker send, read, wait)을 알려 주고, 워커에게는 누구의 워커가 됐는지와 일을 마치면 st worker done으로 보고하라는 것을 알려 줍니다. 그때부터는 다른 워커와 똑같이 다룹니다.

데려올 때는 두 가지가 더 따라옵니다(st 0.3.93 이상).

역할. 터미널에서 st worker adopt를 실행하면, --role "<이유>"를 주지 않은 경우 그 에이전트를 왜 데려오는지 묻습니다. 역할은 워커 이름 아래에 나옵니다. st worker about <id> "<역할>"로 바꾸고, --clear로 지웁니다.
브리프. 데려온 에이전트의 턴이 끝나면 st가 지금까지 한 일을 다섯 줄 이내로 알려 달라고 묻고, 에이전트는 st worker brief --summary로 답합니다. st worker read가 그것을 보여 주고, st worker wait <id> --brief는 그것을 기다립니다. --no-brief를 주면 묻지 않고 데려옵니다.

st worker send %15 "인증 모듈 테스트를 추가해 줘. go test ./internal/auth가 통과하면 끝이야."
st worker wait %15
st worker read %15

데려온 워커에게는 과제 파일이 없고, 일은 st worker send로 받습니다. 이미 아는 내용을 다시 설명할 필요는 없습니다.
에이전트가 질문이나 권한 화면에 있어서 입력창이 보이지 않으면 st는 알림을 입력하지 않습니다. 데려오기 자체는 이루어지고, 결과에 누구에게 알리지 못했는지와 그 이유가 나옵니다. 화면이 넘어간 뒤 직접 알려 주거나 st worker send로 보냅니다.
부모와 워커는 둘 다 에이전트여야 합니다. 자기 자신을 데려오거나, 이미 자기 아래에 있는 에이전트를 데려와 고리가 생기거나, 위에서 말한 한도(실행 안에서 두 단계, 전체 사슬 네 단계)를 넘으면 거절됩니다.
자기 워커가 있는 에이전트는 팀으로 들어옵니다. 다음 절을 보세요.
놓아 주면 데려오기 전으로 돌아갑니다. 앱에서는 워커 카드에 포인터를 올리고 Release를 누릅니다. st worker stop은 데려온 워커를 닫지 않습니다. 원래 누군가가 쓰던 세션이기 때문입니다.

팀을 워커로 데려오기

팀은 따로 만드는 것이 아니라 생기는 것입니다. 코디네이터는 맨 위에 고정된 역할이 아니라 자리이므로, 자기 워커를 거느린 에이전트도 다른 에이전트처럼 데려올 수 있습니다. 데려오는 순간 그 에이전트와 워커들이 팀이 되고, 그 에이전트가 팀장이 됩니다. 사이드바에서 그 카드의 머리 행을 다른 에이전트 행에 끌어다 놓거나 st worker adopt를 실행하면 됩니다. 팀이 통째로 들어오고 누구의 대화도 사라지지 않으며, 새 코디네이터에게는 워커 하나로 보입니다. 새 코디네이터가 이미 다른 에이전트의 워커여도 됩니다. st 0.3.88 이상이 필요합니다(팀장이 다른 장치에 있으면 두 장치 모두).

팀장은 자기 실행을 유지합니다. 새 코디네이터의 실행에는 팀장 하나가 워커로 들어가고, 팀장의 워커는 계속 팀장의 워커이고, 그 워커들 쪽에서는 아무것도 바뀌지 않습니다. 팀장의 st worker list에도 자기 팀이 그대로 보입니다.
일은 팀장에게만 줍니다. 새 코디네이터는 st worker send로 팀장에게 일을 줍니다. 팀장이 일을 자기 워커에게 나누고, 기다리고, 결과를 확인한 뒤 st worker done --summary로 팀 전체를 한 번 보고합니다. 팀을 데려올 때 st가 두 에이전트에게 이렇게 알리고, 가이드에도 같은 내용이 있습니다.
기다리기와 읽기. id 없이 실행한 st worker wait는 이 pane의 워커만 기다리므로 팀장의 워커가 아니라 팀장을 기다립니다. st worker read <팀장>은 팀장의 마지막 답과 팀 전체에 대한 보고를 보여 줍니다.
보이는 곳. st worker list에서는 팀이 팀장 아래에 나오고, 팀이 목록에 없으면(--depth 1, 다른 장치) 팀장 행에 (team N)이 붙습니다. 사이드바와 에이전트 그래프에서는 이름 뒤에 team of N이 붙습니다(데스크탑 앱 0.1.33 이상, 웹 터미널은 st 0.3.88 이상).
깊이. 팀 안의 깊이는 팀장부터 세므로 팀장의 워커도 다시 자기 워커를 띄울 수 있습니다. 맨 위 코디네이터부터 이어지는 전체 사슬은 네 단계까지입니다. 새 코디네이터에서 한 단계 내려가면 그 실행 안에서 두 단계를 넘을 때, 또는 새 코디네이터까지의 사슬에 한 단계와 팀 자체의 깊이를 더하면 네 단계를 넘을 때 st가 데려오기를 거절합니다.
놓아 주기는 팀장만 놓아 줍니다. 팀장은 다시 자기 팀의 코디네이터가 되고, 팀은 그 아래 그대로 남습니다.

st 0.3.87 이하에서는 워커가 있는 에이전트를 전체가 두 단계 안에 들어올 때만 데려올 수 있었습니다. 데려오면 팀장이 새 코디네이터의 실행으로 옮겨 가서, 팀장의 st worker list에 자기 워커가 보이지 않았습니다.

맥락이 쌓인 세션을 워커로 넣는 법

한동안 대화한 세션은 코드와 그동안의 결정을 알고 있어서, 새로 띄운 워커보다 설명할 것이 적습니다. 그런 세션을 그대로 데려오는 순서는 이렇습니다.

세션의 id를 찾습니다. 그 세션의 pane에서 echo $TMUX_PANE을 치거나, st ls 또는 데스크탑 앱의 에이전트 그래프에서 확인합니다. %15 같은 모양입니다.
부모가 될 에이전트에게 부탁합니다. 예를 들어 "%15를 네 워커로 데려와서 인증 테스트를 맡겨. 그 모듈은 이미 알고 있어."라고 합니다. 부모 에이전트가 st worker adopt %15를 칩니다. 직접 쳐도 되는데, 그때는 부모의 pane에서 치거나 --parent를 줍니다.
일을 줍니다. 부모가 st worker send %15 "<할 일>"로 일을 보내고, st worker wait %15로 기다리고, st worker read %15로 결과를 읽습니다.
끝나면 놓아 줍니다. st worker release %15를 치거나 앱에서 Release를 누릅니다. 그 세션은 다시 원래 대화로 돌아갑니다.

섞어 쓸 수 있는 에이전트

부모와 워커는 Claude Code와 Codex를 섞어 써도 됩니다. Claude 코디네이터 아래 Codex 워커를 두어도 되고, Codex 코디네이터 아래 Claude 워커를 두어도 됩니다. 새 워커는 st worker start --agent claude|codex|opencode|pi로 고르고, 데려오기는 이미 실행 중인 에이전트를 그대로 씁니다. 다른 tmux 세션에 있는 에이전트도 되고, 같은 계정의 다른 장치에 있는 에이전트도 됩니다(st worker adopt ci-mac/%7, 다른 장치의 워커 참고).

Claude Code 백그라운드 세션

백그라운드로 보낸 대화는 tmux 밖에서 Claude 데몬 아래에서 실행되고, pane은 그 화면을 보여 주기만 합니다. st 0.3.83부터는 그 세션의 훅을 세션 이름과 같은 제목의 pane으로 연결합니다. 그래서 그 세션의 턴, 질문, 서브에이전트가 그 pane에 나타납니다. 같은 이름의 pane이 둘이면 st는 어느 쪽인지 짐작하지 않습니다.

tmux 재시작 뒤

누가 누구의 일을 하는지는 tmux pane과 함께 남고, 실행 기록은 코디네이터와 워커를 pane id로 가리킵니다. tmux 서버가 내려갔다가 st가 세션을 되살리면 pane은 모두 새 id로 돌아오고, 옛 id는 다른 pane이 받을 수도 있습니다. st 0.3.88부터는 이렇게 됩니다.

관계가 돌아옵니다. st는 10초쯤 안에 자리를 이어받은 pane에서, 또는 다른 창에서 직접 이어 간 에이전트(claude --resume)라면 대화로 코디네이터와 워커를 모두 다시 찾아 관계를 되돌려 놓습니다. 그 뒤로는 사이드바 카드, 에이전트 그래프, st worker list, st worker wait가 새 id로 동작합니다.
놓아 준 것은 되돌리지 않습니다. 일부러 놓아 주거나 정리한 관계는 다시 적지 않고, 다른 실행에 속한 pane은 가져오지 않습니다.
다른 장치의 워커에게는 코디네이터의 새 pane을 알립니다. 다른 장치의 워커를 보세요.
코디네이터를 찾지 못한 워커는 st worker list에 (parent gone)으로, 사이드바에는 ⚠와 Release로 나옵니다. 코디네이터는 st worker list로 자기 실행을 다시 찾습니다.
pane 번호가 아니라 키로 찾습니다(st 0.3.97 이상). 코디네이터와 워커는 각자의 pane에 남긴 키로 양쪽 장치에서 다시 찾습니다. 그래서 다른 장치의 워커가, 부모의 옛 번호만 이어받은 pane을 부모로 안내받는 일이 없습니다. 어느 pane에도 키가 없는 워커는 lost입니다. 그 워커가 실행되는 곳에서 다시 데려오세요.
남은 것이 없는 실행(코디네이터가 어느 tmux 서버에도, 스냅샷에도 없음)은 ~/.sophonz/orch/archive로 옮겨집니다. st orch unarchive <실행>으로 되돌리면 그 에이전트들을 키로 다시 찾습니다.

st는 에이전트가 실수로 tmux를 멈추지 않게도 막습니다. tmux pane에서 실행되는 에이전트가 다음 셸 명령을 실행하려 하면 st의 Claude Code 훅이 거절하고, 이유와 대신 쓸 명령을 알려 줍니다.

-S나 -L 없는 tmux kill-server. 장치의 모든 세션이 든 기본 서버를 멈출 수 있습니다.
에이전트 자신이 든 서버를 멈추는 tmux kill-server.
tmux를 겨냥한 pkill이나 killall.

테스트용 서버를 멈추려면 tmux -S <소켓> kill-server처럼 소켓을 지정합니다. 따옴표 안의 글이나 heredoc 본문은 거절하지 않습니다. Codex 에이전트는 아직 검사하지 않습니다.

실행을 파일 하나로

st project는 오케스트레이션 실행 하나를 .sophonz 파일 하나로 저장하고, 이 장치나 다른 장치에서 다시 엽니다(st 0.3.98 이상).

st project save [<run>] [-o <file>]     # 이 pane의 실행, 또는 지정한 실행
st project archive [<run>] [-o <file>]  # 저장한 뒤 실행을 은퇴시킴
st project show <file>                  # 들어 있는 것과, 여기서 열면 무엇을 할지
st project open <file> [--map <저장된 폴더>=<여기 폴더>]

들어 있는 것: 실행의 기록, 히스토리, 핸드오프 문서, 과제 파일, 에이전트마다의 마지막 요약과 브리프, 그리고 각 에이전트의 대화가 무엇이었는지입니다. 에이전트 일곱과 핸드오프 문서 55개의 실행이 약 137 KB였습니다.
대화 전문은 기본으로 넣지 않습니다. --with-conversations를 주면 에이전트의 대화 기록이 들어갑니다. 대화 기록에는 에이전트가 읽은 코드와 실행한 명령이 담기므로, 그때는 파일 스스로 그 사실을 적어 둡니다.
열면 에이전트마다 키를 기준으로 같은 트리에 창을 다시 만듭니다. 대화가 이 장치(또는 파일)에 있는 에이전트는 그 대화를 이어 가고, 없는 에이전트는 새 대화를 시작하면서 st가 보관한 그 에이전트의 몫(역할, 마지막 요약, 핸드오프 문서)을 받습니다. st project open이 에이전트마다 어느 쪽인지 알려 줍니다. 다른 장치의 워커는 여기서 열지 않습니다.
이 장치에 없는 폴더는 묻거나 --map으로 지정합니다. 둘 다 없으면 아무것도 바꾸지 않고 open이 종료 코드 3으로 끝납니다.
보관은 파일을 저장한 뒤 실행을 ~/.sophonz/orch/archive로 은퇴시킵니다. 그 파일을 다시 열거나 st orch unarchive를 실행하면 돌아옵니다.

데스크톱 앱(0.1.43 이상)에서는 File → Open Project…(⌘O, Windows와 Linux는 Ctrl+Shift+O), Save Project…(⌘S, Ctrl+Shift+S), **Archive Project…**입니다. 실행의 코디네이터가 있는 세션을 닫으면 먼저 Archive, Save as Project…, Cancel 중에서 고르게 합니다.