Note: This page is reproduced verbatim from the project's Korean-language source documentation. No English version of this document exists in the source repository yet — only the top-level README has an English translation.
User Manual: Fleet Operations
5. AI 함대 운용#
5.1 역할과 주소#
cys identify # 나는 누구인가 (surface ref)
cys claim-role worker # launch-agent 없이 시작한 세션을 역할로 등록
cys surface-role # 데몬이 알고 있는 내 역할 1단어 출력5.2 노드 기동#
cys launch-agent --role worker --agent claude # surface 생성 + CLI 기동 + 절대지침 자동 주입 + 역할 등록
cys boot # 표준 노드 세트 일괄 기동(설치된 CLI 자동 감지)launch-agent는 ①surface 생성(CYS_ROLE 주입) ②에이전트 CLI 기동 ③역할 절대지침 stdin
주입 ④역할 레지스트리 등록을 한 번에 수행합니다. 어댑터 정의는 팩의 agents.json에
있습니다(claude·gemini·codex·grok).
5.3 메시지 보내기#
cys send --to worker "상태 보고해줘" # 대상 PTY stdin에 직접 주입 (타이핑만)
cys send-key --to worker Return # 전송 확정 (send 후 필수)
cys send --queued --to worker "..." # followup 큐: 대상이 조용해지면 자동 배달(Return 불필요)- 기본 send = steer(즉시 주입 — 실행 중 조향).
--queued= followup(대상이 3초 이상 조용할 때 한 틱에 한 건씩 배달). - 타이핑 가드: 사람이 방금 타이핑 중인 pane에는 기계 주입이 거부됩니다(기본 3초).
5.4 관제·이벤트#
cys status --json # 전 노드 1콜 스냅샷 (폴링 대체)
cys fleet # 모든 부서×노드의 현재 업무
cys events --reconnect # 이벤트 푸시 구독 (seq 이어받기)
cys read-screen --surface surface:3 # 화면 읽기 (vt100 정확) — 보조 수단
cys watch --surface surface:3 --until "DONE" # scrollback이 regex에 맞을 때까지 대기read-screen --since N은 단조 라인 커서로 델타만 읽습니다.
5.5 자기보고 (권장 규약)#
에이전트는 화면 파싱 대신 스스로 신고합니다:
cys set-status --state working --context 57 --task "리팩토링 중"컨텍스트%가 임계(기본 60%)에 닿으면 데몬이 context.threshold 이벤트로 통보합니다.
5.6 컨텍스트 사이클·복구#
cys cycle-agent --role worker # 저장 지시 → 파일 게이트 → clear → 지침 재주입 → 재개
cys node-recover --role worker # 죽은 에이전트를 같은 surface에서 재기동+재주입
cys restore [--include-master] # 토폴로지 스냅샷의 죽은 역할 일괄 복원
cys reinject --role worker [--check] # 디렉티브 재주입 (--check: 드리프트 감지 후 필요 시만)에이전트 사망은 즉시 감지되어 agent.exited/recovered 이벤트가 흐르고, 옵션으로 자동
재기동(CYS_AGENT_AUTORESTART=1, 3회 상한·인증 오류 시 차단)이 가능합니다.
5.7 역할별 TODO 경로#
cys todo-path # 이 surface 역할 전용 TODO 파일 경로를 결정론으로 산출(없으면 생성)6. 승인 Feed와 승인 서명#
6.1 Feed — 승인 요청함#
cys feed push --wait --title "git push 승인" --body "..." # 결정까지 블록. exit 0=allow, 2=deny, 3=timeout
cys feed list --status pending
cys feed reply <request_id> allow # CLI로 응답 (UI Allow/Deny 버튼과 동일)- 에이전트 훅 연동 예: PreToolUse 훅에서
cys feed push --wait ...를 호출하고 exit code로 결정을 반영. - pending이 오래 방치되면
feed.item.aging이벤트로 재알림됩니다(기본 300초). - 자동 응답은 없습니다(HITL). 요청한 노드가 스스로 승인하는 것도 데몬이 거부합니다.
- UI: 승인 요청이 오면 배지·토스트·OS 알림이 뜨고, 30초 내 해소되지 않은(=사람 개입이 필요한) 건만 Feed 탭으로 화면이 전환됩니다.
6.2 승인 서명 — 반복 위험 명령의 사전 허가#
cys approval sign # (master 전용) 위험 명령 prefix를 HMAC 서명 — 이후 guard 훅 자동 통과
cys approval check # 서명 유효성 확인7. 자원 거버넌스#
에이전트가 남긴 고아 서버로 시스템이 마비되는 것을 막는 1급 기능입니다.
cys run --scoped -- python -m http.server # 새 프로세스 그룹+원장 등록. 종료 시 그룹째 강제 정리
cys ps # 프로세스 원장
cys kill <pid> # 원장 등록 프로세스(그룹) 종료
cys add-health-rule relogin "Not logged in" # 출력 라인 헬스룰 추가 → health.alert
cys health-rules- watchdog(5초 주기): load 폭주·프로세스 수·중복 명령·idle(기본 300초 무출력)·에이전트
사망·좌비를 감시해 이벤트를 발행합니다. 중복 프로세스 자동 kill은 opt-in
(
CYS_AUTOKILL_DUP=1, 최고(最古) 프로세스 보존). - 기본 헬스룰: 로그인 풀림·401·token expired·rate limit (30초 디바운스).
- 헬스룰에 조치를 묶을 수 있습니다(opt-in):
--action pause-queue— queued 배달만 일시정지.
kill-switch#
cys pause # 큐 배달·스케줄 발화 동결 (직접 send는 통과 — '신경 차단')
cys resume
cys gate-check # exit 0=running, 4=paused (자율주행이 매 action 전 확인)
cys queue list / clear # 미배달 큐 검사·철회pause 상태는 재부팅에도 유지됩니다.
8. 스케줄러#
cys schedule add --id wake --in 20m --text "[wakeup] 다음 액션 착수" --to master # 원샷(발화 후 자동 삭제)
cys schedule list / remove <id> / run <id>- 반복 잡은 팩의
schedule.json으로 정의됩니다(30초 tick·missed-fire 처리) — 기본으로 진행 보고·비용 다이제스트·채널 헬스 잡이 들어 있습니다. --fresh --agent claude: 매 발화마다 새 surface를 띄워 과업을 주입(권한·컨텍스트 상속 차단),--close-after로 TTL 정리.
Continue: Control Center → · Back: Getting Started