Rocky

한 기기에서 여러 에이전트 세션을 부리는 개인 툴킷이다. 하는 일은 넷이다 — 세션에 일을 맡기고(보드 · 핸드오프 · 새 세션 띄우기), 머지까지 결과를 받아 오고(PR 감시 · 기본 브랜치 검증 · 리뷰 반영), 폰에서든 데스크에서든 지켜보고 조종하며(웹 UI · 원격 제어 · statusline), 그 모든 것을 기록한다(워크로그 · 토큰 · 사용 로그). 넷 중 어디에도 붙지 않는 기능은 들이지 않고, 다른 곳에 있는 기능을 한꺼번에 옮겨 오지도 않는다 — 소유자가 하나씩 정해서 들인다. 본체는 **Rust 상주 데몬(rockyd)과 CLI(rocky)**이고, 그 위에 얇은 Claude Code 플러그인이 훅 · 슬래시 커맨드 · 스킬을 얹는다. 화면은 데몬이 http://127.0.0.1:8636/에서 서빙하는 웹 UI 하나다. 이름은 Project Hail Mary의 Rocky에서 따왔다. 2026-09에 별도 레포였던 rocky-todo를 흡수했다.

방향(2026-10-29): rocky는 자기 세션을 하나 가진 오케스트레이터 에이전트(로키)로 가는 중이다. 로키가 오너와 같이 생각하며 세션을 맡기고 깨우고 결과를 챙기고, 레포 맥락과 오너의 개인 맥락 저장소(캐비닛)를 도구로 찾는다. 아직 구현 전이고, 설계와 결정은 docs/design/specs/2026-10-29-rocky-orchestrator-design.md에 있다.

v0.23에서 걷어낸 것: openapi_* 7종, seo_validate, notion_* 4종과 단독 CLI openapi-mcp. 39개 레포 5,216턴의 워크로그를 세어 보니 호출이 0회였다. 전부 git 히스토리에 있으니 필요해지면 거기서 꺼낸다.

공개에 관하여: 이 저장소는 소유자가 혼자 쓰려고 만든 개인 플러그인이다. 누구나 참고·포크·설치할 수 있게 MIT로 공개하지만 범용 제품은 아니다. 표면과 규칙은 소유자의 워크플로에 맞춰 바뀐다. 구조와 패턴(단일 패키지 MCP 서버, CLI 위임, 기록과 정리의 분리 등)을 참고 자료로 보기를 권한다.

한눈에

MCP 서버는 둘이다. 데몬의 streamable HTTP(127.0.0.1:8636/mcp, 보드 도구 5개 + 토큰 도구 2개)와 CLI의 stdio 서버(rocky mcp worklog, 워크로그 도구 4개)다. 워크로그는 프로젝트별이라 세션의 cwd를 아는 CLI가 연다. 작업 폴더 밖에서 서버를 띄우는 호스트(Antigravity)는 rocky mcp worklog --roots로 띄워 클라이언트가 알려 주는 MCP roots를 프로젝트로 쓴다.

stdio 서버는 rocky 채널도 겸해, 데몬이 본 PR 전이(머지 후보·충돌)를 그 PR을 구독한 세션에 알린다. 채널 알림은 claude --dangerously-load-development-channels plugin:rocky@rocky-marketplace로 띄운 세션만 받는다(docs/board.md "PR 감시").

Claude Code 플러그인은 plugin/.claude-plugin/plugin.json의 mcpServers로 두 서버를 붙이고, Codex와 opencode는 직접 등록해서 쓴다. Antigravity(agy)는 레포의 antigravity/ 번들을 agy plugin install로 깔아 쓴다. 보드 데몬의 설치·CLI·설정·핸드오프는 docs/board.md에 있다.

MCP 도구 표면

각 도구의 입출력과 부수 효과는 별도 문서가 아니라 도구 정의 자체에 있다. crates/rockyd/src/mcp.rs(보드)와 crates/rocky-cli/src/worklog_mcp.rs(워크로그)의 #[tool] 정의를 읽으면 된다.

Claude Code 전용 표면 (MCP 도구 아님)

아래는 Claude Code 플러그인으로 설치했을 때만 붙는다.

• 슬래시 커맨드 (plugin/commands/)
  • /rocky:next: 보드에서 다음 작업을 골라 착수한다.
  • /rocky:brainstorm: 아이디어를 설계로 다듬는다. 게이트가 아니라 필요할 때 부르는 도구다.
  • /rocky:review-request: 게이트 → 커밋 → 푸시 → PR 생성까지 한다.
  • /rocky:spec-check: 구현이 요구사항대로 됐는지만 본다. 요구사항 원문(인자·대화·보드 할 일·스펙 문서·이슈)을 모아 reviewer에게 diff와 함께 넘기고, 항목마다 충족·빠짐·다르게 해석·요청 안 한 것으로 판정받는다. 버그는 기본 /code-review 몫이다. /rocky:review-request가 위험한 변경일 때 부르고, 작업 중간이나 다른 호스트에 넘긴 일이 돌아왔을 때 따로 불러도 된다.
  • /rocky:review-fix: PR에 붙은 리뷰를 반영한다. 스레드에는 리액션(🚀 수정 완료 / 👀 결정 필요)으로 상태만 남기고, 코멘트·resolve·머지는 사람이 한다.
  • /rocky:config: 설치·설정을 점검하고 빠진 것을 하나씩 물어 채운다.
  • /rocky:usage: 사용 로그를 읽고 뺄 것·손볼 것·더 쓸 것을 제안한다. 판단은 사람이 한다.
  • /rocky:recall: 워크로그를 다이제스트(kind:"digest")로 증분 정리한다. 기록의 짝인 정리(整理) 레이어다.
• 웹 UI (http://127.0.0.1:8636/): 피드·보드·항목 상세(마크다운·댓글·타임라인)·노트·작업로그·GitHub·에이전트·원격 제어 탭. 에이전트 탭은 claude agents가 보는 세션을 사람 답을 기다리는 것(background blocked, Claude가 남긴 "기다리는 것" 한 줄과 함께) → 실행 중 → 쉬는 중으로 보이고, 끝나지 않은 세션에는 로컬 화면에서 한 줄 메시지를 보낼 수 있다(받은편지함으로 — 받는 쪽에는 다른 세션의 메시지로 보인다). 살아 있는 background 세션은 멈추기(로컬 화면만, claude stop — 대화는 남는다), background 행에는 claude attach <id> 복사 버튼이 있다. 보던 탭은 주소(?view=)에 남아 새로고침해도 유지된다. 늘 곁에 둘 노트는 rocky note pin REF나 웹의 📌로 고정한다. web/의 React 앱을 릴리스 때 dist/로 번들해 tarball에 넣고 데몬이 서빙한다. 자세한 내용은 docs/board.md "웹 UI".
• TUI (rocky tui [--board K]): 같은 보드를 터미널에 — cmux 에서 Claude Code 옆 패널에 띄워 두는 용도(웹 패널을 오가는 멈칫이 없다). 위에서부터 "지금"(전 보드의 내 차례·돌고 있음) → 보고 있는 보드의 섹션별 트리. j/k 이동, Enter 상세(100열 이상이면 목록 옆에 늘 보인다), s 착수 · x 멈춤 · d 완료, a 빠른 추가, [ ] 보드, q 끝. 바뀐 것은 SSE 로 바로 반영된다. 실행 파일 옆 tui.js(릴리스 tarball 에 들어 있다)를 bun 으로 띄우므로 bun 이 있어야 한다. 노트·피드·작업로그 같은 나머지 화면은 웹 UI 에 있다.
• 맥 앱 (mac/, Swift · SwiftUI): 메뉴 막대에 돌고 있는 일(전 보드)과 머지 후보 PR 을 늘 띄우고, 할 일 창에서 보드를 골라 섹션별 열린 할 일을 보며 착수 · 멈춤 · 완료 · 다시 열기 · 빠른 추가를 한다. 메뉴의 "에이전트" 칸과 화면 구석에 떠 있는 로키 아바타(돌 골렘 조각 그림을 관절로 움직인다)가 이 기기의 Claude Code 세션 상태를 알린다 — 사람 답을 기다리는 세션이 있으면 아바타가 껑충 뛰고 손을 흔들며 말풍선에 기다리는 것을 띄우고, 도는 세션이 있으면 팔을 들어 내리치고, 다 쉬면 주저앉아 잠든다. 메뉴의 "돌아다니기"를 켜 두면(기본) 일하는 동안 창 윗면을 걸어 다니고, 창 옆면을 기어오르고, 밟던 창이 사라지면 떨어지고, 가끔 튜브를 놓아 다른 창으로 건너간다. 두 번 누르면 웹 에이전트 탭이 열리고(말풍선은 누르면 닫힌다), 메뉴의 토글이나 오른쪽 클릭으로 숨긴다. 바뀐 것은 SSE 로 바로 반영된다. 머지 후보 알림 배너는 데몬이 이미 띄우므로 앱은 목록만 보인다. 만들기: mac/scripts/bundle.sh → mac/build/Rocky.app(macOS 14 이상, Xcode 또는 Swift 툴체인 필요). 서명할 인증서는 ROCKY_MAC_SIGN_IDENTITY=<키체인의 인증서 이름>(예: 자체 서명 인증서 rocky 면 ROCKY_MAC_SIGN_IDENTITY=rocky mac/scripts/bundle.sh) 으로 주고, 없으면 ad-hoc 으로 서명한다. 데몬 주소·actor 는 defaults write dev.minjun.rocky.mac daemonURL http://127.0.0.1:8636 · defaults write dev.minjun.rocky.mac actor <이름>(기본 logan). 릴리스 tarball 에는 아직 들어 있지 않다.
• 보드 패널 (plugin/hooks/board-panel/, Claude Code function hooks — early access): /rocky-board 로 세션 옆 패널에 이 폴더의 보드를 띄운다 — 저절로 열지는 않는다. 진행 중(▶)을 먼저, 그다음 할 일을 번호와 함께 보이고, 좁은 패널에서는 제목이 다음 줄로 내려간다(넘치면 패널에 포커스를 두고 스크롤). 읽기만 한다 — 착수·완료는 TUI·웹 UI·보드 도구로. 열려 있는 동안 5초마다 보드 히스토리의 새 행만 묻고 이 보드가 바뀌었을 때만 다시 읽는다(수집함 수는 60초마다). 닫으면 묻지 않는다. 원격 제어 세션에서는 앱이 붙을 때 명령을 등록하고, 아무 화면도 붙지 않는 -p 실행에서는 아무것도 하지 않는다.
• 업데이트: rocky update가 마켓플레이스 갱신 → 플러그인 → 데몬 교체를 한 번에 한다(--check는 버전 비교만). 릴리스 대신 GitHub main 을 이 기기에서 빌드해 쓰려면 rocky update --main [SHA] — git·cargo·bun 이 있어야 하고, 처음엔 플러그인 마켓플레이스를 이 기기의 main 폴더로 바꿔도 될지 묻는다. 그 뒤로 rocky update 는 main 최신으로 올리고, 릴리스로 돌아가기는 rocky update --release. 빌드 없이 CI 가 매일 밤(01:30 KST) 낸 main 의 nightly 프리릴리스(v<버전>-nightly.<YYYYMMDD>)를 받아 쓰려면 rocky update --nightly [TAG] — git·curl·claude 만 있으면 되고, 마켓플레이스는 --main 과 같은 폴더로 바꾼다(처음이면 묻는다). 그 뒤로 rocky update 는 최신 nightly 로 올린다. statusline은 rocky statusline이 그린다 — 경로·git 줄과 모델·ctx·한도 줄(docs/board.md "statusline").
• 제거: rocky uninstall 이 플러그인·마켓플레이스, launchd job(plist), 떠 있는 데몬, ~/.local/bin/rocky 링크, ~/.local/share/rocky(바이너리·main 빌드)를 걷어낸다. 먼저 목록을 보여 주고 확인을 받는다(--yes 로 생략, --dry-run 은 목록만). 설정·보드·워크로그·사용 로그(~/.config/rocky)는 남겨 다시 깔면 이어지고, --purge 를 붙일 때만 지운다. rc 서버의 claude 세션·tailscale serve·statusLine 설정은 건드리지 않고 정리할 곳만 알려 준다.
• 버전 표시: 버전 오른쪽 괄호에 빌드한 커밋의 짧은 해시(7자)가 붙는다 — 웹 하단 rocky v0.49.0 (abc1234), rocky version, rocky daemon status, rocky doctor 의 데몬 줄, /api/health 의 commit. 해시는 release 빌드에만 들어간다(릴리스 tarball · main 빌드는 붙고, cargo build debug 는 버전만).
• 수집함 CLI: rocky inbox [--json]이 소스별 항목을 보여 준다(✓는 이미 어느 보드든 올라간 것). rocky today와 세션 시작 요약은 아직 안 올린 항목을 최대 3개 싣는다. 세션에 "gh-bugs 구독해"라고 하면(rocky inbox subscribe) 그 뒤 새 항목을 데몬이 그 세션에 알린다. 착수는 사람이 정한다(docs/board.md "요약").
• 훅 (plugin/hooks/hooks.json): SessionStart가 데몬을 띄우고(버전이 다르면 재기동), UserPromptSubmit이 사람이 보드에서 바꾼 것을 세션에 알리고, PostToolUse가 세션이 todo_status 로 스스로 시작한 할 일에 그 세션을 귀속시키고(턴 태그용 — Stop 의 "닫았나?" 확인은 핸드오프로 받은 것에만), Stop이 핸드오프를 집은 뒤 턴을 워크로그에 자동으로 남긴다(kind:"turn", LLM을 쓰지 않는다, worklog.autoCapture로 끈다). 모든 훅은 실패해도 세션을 막지 않는다.
• 스킬 (plugin/skills/): rocky 를 쓰는 에이전트가 상황에 맞을 때 읽는 문서다(평소엔 컨텍스트를 쓰지 않는다). pull-request는 PR 구독과 받은편지함 메시지별 할 일, token-usage는 모델·effort 고르기, branch-verify는 기본 브랜치 검증 결과 읽기, handoff는 보드에서 넘겨받은 일의 start→done, worklog는 무엇을 언제 기록하나를 다룬다. rocky 를 고치는 에이전트용 기능 문서는 레포의 docs/features/에 따로 있다. board는 보드 에티켓(start→done, 링크 첨부, 보관만)과 MCP·CLI 폴백을, writing-cc-plugin은 Claude Code 플러그인 작성 가이드와 매니페스트·컴포넌트·배포 레퍼런스를 담는다.
• 서브에이전트 (plugin/agents/): reviewer는 새 컨텍스트에서 diff와 요구사항만 받아 검토하는 읽기 전용 리뷰어다. /rocky:spec-check이 요구사항 대비 점검으로 띄우고(버그 찾기는 기본 /code-review), "리뷰해줘"처럼 직접 부를 수도 있다. 돌려 본 것만 통과라고 쓰고, 통과처럼 보이는 실패(false pass)를 따로 챙기며, 파일을 고치거나 머지하지 않는다. quick-fix(Sonnet)와 merge-cleanup(Haiku)은 /rocky:review-fix의 기계적인 단계 — 충돌 해소·판단이 필요 없는 리뷰 수정·CI 실패, 머지 뒤 정리 — 를 가벼운 모델과 새 맥락에서 맡는다. 긴 세션이 몇 줄짜리 손질을 위해 대화 전체를 요청마다 다시 읽지 않게 하려는 것이다. 둘 다 강제 푸시·-D·코멘트·resolve·머지를 하지 않고, 판단이 필요한 건은 메인 세션에 돌려준다.

토큰 사용 — 모델·effort 고르기

데몬이 Claude Code 세션 트랜스크립트(~/.claude/projects/**/*.jsonl)를 1분마다 읽어 응답마다의 모델·effort·토큰·도구 호출을 logs.db에 쌓는다. 첫 바퀴가 과거 트랜스크립트 가져오기를 겸하므로 따로 가져올 명령이 없다. 훅 설정은 필요 없다. 토큰은 훅 입력에 아예 없고 모델은 SessionStart에만 실리지만, 트랜스크립트에는 줄마다 둘 다 있다. 그래서 세션 쪽에 붙는 것이 없고, 데몬이 꺼져 있어도 Claude Code는 늦어지지 않는다.

rocky tokens                       # 최근 30일, 모델 × effort 별 세션·턴·요청·턴당 출력·토큰·도구 호출
rocky tokens --since 7d --by branch   # model · effort · session · branch 로도 묶는다
rocky tokens here                  # 이 디렉터리의 최근 세션 — 턴별 모델·effort·토큰, effort 변경, 추천

추천은 규칙 네 가지다(최근 15턴, 5턴 미만이면 판단하지 않음). ① 턴 평균 출력이 3,000토큰 이하인데 effort가 xhigh/max면 medium을 권한다. ② 창 안에서 effort를 올린 뒤 턴이 길어졌으면 이미 조정한 것으로 보고 추천하지 않는다. ③ Opus인데 도구 호출이 0이고 출력이 짧으면 Sonnet medium을 권한다. ④ 맥락(요청당 캐시 읽기)이 20만 토큰 이상인데 턴 평균 출력이 1만 토큰 이하면 — 긴 맥락을 요청마다 다시 읽으며 조금씩 쓰는 중이다 — 기계적인 후속(리뷰 반영·머지 뒤 정리)은 새 세션이나 가벼운 서브에이전트로 넘기라고 권한다. 긴 세션의 비용은 대부분 출력이 아니라 이 캐시 읽기다. 모델 전환은 다음 작업 경계(커밋 직후)나 새 세션에서 하라고 권한다 — 모델을 바꾸면 쌓인 캐시를 못 쓰고 새로 쌓는다(effort 변경은 캐시를 지킨다). 수치와 규칙 on/off는 rocky.json의 tokens.recommend로 바꾼다.

기본 브랜치 검증

여러 워크트리에서 PR을 연달아 머지하면 "머지된 main이 여전히 초록인가"를 누군가 다시 봐야 한다. 데몬이 그 일을 한다 — rocky.json의 verify.targets[]에 보드와 단계를 적으면, 원격 브랜치를 git ls-remote로 보다가(GitHub API 예산을 쓰지 않는다) 새 커밋이 들어오면 전용 워크트리(<todo dir>/verify/<board>/<branch>/tree, detached — 사람·세션의 작업 트리와 브랜치를 건드리지 않는다)에서 단계를 차례로 돈다. 한 번에 하나만 돌고, 도는 사이 커밋이 몰리면 최신 하나만 본다. 실패와 복구(실패 → 통과)만 macOS 배너로 알린다.

"verify": { "targets": [ { "board": "rocky", "steps": [
  { "name": "install", "command": ["bun", "install", "--frozen-lockfile"] },
  { "name": "check", "command": ["bun", "run", "check"] },
  { "name": "cargo-test", "command": ["cargo", "test", "--workspace"] }
] } ] }

rocky verify(또는 GET /api/verify)가 대상마다 마지막 결과를 보여 준다 — 실패면 단계·이유·로그 파일. 명령은 설정 파일에만 있다(화면·REST가 바꾸지 않는다). 데몬이 빌드·테스트를 돌리므로 머신이 그만큼 바빠지고, 전용 워크트리의 빌드 산출물(target/·node_modules/)이 <todo dir>/verify/ 아래에 남는다(대상마다 로그는 최근 10개만). 보드 레포의 git 훅은 돌리지 않는다.

실패하면 그 자리에서 한 번 더 돌고, 두 번 연속 실패일 때만 실패로 기록하고 알린다 — 진짜 실패는 그만큼 늦게 알게 되고, 두 번째에 통과하면 rocky verify가 "통과(다시 돌려서)"로 보여 준다. 그 뒤로 같은 커밋의 실패는 다시 돌지 않는다. 머신이 바빠 테스트가 시간 초과로 떨어진 것처럼 커밋 탓이 아닌 실패라면 rocky verify --rerun [보드](또는 로컬에서 POST /api/verify/rerun, 본문 board·branch)로 지금 커밋을 바로 다시 돌린다 — 보드를 안 주면 대상 전부, 도는 중인 대상은 건너뛴다. 실행 이력은 대상 디렉터리의 runs.jsonl에 쌓인다 — 끝난 실행(통과·실패 — 자동 재시도 전의 첫 실패도, 두 번째 시도면 attempt: 2, 다시 돌린 것이면 rerun)과 끊긴 실행, 검증을 못 한 이유(원격을 못 읽음·준비 실패, 같은 이유가 이어지면 한 번만)를 한 줄씩.

결과를 기다리는 세션(배포 등)은 세션 안에서 rocky verify subscribe [보드] [--branch B] 로 구독하면 끝난 실행마다(통과도) 받은편지함으로 한 줄을 받는다 — 같은 커밋은 한 번, 다시 돌려 결과가 바뀌면 다시. 대상마다 세션 하나(다시 구독하면 넘겨받는다)이고 rocky verify unsubscribe·rocky verify subscriptions 로 해지·조회한다. /clear 뒤의 구독은 웹 "세션 전달" 카드에서 PR·수집함 구독과 같이 정한다.

main 빌드 모드 기기(rocky update --main)에서는 rocky 보드의 main 대상에 "deploy": true 를 더하면 통과한 커밋을 데몬이 직접 rocky update --main <sha> 로 올린다. 배포를 맡을 세션이 따로 필요 없다. 깔린 빌드보다 앞선 커밋만 올리고, 같은 커밋은 성공이든 실패든 한 번만 올린다(실패한 커밋은 고친 커밋이 통과할 때까지 그대로다). 다른 rocky update --main 이 도는 중이면 끝나기를 기다린다. 실패(90분 안에 끝나지 않은 것도)만 배너로 알리고, rocky verify 가 대상 아래에 배포 한 줄(도는 중 · 올린 커밋과 시각 · 실패 이유와 로그)을 보여 준다. 이 대상을 구독한 세션에는 통과 알림이 "데몬이 배포한다"로 간다. 낮에 데몬·플러그인이 바뀌지 않게 밤에만 올리려면 그 대상에 "deployWindow": { "from": "02:00", "until": "04:00" } 을 더한다(이 기기의 현지 시각, 칸을 빼면 그 값이 기본). 창 밖에서 통과한 커밋은 다음 창이 열릴 때 그때의 마지막 통과 커밋으로 한 번에 올라간다. 바꾼 설정은 rocky daemon restart 뒤에 적용된다. update 는 데몬의 PATH(rocky daemon install 때 구운 것)에서 git · cargo · bun · claude 를 찾는다.

rc 서버 현황

사용자 설정(~/.config/rocky/rocky.json)의 rc 블록에 폴더를 적으면 데몬이 폴더마다 떠 있는 claude rc(Remote Control) 서버를 그 목록과 맞대어 보여 주고, 사람이 부르면 띄우거나 다시 띄운다. supervise 를 켜면 꺼진 고정 서버를 스스로 되살린다(설계). 띄울 때마다 그때 설치된 claude 버전을 rc/<라벨>.version 에 남긴다(야간 재시작이 구버전을 가리는 기록).

웹 UI에서는 피드 머리 아래 한 줄(원격 제어 7/13 · 세션 4)과 원격 제어 탭으로 본다(⋯ 메뉴에서 탭을 끌 수 있다). rc 블록이 없거나 enabled: false면 둘 다 없다.

Antigravity 원격 제어(agy remote-control)는 rc 블록과 상관없이 그 기기에 agy가 있으면 보이고, 켜고 끌 수 있다 — rc 블록이 없는 기기에서는 원격 제어 탭에 Antigravity 줄만 나온다. 켜기·끄기는 이 기계의 원격 접속 데몬을 바꾸므로 로컬 요청만 된다(폰·테일넷 화면에는 버튼이 없다).

rocky rc                         # 현황 표(이름 · 고정 · 떠 있음 · 세션 · 메모), 핸드오프 · 대상 밖 서버, 감시 · 야간 · Antigravity
                                 # 로그아웃 같은 기기 전체 문제는 맨 위 ⚠ 에 한 번 — 푸는 법까지(새 로그인이 키체인 대신 파일로 갔으면 그렇다고)
rocky rc help                    # 아래 옵션 전부
rocky rc start repo-a --wait     # 꺼진 대상을 서버만 띄운다(세션은 앱에서 — 새 세션과 함께면 --new-session)
rocky rc restart repo-a --wait   # 다시 띄운다 — 열린 세션이 있으면 그 세션을 이어받기(가장 최근에 대화한 것, --session-id), --fresh 나 워크트리 대상이면 새로. 붙은 원격 세션은 끊긴다
                                 # 막 대화하는 중이면 턴이 끝날 때까지(최대 10분) 기다렸다 내린다
                                 # 이 세션이 붙은 서버는 거절한다(재시작이 이 턴을 끊는다 — 웹이나 다른 세션에서)
rocky rc restart repo-a --session cse_…  # 이어받을 세션을 claude.ai 쪽 id 로 못 박는다
rocky rc --activity              # 대상마다 최근 활동(마지막 커밋 · *작업중 · @곁가지), 꺼진 비고정 중 오래 조용한 것은 정박
rocky rc start --all             # 꺼진 대상 전부를 서버만 — 비상용
rocky rc agy                     # Antigravity 원격 제어 상태 한 줄
rocky rc agy stop                # agy remote-control stop(정지 + 등록 해제) — start 는 등록 + 기동
rocky rc nightly --dry-run       # 야간 재시작 리허설 — 지금 설치 버전으로 서버마다 무엇을 할지(손대지 않는다)
rocky rc nightly                 # 야간 재시작을 지금 한 번(백그라운드) — 결과는 rocky rc 의 "야간:" 줄
rocky rc stop rocky-41           # 새 세션 띄우기가 띄운 핸드오프 서버를 닫는다(할 일 참조로, pid 로만 — 워크트리는 남는다)
rocky rc stop cc-usage           # 대상 밖 서버를 닫는다(폴더 이름이나 pid 로 — 설정 대상은 닫지 않는다)
rocky rc report                  # 마지막 야간 보고 — 서버마다 결과, rocky 세 층 버전 · 최신 태그, agy(읽기만이라 확인 규칙에 안 걸린다)
rocky rc targets                 # rocky.json 의 대상 목록(이름 · 고정 · 폴더). 없는 폴더 · 겹친 이름은 ⚠
rocky rc targets add ogpeek      # 대상을 더한다(맨 이름은 root 아래, . 은 지금 폴더, --pin 은 고정). 데몬이 바로 다시 읽는다
rocky rc targets rm ogpeek       # 대상을 뺀다. 떠 있던 서버는 대상 밖 서버로 남는다(닫으려면 rocky rc stop)
rocky rc targets unpin ogpeek    # 고정을 푼다. 대상으로 남고 떠 있는 서버도 그대로다(감시가 고정으로 되살리지 않는다)
rocky rc reload                  # 데몬이 대상 목록을 지금 다시 읽고 무엇이 바뀌었는지 알린다(손으로 고친 파일은 알아서 읽는다)

대상 목록 고치기: rocky rc targets add|rm|unpin 은 사용자 rocky.json 의 rc.pinned · rc.targets 를 고치고 떠 있는 데몬이 바로 다시 읽게 한다. 적는 이름은 가장 짧은 꼴(root 아래면 맨 이름, 홈 아래면 ~/…)이고, 이 기기에 없는 폴더나 이름(폴더 이름)이 같은 다른 폴더는 거절한다. unpin 은 적힌 이름을 그대로 일반 대상으로 옮긴다. 파일의 키 순서와 들여쓰기 단위는 그대로 두지만 한 줄로 적은 배열은 여러 줄로 펴진다. 손으로 고친 파일은 데몬이 다음에 설정을 볼 때(현황 · 띄우기 · 감시) 파일이 바뀐 것(mtime · 크기 · inode)을 보고 알아서 다시 읽는다. 바로 반영하고 무엇이 바뀌었는지 보려면 rocky rc reload. 데몬을 다시 띄우지 않고 바뀌는 것은 대상 목록(root · pinned · targets · worktree)뿐이다. enabled · supervise · nightly 는 rocky daemon restart 뒤에 반영된다(명령이 알려 준다). 파일이 JSON 이 아니면 데몬은 하던 목록을 그대로 쓴다.

워크트리 모드(rc.worktree — pinned · targets 에 적힌 폴더 중에서 고른다): 그 대상의 서버를 claude rc --spawn worktree 로 띄워, 앱이나 claude.ai 프로젝트가 그 폴더에 여는 세션마다 제 git 워크트리(.claude/worktrees/)를 받는다 — 같은 폴더에 세션이 여럿 떠도 작업 트리를 나눠 쓰지 않는다. 기본은 꺼짐이다 — 세션마다 고르려면 이 설정 없이 그 세션에 워크트리를 청한다("워크트리에서 해 줘" — Claude Code 의 EnterWorktree 가 .claude/worktrees/ 에 워크트리를 따서 그 세션만 옮겨 간다). 이 설정은 그 폴더의 세션을 전부 나눌 때 쓴다. 폴더는 git 레포 루트로 고른다 — git 레포가 아니면(WorktreeCreate 훅도 없으면) claude 가 뜨지 않고, 하위 폴더면 워크트리가 레포 루트에 생겨 rocky 가 그 대화를 못 본다. 재시작은 열린 세션을 이어받지 않고 새로 띄운다 — 이어받기(-c · --session-id)는 세션 하나만 받는 모드라 워크트리와 같이 쓸 수 없다(사람이 --session 으로 고르면 그 세션만). 목록에서 뺐어도 떠 있는 서버가 아직 워크트리 모드면 마찬가지다(세션이 제 워크트리에서 돈다). 재시작 · 야간이 기다리는 "대화 중" 판정은 목록과 상관없이 그 폴더 워크트리의 대화 기록까지 본다(세션이 청해 딴 워크트리도 보고, rocky 핸드오프의 todo-<번호> 는 뺀다). 목록을 고치면 데몬이 바로 읽지만 떠 있는 서버는 rocky rc restart <이름> 으로 다시 띄워야 바뀐 모드로 뜬다 — 그때까지 rocky rc 가 워크트리(다시 띄우면 켜짐) · 워크트리 끔(다시 띄우면 꺼짐) 으로 보인다. 대상이 아닌 이름(오타)은 무시되고 rocky rc targets 가 ⚠ 로 알린다. 대상을 빼면(rocky rc targets rm) 워크트리 목록에서도 빠진다.

"rc": {
  "pinned": ["rocky"],
  "worktree": ["rocky"]  // 이 폴더에 열리는 세션마다 제 워크트리
}

서버는 데몬과 다른 프로세스 그룹으로 띄워 데몬을 재시작·업데이트해도 살아 있다. 재시작은 SIGTERM 뒤 20초를 기다리고, already served(claude.ai 쪽 등록이 남음)면 60초·120초 뒤 다시 띄운다. 기동 로그와 이벤트는 todo 폴더의 rc/(<라벨>.out · .err · events.jsonl)에 남는다.

감시("supervise": true, 기본 꺼짐): 데몬이 2분마다 고정 서버를 보고 꺼져 있으면 스스로 띄운다(비고정은 띄우지 않는다 — 단 야간 재시작이 내리고 못 띄워 되살림 표식 rc/<라벨>.revive 가 남은 것은 서버만 띄우고 표식을 지운다). 연달아 못 뜨면 2분부터 30분까지 쉬었다 다시 해 본다. 데몬 맥락(launchd 면 키체인)의 claude 자격이 끊기면 macOS 배너를 한 번 띄우고 그동안은 띄우지 않으며, 돌아오면 다시 한 번 알리고 끊기기 전에 뜬 서버를 "자격 의심"으로 표시한다(다시 띄우기를 권한다). 자격 기록은 rc/auth.json.

야간 재시작("nightly": {} — 블록이 있으면 켜진다, 기본 꺼짐): 매일 at(기본 04:30, 이 기기 현지 시각)에 claude update 를 돌리고, 기동 때 남긴 버전(rc/<라벨>.version)이 설치 버전과 다르면서 쉬는 서버만 다시 띄운다(열린 세션을 이어받지 않고 서버만). 고정이 아니고 열린 세션 없이 48시간 넘게 안 쓰인 서버(핸드오프 서버 포함)는 다시 띄우지 않고 내린다 — 필요하면 rocky rc start <이름> 으로 다시 연다. 쉬는 서버는 열린 세션이 없거나 그 폴더(와 그 워크트리) 대화 기록이 quietMinutes(기본 60분) 넘게 안 바뀐 것이다. 고정 하나를 먼저 내려 띄워 보고, 뜬 뒤에야 나머지를 내린다. 내리기 직전마다 네트워크를 확인한다. 바쁜 서버는 busyUntil(기본 07:00)까지 5분마다 다시 본다. 내렸는데 못 띄운 것은 그때까지 다시 띄워 보고, 그래도 안 되면 되살림 표식(rc/<라벨>.revive)을 남겨 감시가 서버 모드로 띄운다 — 감시와 함께 켠다. 맥이 그 시각에 자고 있었으면 깬 뒤 한 번 돈다(rc/nightly.json). 처음 켠 날 낮에는 돌지 않는다. 못 띄운 서버가 있을 때만 배너를 띄운다. 보고에는 rocky 세 층(플러그인 · CLI · 데몬)의 버전과 최신 릴리스 태그, agy 버전과 원격 제어 데몬(상태 · pid · 기동 시각, 업데이트 전 바이너리로 도는지)도 남는다 — 설치 · 재시작은 하지 않는다(rocky 를 올리는 건 rocky update). 기록은 todo 폴더의 rc/events.jsonl(nightly-* 이벤트)과 rc/nightly.json(마지막 보고).

Cloudflare Access 로 원격 제어(access 블록 — 기본 꺼짐): 원격 제어 탭의 서버 띄우기 · 재시작 · 닫기 · 야간 실행은 로컬 요청 전용이지만, 사용자 rocky.json 에 아래를 두면 Access 로 로그인한 허용 이메일에게도 열린다. 데몬이 Cf-Access-Jwt-Assertion 을 팀 공개키(https://<team>.cloudflareaccess.com/cdn-cgi/access/certs, 1시간 캐시)로 검증하고 aud · 발급자 · 만료 · 이메일을 모두 맞춰 본 요청만 받는다 — 헤더 이름만으로는 믿지 않는다. 이슈 만들기 · 새 세션 띄우기 · Antigravity 켜기 · 끄기 같은 다른 로컬 전용 동작은 그대로 로컬만이다. 데몬을 다시 띄워야 적용된다. 터널 설정은 docs/board.md의 "밖에서 닿기".

"access": {
  "team": "<팀 이름>",            // <team>.cloudflareaccess.com
  "aud": "<Access 앱의 AUD 태그>",
  "emails": ["you@example.com"],  // 비면 아무도 열리지 않는다
  "remoteControl": true
}

새 세션 띄우기(rocky spawn REF, 웹은 할 일 상세의 "에이전트에게 보내기" 패널 첫 대상 "새 세션", 로컬 전용): rc 가 켜진 기기에서는 데몬이 그 할 일의 워크트리(<보드 경로>/.claude/worktrees/todo-<번호>, 없으면 origin 기본 브랜치에서 딴다)에 단일 세션 rc 서버(<보드>-<번호>: <제목 앞부분>)를 띄우고, 그 세션에 핸드오프를 넣어 깨운다 — 폰 · 웹의 원격 제어 목록에서 그 이름으로 이어 본다. 할 일당 서버 하나이고, 서버는 저절로 내려가지 않는다 — 세션이 끝났다고 알리면 사람이 닫는다(rocky rc stop <할 일>, 감시는 건드리지 않고 야간은 열린 세션 없이 48시간 안 쓰인 것만 내린다). rocky rc 에는 "핸드오프:" 로 따로 보인다(띄울 때 남긴 기록 rc/handoff/<라벨>.json 과 pid · 폴더가 맞는 서버). rc 가 꺼진 기기는 claude --bg 로 띄우는데, 그 세션은 로그인 세션 밖에서 돌아 ssh · 자격이 끊길 수 있어 응답에 경고가 붙는다. 자세한 규칙은 docs/board.md의 spawn 절.

에이전트가 부를 때의 확인: 서버를 바꾸는 명령은 사용자 설정(~/.claude/settings.json)의 permissions.ask 로 사람 확인을 받는다 — "Bash(rocky rc start:*)", `"