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: Getting Started

cys-terminal User Manual (사용자 매뉴얼)#

설치부터 AI 함대 운용, 전체 레퍼런스까지. (v0.12.x 기준) 무엇을 왜 이렇게 만들었는지는 Architecture & Philosophy를 보세요.

목차 (Table of Contents)#

1. Getting Started (this page) — §1 Overview & terms · §2 Install · §3 First run · §4 Terminal UI
2. Fleet Operations — §5 AI fleet ops · §6 Approval Feed · §7 Resource governance · §8 Scheduler
3. Control Center — §9 Control Center · §10 Skill Board
4. Updates & Pack Operations — §11 Updates · §12 CYSJavis pack operations
5. Reference — §13 Channel bridge · §14 Recall/attest · §15 CLI reference · §16 Env vars · §17 Protocol reference · §18 Troubleshooting

1. 개요와 용어#

핵심 그림: 앱이 아니라 데몬이 세션을 소유한다. 앱을 꺼다 켜도, 앱을 업데이트해도 세션은 살아 있고 앱은 다시 attach만 한다.

2. 설치#

Releases에서 받습니다. 데몬을 따로 설치할 필요가 없습니다 — 앱이 자동 기동하고 팩도 자동 설치됩니다.

2.1 macOS (Apple Silicon)#

1. cys_<버전>_aarch64.dmg를 열고 cys.app을 Applications로 드래그.
2. 첫 실행에서 Gatekeeper 경고가 뜨면: 공증된 빌드는 그대로 열리고, 아니면 우클릭 → "열기".
3. 앱이 데몬(cysd)을 자동 기동하고 launchd에 등록합니다(재부팅 후에도 유지).

2.2 Windows (x64)#

1. cys_<버전>_x64-setup.exe(NSIS) 실행 — 자기완결 설치: 데몬·CLI·런타임(Git Bash· Python)이 동봉되어 별도 준비물이 없습니다.
2. 앱을 1회 실행하면 온보딩이 자동으로 팩 설치·훅 등록·데몬 자동 기동(작업 스케줄러 ONLOGON)을 마칩니다.
3. 확인: dir %USERPROFILE%\.cys\pack · schtasks /Query /TN cysd
4. 상세(비기술자용 안내 포함): Windows install guide

2.3 데몬 상시 가동 (24/365, 선택)#

cys daemon install      # macOS launchd KeepAlive / Windows 작업 스케줄러 등록
cys daemon status
cys daemon uninstall

이미 데몬이 돌고 있으면 install은 안전하게 거부됩니다.

2.4 외부 터미널에서 cys 쓰기 (셸 설치)#

• 권장(macOS): 앱 Control Center 헤더 → "셸에 cys 설치" 1클릭(관리자 승인 1회) — /usr/local/bin/cys·cysd 심볼릭 링크가 생기고, 앱 업데이트에도 자동 추종합니다.
• Windows는 설치기가 PATH를 구성합니다.

2.5 설치 확인#

cys ping            # 데몬 응답 확인
cys identify        # 데몬·내 주소 확인
cys status          # 전 노드 관제 보드
cys doctor          # 자기진단 (문제 시 --fix)

2.6 제거#

1. cys daemon uninstall
2. 앱 삭제(macOS: Applications에서 제거 + 심링크 제거 / Windows: 제어판 제거)
3. 선택 — 데이터까지 완전 삭제(비가역): ~/.cys(팩·설정)와 ~/.local/state/cys(소켓· 관제 DB) 삭제. 장기기억·soul.md도 함께 사라지므로 백업 후 진행하세요.

상세: Install guide (macOS)

3. 첫 실행 — 자동 온보딩#

앱 첫 실행 시 자동으로 수행됩니다(멱등 — 다시 실행해도 안전):

• 데몬 자동 기동(꺸려면 CYS_NO_AUTOSTART=1) 및 상시 가동 등록
• 팩 설치(~/.cys/pack) — 이미 사용자가 수정한 파일(soul.md·디렉티브·CLAUDE.md· schedule.json)은 보존되고, 수정하지 않은 파일만 갱신됩니다
• Claude Code SessionStart 훅 등록(역할 지침 자동 주입용 — CYS_ROLE 세션에서만 발동)
• pane 프로세스에 CYS_SURFACE_ID·CYS_SURFACE_REF·CYS_SOCKET 자동 주입

4. 터미널 UI#

4.1 상단바#

+ New(⌘T) · Split →(⌘D) · Split ↓(⌘⇧D) · 정렬(역할 표준 배치) · Close(⌘W) · Files(파일 트리) · Control Center(승인 대기 배지) · Update(업데이트 배지) · 테마. 좌측에 데몬 연결 상태가 표시됩니다.

4.2 pane 분할·이동·정렬#

• 분할선을 드래그해 비율 조정.
• pane 헤더를 드래그해 다른 pane의 상/하/좌/우에 드롭 — 자유 재배치.
• 정렬 버튼: 역할 기반 표준 배치(좌측 master/CSO · 가운데 worker · 우측 리뷰어).
• pane 닫기(×)와 워크스페이스 삭제는 2-클릭 확인(첫 클릭 후 2.5초 내 재클릭)입니다.

4.3 워크스페이스 탭·그룹#

좌측 사이드바에서 워크스페이스를 전환합니다. 탭에는 pane 수·대표 제목·노드 상태·최악 컨텍스트%·승인 대기 ⚠ 배지가 표시됩니다. 탭은 드래그로 재정렬하고, 우클릭 메뉴로 그룹(접기·고정·색상·이름)을 만들 수 있습니다.

4.4 부서 (독립 데몬 워크스페이스)#

＋부서 버튼으로 부서 워크스페이스를 만들면 **별도 cysd 데몬(별도 소켓)**이 뜸니다 — 프로젝트 간 장애·자원·통신이 격리됩니다. Control Center "작업" 탭과 cys fleet은 모든 부서를 집계해 보여줍니다.

4.5 입력#

• 한글 IME: macOS에서 조합 중 자모 유출을 막는 상태 머신이 내장되어 있습니다.
• 붙여넣기: ⌘V/Ctrl+V (bracketed paste 보존). 클립보드 이미지를 붙여넣으면 임시 파일로 저장된 경로가 타이핑됩니다(iTerm2 방식).
• 파일 드래그&드롭: 드롭한 pane에 셀 인용된 경로가 입력됩니다.

4.6 파일 트리#

Files 버튼 — 포커스 pane의 현재 디렉토리를 루트로 트리를 보여주고(cd 추적), 파일 클릭 시 시스템 기본 앱으로 엽니다.

4.7 테마·폰트#

• 다크 테마 고정 + 배경색 커스텀 피커(테마 버튼). 밝은 배경을 고르면 글자색이 자동 보정됩니다. OS 라이트/다크 자동 전환은 없습니다.
• 터미널 폰트 선택: 테마 버튼 → 폰트 드롭다운(기본값·Menlo·SF Mono·Cascadia Mono· Consolas·JetBrains Mono·D2Coding 등, 기억됨). 미설치 폰트는 기본 스택으로 자동 폴백, 한글 폴백은 항상 보존됩니다.
• 터미널 폰트 크기: ⌘+ / ⌘- / ⌘0 (8–32px, 기억됨).

4.8 ⌘K Command Palette#

퍼지 검색으로: 노드 점프 · 컨텍스트 60%+ 노드 순회 · 역할별 재기동 · 가장 오래된 승인 처리 · 새 탭/분할 · Control Center 토글 등을 키보드로 실행합니다.

4.9 Glance 모드 (⌘G)#

비기술자용 큰 글씨 요약 화면(Live↔작업 전환)과 엔지니어용 상세 탭 화면을 오갑니다.

4.10 단축키 요약#

Continue: Fleet Operations → · Back to Overview