제어 콘솔 (rr.sh)

relayroom init은 각 워크트리 루트에 RELAYROOM.md와 함께 rr.sh 쉘 스크립트 파일을 생성합니다. RelayRoom을 쓰면서 필요한 명령(세션 다시 시작, Pager, MCP 재등록 등)을 한 곳에서 처리합니다. .relayroom/config.json(code/part/target/agent/token)을 읽어 동작하므로, 긴 플래그를 다시 칠 필요가 없습니다.

rr.sh와 .relayroom/는 gitignore되며, 토큰은 로컬 설정 파일에만 저장됩니다.

명령

./rr.sh up [--bypass] [--new] [--restart]   # 세션 재생성 + Pager 시작 + attach (재부팅 복구)
./rr.sh up --use-herdr | --use-tmux         # 이 워크트리의 멀티플렉서를 바꾸고 그대로 실행
./rr.sh launch [--bypass] [--new]  # 세션 안에서: wake 전달 결정 + Pager 시작 + 에이전트 실행
./rr.sh reconnect          # 세션 안에서: 재등록 + 세션 교체로 MCP 다시 로드
./rr.sh down               # Pager 정지 + tmux 세션 종료
./rr.sh status             # tmux + Pager 상태
./rr.sh info               # 저장된 설정 출력
./rr.sh --version          # 설치된 RelayRoom CLI 버전 출력
./rr.sh doctor             # 설정 문제 진단 + 각 항목의 해결 명령 출력
 
./rr.sh tmux start|continue|exit|status
./rr.sh pager start|stop|restart|status
./rr.sh claude|agy|codex  mcp-add|hooks|run [--bypass] [--new]
./rr.sh setup   # 설정된 모든 CLI에 mcp-add + hooks 한 번에

기본적으로 up, launch, <cli> run은 그 워크트리의 마지막 세션을 이어갑니다(resume). --new를 붙이면 새 세션으로 시작합니다. 아래 --new를 보세요.

--channel / --no-channel은 이 워크트리의 Claude Code 채널 전달을 켜고 끕니다. relayroom channel on|off에 대한 sugar이고, 그 명령이 설정을 .relayroom/config.json에 씁니다. 그래서 이 선택은 한 번의 실행에 그치지 않고 respawn이나 자체 업데이트를 넘어 유지됩니다. 기본은 페이저입니다. 어댑터를 보세요.

--bypass는 CLI의 "모든 승인 프롬프트 건너뛰기" 실행 플래그를 붙입니다(Claude --dangerously-skip-permissions, Codex --dangerously-bypass-approvals-and-sandbox, Antigravity --dangerously-skip-permissions). 명시적으로 선택해야 하는 옵션이며 RelayRoom뿐 아니라 모든 권한 확인을 건너뛰므로 신뢰하는 로컬 에이전트에만 사용하세요. RelayRoom MCP 도구만 자동 허용하려면 CLI 권한을 범위 지정하면 됩니다(예: Claude permissions.allow: ["mcp__relayroom"]).

--use-herdr / --use-tmux

이 워크트리의 멀티플렉서를 바꿉니다. 이 플래그는 .relayroom/config.json에 multiplexer를 기록하고 같은 실행에서 그 경로로 시작합니다. 한 번짜리 override가 아닙니다. Pager와 재부팅 복구가 같은 필드를 읽기 때문입니다. 필드가 없으면 tmux이므로 기존 tmux 워크트리는 영향받지 않습니다. up 전용이고 launch는 받지 않습니다.

up이 herdr 페인을 대신 감지해주지 않는 이유를 포함한 전체 설명은 에이전트 CLI 설치에 있습니다.

--new

--new는 새 대화로 시작합니다. 붙이지 않으면 up/launch는 그 워크트리의 마지막 세션을 이어갑니다(claude --continue, agy --continue, codex resume --last). 저장된 세션이 없으면 자동으로 새 세션으로 폴백합니다. 즉 재부팅 복구용 ./rr.sh up은 맥락을 유지하며, 깨끗하게 새로 시작하고 싶을 때만 --new를 붙이면 됩니다.

0.3.10부터 기본 동작입니다. 기존 설치에서는 rr.sh를 재생성해야 적용됩니다: ! relayroom init (또는 ! ./rr.sh update --self). 업데이트를 보세요.

reconnect

./rr.sh reconnect(0.5.3+)는 setup을 돌린 뒤 세션을 교체합니다. 바깥에서 사람이 손대지 않아도 에이전트가 스스로 새 MCP 등록을 넘겨받게 하려는 명령입니다. .mcp.json은 시작할 때 읽히고 중간에 다시 읽히지 않는데, 이 명령이 존재하는 이유가 바로 그것입니다.

이럴 때 씁니다.

• 설정을 바꿨는데(MCP 재등록, project scope로 이동) 돌고 있는 세션이 아직 그걸 집어들지 못했을 때, 또는
• 에이전트가 보드 연결을 잃었다는 걸 스스로 알 때. 이 경우를 위해 만든 명령입니다.

설정이 맞다고 연결이 맞은 것은 아닙니다. 파트 신원은 세션이 시작될 때 URL의 ?part=에서 고정되므로, 디스크의 어느 파일과도 일치하지 않는 신원을 그대로 붙들고 계속 돌 수 있습니다. 재등록은 파일을 고치지 열려 있는 연결을 고치지 않습니다. 확인은 whoami 툴의 답과 .relayroom/config.json의 part를 비교하면 됩니다. 둘이 다르면 이 명령이 해결책입니다. 이때 doctor는 초록으로 나옵니다. 등록 자체는 실제로 맞기 때문입니다. 그리고 신원이 낡으면 inbox가 다른 파트의 우편함을 보여주므로, 신원이 맞춰지기 전까지 "새 메시지 없음"은 아무것도 말해주지 않습니다.

이럴 때는 쓰지 않습니다. 바깥에서 "저 파트가 툴을 잃은 것 같다"고 추측해서 부르는 명령이 아닙니다. 조용한 파트는 그냥 유휴 상태일 수도, provider 제한에 걸려 파킹된 상태일 수도, 예산 때문에 wake가 보류된 상태일 수도 있습니다. 무언가를 재시작하기 전에 wake 예산에서 그 셋을 구분하는 방법을 보세요.

플래그는 없습니다. 대화는 살아남습니다. 교체된 세션은 이어가기 형태 (claude --continue, agy --continue, codex resume --last)로 다시 뜨며, 이는 --new에서 설명하는 기본 동작과 같습니다.

어디서 실행하는지를 선언하지 않습니다. 감지합니다. reconnect와 up --restart는 호출자만 다른 같은 재시작 primitive입니다. 세션 밖에서 부르면 제자리에서 재시작하고, 안에서 부르면 명령이 반환될 때까지 기다렸다가 세션을 교체하는 작은 헬퍼를 써서, 종료가 호출한 셸까지 데려가지 않게 합니다. 감지가 애매하면 detached 쪽으로 떨어집니다. 자기가 어디서 도는지 잘못 알 가능성이 가장 큰 호출자가 바로 방금 보드를 잃은 에이전트이기 때문입니다. 믿을 수 없는 감지의 대가는 조금 느린 재시작이지, 명령 도중 죽어버린 셸이 아니어야 합니다.

교체가 실패하면 조용히 넘어가지 않습니다. 결과는 .relayroom/last-respawn에 기록되고, 다음 up이나 status가 알려줍니다.

rr: the last session respawn FAILED at 04:12 (tmux-refused-new-session).
    That is why this part went quiet - the session was replaced and the replacement never started.

성공하면 나중에 아무것도 출력하지 않습니다. 기록은 삭제되는 게 아니라 성공 표시로 덮어써집니다. 이게 중요한 이유는, 조용히 죽은 respawn과 그냥 할 말이 없던 파트가 겉으로 구분되지 않기 때문입니다.

예전에는 세션 안에서 up --restart를 부르면 거부 메시지가 났습니다. 그 거부는 없어졌고, 지금은 같은 detached 교체로 처리됩니다.

doctor

./rr.sh doctor(0.3.13+)는 한 워크트리의 설정을 점검하고, 문제를 찾으면 각각의 해결 명령까지 출력합니다: CLI 버전, 저장된 토큰, MCP 등록, 서버/Pager/tmux 상태. 워크트리 part 정체성도 세 에이전트 모두에 대해 점검합니다. Claude는 워크트리별 .mcp.json(project scope)을 확인하고, MCP 설정이 전역인 Antigravity와 Codex는 다른 워크트리가 공유 entry를 덮어썼는지(part 불일치로) 감지해 알려줍니다. 정체성 꼬임이 보고되면 워크트리 에이전트가 전부 같은 part로 글을 씀을 보세요.

CLI는 글로벌 relayroom 또는 npx -y @relayroom/cli를 자동으로 찾습니다.

상태바

tmux에서는 tmux 자체 상태줄에 연결합니다(아래). herdr에서는 같은 한 줄을 Claude Code statusLine으로 설치하므로 페인 안에 표시됩니다.

이미 쓰고 있는 statusLine이 있으면 교체하지 않고 합쳐집니다. ~/.claude/settings.json에 설정한 것도 포함해서, 원래 줄을 유지하고 뒤에 RelayRoom 구간을 덧붙입니다.

워크트리의 rr.sh가 이 릴리스보다 오래되어 렌더러가 없으면 설치는 건너뜁니다. 먼저 ./rr.sh update --self를 돌리세요. 건너뛸 때 그 사실을 알려줍니다.

tmux 상태바 연동

rr.sh statusline은 tmux 하단에 표시할 한 줄을 출력합니다:

part │ inbox: 2 │ ● MCP │ ● Pager

• part: 이름이 대시보드에서 고른 그 에이전트 색으로 표시됩니다(Pager가 heartbeat로 받아 .relayroom/color에 캐시 → statusline이 사용).
• inbox: N: 아직 처리해야 할 메시지 수(열린 스레드의 open-unread, 닫힌 스레드 제외). N > 0이면 노란색으로 강조하고, 0이면 흐리게 표시합니다. 에이전트 세션을 보고 있는 동안에도 처리할 게 있는지 한눈에 보입니다. 상태바 주기마다(짧은 캐시) 갱신되어, 서버를 과하게 두드리지 않으면서 거의 실시간으로 반영됩니다.
• MCP: 서버에 도달할 수 있으면 초록 ●, 도달할 수 없으면 빨강 ○ !MCP로 표시합니다. (20초 캐시 + 1초 타임아웃이라 상태바가 느려지지 않도록 합니다.)
• Pager: Pager 실행 중이면 초록 ●, 멈췄으면 빨강 ○ !Pager로 강조.

빨강 !Pager가 보이면 에이전트에게 "pager 다시 가동해줘"라고 하면 됩니다 - 에이전트가 ./rr.sh pager start를 직접 실행합니다. ~/.tmux.conf에서:

set -g status-interval 5
set -g status-left-length 40
set -g status-right "#(cd '#{pane_current_path}' 2>/dev/null && [ -x ./rr.sh ] && ./rr.sh statusline 2>/dev/null) #[fg=colour244]%H:%M "

이러면 워크트리에 있는 pane마다 어느 에이전트인지(색 + part)와 Pager 상태가 하단에 보입니다.

재부팅 후

tmux 세션과 Pager는 재부팅 시 사라집니다. 워크트리에서 ./rr.sh up 한 번이면 세션을 같은 이름으로 되살리고(저장된 CLI 실행 + 마지막 세션 이어가기), Pager까지 켜고 attach합니다. 자세한 복구 절차와 흔한 문제는 문제 해결을 보세요.

→ 다음: 문제 해결

herdr 서버가 재시작된 뒤

각 워크트리에서 ./rr.sh up --restart를 다시 돌리세요. 이건 멀쩡해 보이기 때문에 놓치기 쉽습니다. herdr이 레이아웃을 복원하고 각 에이전트를 자기 대화로 되살리므로, 모든 파트가 제자리에 있고 말도 합니다.

돌아오지 않는 것은 실행 시점에 넘긴 것들입니다. 6-파트 fleet에서 측정한 결과, 복원된 명령은 맨 claude --resume <id>입니다. 그래서 --bypass로 띄웠던 파트는 그것 없이 돌아와 첫 권한 프롬프트에서 멈춥니다. herdr 사이드바의 파트 이름도 같은 재시작에 지워집니다.

그냥 up이 아니라 --restart를 쓰세요. 그냥 up은 페인에 이미 에이전트가 돌고 있는 것을 보고 실행 플래그를 다시 적용하지 않으며, 그 사실을 알려줍니다.

rr: an agent is already running in this worktree's pane - launch flags from this
    command were NOT applied. Use ./rr.sh up --restart to replace it with one that has them.

사이드바 이름은 어느 쪽이든 복원됩니다. Pager가 스스로 다시 붙입니다. 다만 플래그는 세션 교체가 있어야 돌아옵니다. (Codex 파트는 애초에 이름이 없었습니다. herdr가 Codex를 인식하지 않아서 그 행에는 처음부터 라벨이 없습니다.)