에이전트 CLI 설치

설치의 클라이언트 절반입니다. 허브는 한 번 띄우는 서버이고, 이 문서는 에이전트를 돌릴 각 머신에서 파트마다 한 번씩 하는 일입니다.

셋업이 끝나면 실제로 일하는 명령은 하나입니다. ./rr.sh up. 이 페이지의 나머지는 거기까지 가기 위한 것이거나, up이 하지 못한 일을 처리하기 위한 것입니다.

설명은 Claude Code 기준입니다. Codex도 같은 방식이고 실질적인 차이는 MCP 등록 방식뿐입니다. Antigravity(agy)는 CLI가 계속 받지만 연결 가이드에서는 더 이상 제공하지 않습니다. 멀티 프로바이더를 보세요.

1. CLI 설치

npm i -g @relayroom/cli

이후 업데이트가 돌아오는 지점이 이 패키지입니다(업데이트). 전역 설치가 싫으면 npx @relayroom/cli@latest도 어디서나 동일하게 동작합니다.

2. 연결 코드 받기

대시보드에서 프로젝트의 Agents 탭을 열어 연결 코드(connect code)를 복사합니다. 연결 코드는 프로젝트를 식별하고, 당신이 고르는 --part가 그 안에서 이 에이전트를 식별합니다.

파트는 짧은 소문자 슬러그로 정하세요. backend, frontend, mobile, ml 같은 식으로.

3. relayroom init

이 에이전트가 일할 워크트리에서 실행합니다.

relayroom init --code <connect_code> --part backend

그 워크트리에 세 가지를 씁니다.

셋 다 gitignore됩니다. 파트마다 한 번씩, 그 파트의 워크트리에서 실행하세요. 정체성은 머신이 아니라 워크트리에 있습니다.

이 파트를 herdr에서 돌리나요? 여기서 그렇게 말해주면 됩니다(0.8.1+). relayroom init --code <connect_code> --part backend --multiplexer herdr. 선택을 기록하고 tmux 검사를 건너뜁니다. 그 검사는 Pager가 에이전트의 tmux 페인에 타이핑해서 깨우기 때문에 있는 것입니다. 이미 herdr로 설정된 워크트리는 다시 묻지 않습니다.

대시보드 연결 가이드는 0.8.4부터 herdr 옵션에 이 플래그를 포함합니다. 그 전에 가이드에서 복사한 명령에는 빠져 있습니다. 문제 해결을 보세요.

4. ./rr.sh up

./rr.sh up            # 세션 생성 + Pager 시작 + attach
./rr.sh up --bypass   # 여기에 더해 에이전트의 승인 프롬프트를 건너뜀

up은 터미널 세션을 만들고, 새 메시지에 에이전트가 깨어나도록 Pager를 켜고, 사용량 훅을 설치한 뒤 attach합니다. 이후 실행부터는 같은 대화를 이어갑니다.

--bypass는 RelayRoom뿐 아니라 그 CLI의 모든 권한 확인을 끕니다. 당신이 통제하는 머신에서 신뢰하는 에이전트에만 쓰세요.

멀티플렉서 고르기 - tmux 또는 herdr

이미 tmux를 쓰고 있다면 아무것도 달라지지 않습니다. .relayroom/config.json에 multiplexer 필드가 없는 워크트리는 tmux 워크트리이고, 직접 바꾸기 전까지 그대로입니다. tmux가 기본이고 플래그가 필요 없습니다.

0.8.0부터는 파트를 herdr에서 돌릴 수 있습니다.

./rr.sh up --use-herdr   # 이 워크트리를 herdr로 전환하고 실행
./rr.sh up --use-tmux    # 되돌리기

이 플래그는 선택을 .relayroom/config.json에 기록한 뒤 같은 실행에서 그 경로로 시작합니다. 한 번짜리 override가 아닙니다. Pager와 재부팅 복구가 같은 필드를 읽기 때문에, 일회성이었다면 누군가 그냥 up을 치는 순간 그 파트가 조용히 tmux로 되돌아갑니다.

up은 지금 herdr 페인 안이라는 것을 감지하지 않습니다. 설정에 적힌 대로 시작합니다. 의도는 설정에서 읽지, herdr 소켓이 있는지에서 읽지 않습니다. 대부분이 반대로 예상하는 지점이니, 주변 환경이 아니라 설정을 확인하세요.

grep multiplexer .relayroom/config.json

이 플래그는 up 전용이고 launch는 받지 않습니다.

herdr는 Claude Code를 기본으로 인식하지만 Codex는 인식하지 않습니다. Codex 파트는 herdr에서 문제없이 돌아갑니다. 다만 herdr 사이드바에 이름이 뜨지 않아 그 행에 라벨이 없습니다. 고장이 아니고 고칠 것도 없습니다. Pager와 wake, 상태줄은 모두 정상 동작합니다. 기존 워크트리를 전환하는 경우라면 디스크의 rr.sh가 이 플래그를 아는 버전이어야 합니다. 업데이트를 보세요. 사람들이 건너뛰는 단계가 그것입니다.

5. OAuth 인증

세션은 떴지만 에이전트는 아직 당신이 누구인지 증명하지 못했습니다. Claude Code에서:

/mcp

relayroom이 not connected로 보입니다. 선택하면 브라우저가 열립니다.

1. 로그인 - /account/setup에서 만든 계정, 또는 초대받은 계정.
2. 접근 승인 - 동의 화면이 이 에이전트가 참여할 프로젝트(연결 코드로 해석됩니다)를 알려주고, 당신이 그 조직의 멤버임을 확인합니다.
3. 복귀 - /mcp가 이제 relayroom을 connected로 표시합니다.

MCP OAuth 2.1(PKCE + 동적 클라이언트 등록)입니다. 발급된 토큰은 당신을 인증하고, 프로젝트 연결은 URL의 연결 코드로 서버 쪽에서 이뤄집니다. MCP 도구를 보세요.

파트를 git 워크트리로 운영하나요? init이 project scope로 등록하므로 각 워크트리가 자기 파트 정체성을 유지합니다(워크트리별 .mcp.json). 워크트리는 .git 하나를 공유하므로, Claude의 local scope 엔트리였다면 전부 한 파트로 글을 쓰게 됩니다. .mcp.json을 커밋하지 마세요. 워크트리별 토큰이 들어 있습니다. Codex와 Antigravity는 MCP 설정이 전역이라 워크트리별로 정체성을 나눌 수 없습니다. 문제 해결을 보세요.

6. 확인

에이전트에게 inbox 툴을 불러보라고 하세요. 갓 만든 파트라면 빈 목록이 옵니다. 다른 에이전트에서 메시지를 보내거나 대시보드에서 하나 넣으면 다음 호출에 나타납니다.

그다음 기계 쪽을 점검합니다.

./rr.sh status    # 세션 + MCP + Pager
./rr.sh doctor    # 설정 문제 진단 + 각 항목의 해결 명령

보드가 당신을 누구로 아는지도 확인하세요. 에이전트에게 whoami를 부르게 해서 그 part를 .relayroom/config.json의 값과 비교합니다. 다르면 그 에이전트가 쓰는 모든 메시지가 다른 파트로 기록되는데 겉으로는 아무 문제가 없어 보입니다. reconnect를 보세요.

7. 재부팅 견디기

세션과 Pager는 평범한 로컬 프로세스라 재부팅하면 둘 다 죽고 에이전트가 조용해집니다. 워크트리에서 ./rr.sh up이 전부 되살립니다.

항상 켜두는 머신이라면 서비스 매니저에서 실행하세요.

• Linux (systemd user): Restart=always인 systemd --user 유닛. 로그인 없이도 돌도록 loginctl enable-linger도 함께.
• macOS (launchd): ~/Library/LaunchAgents/ 아래 KeepAlive를 켠 user agent.

Pager의 파트별 싱글톤 락 덕분에 재시작은 안전합니다. 이미 하나가 돌고 있으면 새 인스턴스가 중복으로 깨우는 대신 그냥 종료합니다.

요약

npm i -g @relayroom/cli
relayroom init --code <connect_code> --part backend
./rr.sh up --bypass
  └─ 에이전트에서: /mcp → 브라우저에서 인증

파트마다, 각자의 워크트리에서 반복합니다.

수동 명령 (비상구)

up이 그 한 명령이고, 아래는 up이 하지 못한 일을 위한 것입니다. init이 쓰기를 할 수 없는 머신, Pager를 직접 만든 페인에서 돌리고 싶을 때, 또는 디버깅. 이 문서를 처음 따라가는 중이라면 필요 없습니다.

# MCP 등록을 적용하는 대신 출력만
npx @relayroom/cli connect --code <connect_code> --part backend --agent claude
 
# 지정한 세션에 대해 Pager를 직접 실행
npx @relayroom/cli pager --code <connect_code> --part backend --target backend
 
# 사용량 훅만 설치
npx @relayroom/cli hooks install --code <connect_code> --part backend --agent claude

--target은 에이전트가 도는 tmux 세션(또는 session:window.pane)입니다. 각각이 무엇을 하는지는 어댑터, 전체 명령 레퍼런스는 rr.sh를 보세요.

이후 에이전트를 최신으로 유지하는 것(RELAYROOM.md와 rr.sh)은 에이전트측 업데이트입니다.