cys-terminal

AI 에이전트 함대를 지휘하는 오케스트레이션 터미널. macOS · Windows 크로스플랫폼.

터미널 멀티플렉서 + 로컬 데몬 + 관제 대시보드 + 멀티에이전트 운영체계(CYSJavis 팩)가 한 몸입니다. Claude Code·Codex 같은 CLI 에이전트 여러 개를 역할(마스터·워커·CSO·리뷰어)로 나눠 동시에 굴리고, 서로 소켓으로 대화시키고, 비용·컨텍스트·하드웨어를 실시간 관제합니다.

이 프로젝트의 코드는 대부분 사람의 지휘 아래 AI 에이전트들이 작성했습니다 — 커밋 로그의 Co-Authored-By 체인이 그 과정의 기록입니다. 이 저장소 자체가 "AI 함대 오케스트레이션이 실제로 동작한다"는 실증입니다.

Read this in English.

기존 터미널·멀티플렉서는 "사람이 명령을 치는 곳"입니다. AI 에이전트를 여러 개 띄우면 곧바로 한계가 옵니다 — pane끼리 서로 말을 걸 수 없고, 에이전트가 남긴 고아 서버가 쌓여 시스템이 마비되고, 누가 얼마나 쓰는지 보이지 않습니다. cys-terminal은 그 문제들을 1급 기능으로 해결하기 위해 처음부터 새로 작성한 독자 구현입니다.

그리고 네 번째 문제 — 에이전트들을 어떻게 조직으로 묶을 것인가 — 를 내장 팩 (CYSJavis: 역할별 절대지침 + 결정론 운영 도구)으로 해결합니다.

자원의 벽은 실행 중만이 아니라 배포·업그레이드 중에도 다룹니다 — 앱을 새 버전으로 교체하는 순간에도 "정지" 명령을 잃지 않는 것(크로스플랫폼 원자 교체)이 1급 목표입니다.

한 가지 문서 규약: 이 저장소는 개선을 서술할 때 사용자가 잃는 것을 먼저 고지합니다 — 마케팅 과장을 금지하고, 실제 코드·릴리스가 뒷받침하는 것만 적는 것이 규약입니다.

1. 양방향 소켓통신 — 단방향 send + capture 폴링을 쓰지 않는다. 같은 소켓에 물린 모든 pane은 surface ID만 알면 서로에게 능동 push하는 동등 노드다. cys send --surface surface:31 "..." + send-key Return → 대상 pane의 PTY stdin에 직접 주입 → 새 user turn 도착. 서버→클라이언트 방향은 cys events 푸시 스트림(시퀀스 번호·재접속 이어받기).
2. 자원 거버넌스 1급 기능 — 고아 서버 누적 → load 폭주 → 401·hang을 원천 차단하는 완화책 내장.
3. 코어/UI 분리 — 데몬(cysd)은 UI와 무관하게 동작. UI가 hang이어도 소켓 제어 채널은 항상 살아있다(OOB 회생).
4. fail-closed 서명 — 앱은 Tauri updater 서명, 팩은 minisign(공개키 바이너리 핀). 검증에 실패하면 설치·전개 자체가 거부된다. 자기봉인 불변식 — 서명된 번들은 실행 중 자기 내용을 바꾸지 않는다(번들 .pyc 자기생성 봉인 3층 + 서명 후 개수 대조 게이트).
5. 지침과 기계의 한 몸 — 역할별 절대지침·운영 도구·스킬(CYSJavis 팩)이 터미널과 함께 빌드·서명·배포되고, 노드 기동 시 자동 주입된다.
6. 수동적 인지 계층(radio) — 발견 알림과 결정을 물리적으로 분리한다. 원칙1(능동 push)이 결정·조향 채널이라면, radio는 다중 워커가 병렬로 티켓을 돌 때 서로의 발견을 알리는 수동적 계층이다. 승인·verdict·done 같은 결정 트래픽은 radio에 싣지 않는다 — 결정의 단일 진실은 여전히 티켓·gate-status다.

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

• macOS: cys_<버전>_aarch64.dmg (Apple Silicon) — 동봉된 "Install cys.app" 도우미가 숨김 스테이징 후 단일 시스템콜(renamex_np)로 원자 교체해, Finder 드래그가 복사 도중 반쪽 번들을 노출하던 경합을 제거합니다(덮어쓰기 대신 도우미 설치 권장).
• Windows: cys_<버전>_x64-setup.exe — 데몬·CLI·런타임 동봉(자기완결 설치). PE 버전리소스·매니페스트·아이콘 임베드로 SmartScreen/Defender 마찰을 낮췄으나 여전히 미서명이라 첫 실행 경고가 뜰 수 있습니다. 상세: docs/INSTALL-Windows-KR.md
• 24/365 상시 가동(선택): cys daemon install (launchd KeepAlive / 작업 스케줄러).
• 외부 터미널에서 cys 명령 쓰기: 앱 Control Center → "셸에 cys 설치" 1클릭.

설치·제거 상세는 docs/INSTALL.md, 사용법 전체는 User Manual.

cys identify                                  # 내 surface 주소 확인
cys launch-agent --role worker --agent claude # 역할 노드 기동(절대지침 자동 주입)
cys send --to worker "상태 보고해줘"            # 역할 주소로 push
cys send-key --to worker Return               # 전송 확정
cys status --json                             # 전 노드 1콜 스냅샷
cys events --reconnect                        # 이벤트 푸시 구독 (폴링 대체)
cys run --scoped -- python -m http.server     # 생명주기 관리되는 스코프드 실행
cys boot                                      # 표준 노드 세트 일괄 기동(설치된 CLI 자동 감지)

cys.app  Tauri 데스크톱 앱: 터미널 UI(xterm.js, TUI 위에서도 휠 스크롤·드래그 선택·복사
         기본 복원) + Control Center — 데몬의 thin client
cysd     헤드리스 코어 데몬: NDJSON 소켓 서버(UDS / win named pipe), PTY(portable-pty:
         macOS openpty·Windows ConPTY), vt100 화면 재구성, 이벤트 버스, watchdog,
         프로세스 원장, 사용량/비용 수집기, 영속 분석(SQLite), 스케줄러
cys      CLI: pane 안의 AI가 쓰는 동등 노드 클라이언트 (수십 종 서브커맨드 — `cys actions`로 열람)
pack     cysjavis-pack/: 절대지침 10·결정론 도구 90+·훅 25+·스킬 114+·스키마 4
         (빌드 시 임베드 · minisign 서명 배포 · 사용자 수정 파일 불가침)

모든 pane 프로세스에 CYS_SURFACE_ID·CYS_SURFACE_REF·CYS_SOCKET 자동 주입 — pane 안의 AI는 cys identify로 자기 주소를 즉시 안다. PTY는 데몬 소유라서 앱을 재시작·재설치·업데이트해도 세션은 살아 있다(재attach).

터미널을 설치하고 AI CLI를 연결하면 master–worker–CSO–reviewer 멀티에이전트 운영체계가 바로 구동됩니다. 시스템은 3층입니다:

마스터 선언 위계 폴백 — 오너가 친 "너는 마스터다" 한 문장으로 5노드 팀이 자동 기동하고(부트/착수 분리), 2번째 선언은 충돌(거부)이 아니라 새 부서를 자동 생성하며 첫 부서 생성 시 기존 마스터가 CEO로 자동 승격됩니다. 부서 생성 경로가 GUI 버튼 외에 '선언 경로'로 확장된 것입니다. 단, 에이전트가 배달·실행한 선언은 machine-origin 게이트로 이 폴백이 적용되지 않습니다(사람 채널에서만).

soul.md와 memory/는 의도적으로 비어 있는 골격입니다 — "운영 취향과 장기기억은 빌려 쓰는 것이 아니라 사용자 자신이 채워가는 것"이라는 설계 철학입니다. 자율주행(승인된 로드맵 자율 완주)은 오너가 soul.md에 명시적으로 부여할 때만 켜지며, 오너의 어떤 입력이든 즉시 일시정지시키는 kill-switch가 최우선입니다. 대칭으로, 자율 착수의 시작 권한도 오너 채널에서만 나옵니다 — 큐에 미완 작업이 있어도 임무가 지정되지 않으면 보고 후 정지하는 임무 게이트가 kill-switch의 반대편(착수 게이트)을 지킵니다.

상세: Architecture & Philosophy §2–4, 운용법: User Manual §12.

cys-terminal은 자비스 온보딩 없이 그냥 claude만 연결해도 전통 터미널과 다른 경험을 제공합니다. 세 구성을 33항목 × 6영역으로 비교한 결과입니다 (신선 기계 E2E 실측 골격 + 배포 코드 v0.14.x 라인 추적·팩 수치 재측정 기반):

• ① 전통 터미널(iTerm 등) + claude CLI
• ② cys-terminal + 순정 claude (자비스 온보딩 없이 일상 사용)
• ③ cys-terminal + 자비스 온보딩 ("너는 마스터다" 선언 → 5노드 풀 시스템, 기준)

기호: ✕ 없음/불가 · △ 부분/조건부 · ○ 제공 · ◎ 강화 체계 · [실측] 신선 기계 E2E 직접 확인

F1 = Claude Code 자체 첫기동 다이얼로그 5단(Enter→보안 노트→터미널 설정→폴더 신뢰→bypass 경고)에서 최초 1회 사람 통과 필요. F2 = 격리 config는 Keychain 자격증명이 config 경로별로 분리되어 (Claude Code-credentials-<sha256(경로)[:8]>) 자체 /login 1회 필요.

한 줄 독법 — ①→②는 설치만으로 생기는 격차(관측·통신·보호·스킬: 전통 터미널엔 범주 자체가 없음), ②→③은 조직·기억·자율성의 격차(자비스 고유 가치, F영역). ②의 실질 마찰은 1회성 게이트 2개(F1·F2)뿐이며, ②에서 ③으로는 "너는 마스터다" 선언 한 문장으로 승격됩니다.

cys의 수동적 인지 계층(설계 원칙 6 · T5-20)은 Coral Protocol의 연구 AgentRadio (arXiv:2607.28430)의 3 프리미티브를 이식해 기계 게이트로 격상한 재구현입니다. 원 연구는 "4개의 코딩 에이전트가 일을 멈추지 않고 서로의 방송을 듣게 하면"(passive awareness) SWE-Atlas QnA 124태스크에서 단일 32.3% → 4에이전트 62.1%가 됨을 통계 검정(McNemar p=0.0023)으로 보였고, DeepSeek 재현(29.0%→50.8%, p=0.0026)과 B1 예산 통제군(1명에게 6배 예산을 줘도 37.9% — "컴퓨팅을 더 써서 이긴 것 아니냐"는 반박을 설계로 차단)까지 갖춘 교과서급 실험입니다. 아래는 원 논문·원 소스 전수조사(2026-08-14, 두 독립 세션 + 적대 검증 2기 + 수치 재실행의 삼중 검증)로 10개 축을 채점한 판정 — 어디서 이기고 어디서 지는지를 먼저 보입니다.

공정 각주: AgentRadio는 하나의 가설을 증명하기 위한 연구 산출물이라 5·6·8축의 부재는 설계 목적 밖입니다. 총점이 아니라 축별 근거로 읽어야 하며, 9축 열세는 우리의 다음 숙제로 명시합니다. 채점(같은 회사 AI 심판)도 전 구성에 동일 심판이 고정돼 L2→L3 상대 비교에서는 편향이 상쇄됩니다 — 편향이 위협하는 건 절대 수치와 "1위" 서사 쪽(현 리더보드 단일 1위 63.17%가 62.1%를 상회하나 ±5 수준 신뢰구간이 서로 겹쳐 어느 쪽 우위도 통계적 단정은 불가 · AgentRadio는 미등재 자기보고). 비용도 저자 공개 수치로 태스크당 $2.96 → $19.45(6.6배)입니다.

규모 50:1은 양날의 검입니다 — 우리 깊이의 증거인 동시에 그만큼 복잡하다는 뜻이고, 그들의 작음(한나절이면 전수 감사 가능)은 과학적 미덕입니다. 단 그 미덕은 감사 불가능한 106MB 서버 바이너리가 깎아 먹습니다.

JavisRadio의 품질 증거는 테스트 297건/73 밀폐 케이스 — 레드팀 23종 포함, "위반이 정확한 exit로 막힌다"를 잠그는 적대 테스트 — 입니다. 9축 열세는 JAVIS-BENCH 본실험으로 해소를 진행합니다.

NousResearch Hermes Agent(스타 230,268 · 실행 코드 1,377,316줄 — 2026-08-14 실측/GitHub API)와 저장소 전수조사 + 독립 적대 리뷰로 비교했습니다. 덩치는 상대가 큽니다(코드 약 9배 · 테스트 약 20배). 9축 판정은 자비스 우세 1 · Hermes 우세 4 · 반반 3, 같은 층끼리 맞댄 14개 능력 비교는 자비스 우세 6 · Hermes 우세 5 · 동급 3입니다. 자비스가 우세한 6개는 전부 "결과를 믿게 만드는 장치"(신뢰·통제)이고, Hermes가 우세한 5개는 전부 "어디서나 싸고 편하게"(경제·편의·개방)입니다. 한 줄로 — Hermes는 능력을 넓혔고, 자비스는 절차를 잠갔습니다. 벤치마크 점수는 양측 모두 없습니다(자비스는 JAVIS-BENCH 준비 중). 전체 근거는 비교 보고서 JAVIS-vs-Hermes-Agent-종합성능비교보고서-2026-08-14.md(적대 리뷰 반영 확정본).

두 시스템은 지향점이 다릅니다. Hermes는 "어디서나 함께 다니는 유능한 비서"를 지향해 접점을 넓혔고(그들의 설계 문서: "capability lives at the edges"), 자비스는 "내 컴퓨터 안에서, 결과를 믿을 수 있게"를 지향해 경계를 잠갔습니다(우리 설계 문서: "로컬 우선 — 데이터는 머신을 떠나지 않는다"). Hermes가 우세한 축·항목 20개를 하나씩 실측으로 뜯어보면 — 8개는 자비스가 갚아야 할 숙제(공개 벤치마크·Windows 서명·공급망 검사 등), 11개는 지향점이 달라 생긴 차이(전부 또는 일부), 1개는 시간의 차이입니다. 같은 잣대를 Hermes 쪽에도 적용했습니다. 항목별 근거(파일:줄)와 전체 표는 보고서 §7-1에 있습니다.

OpenClaw(스타 386,229 · 포크 81,179 · 등록 기여자 372명 — 2026-08-14 실측/GitHub API)는 깃허브 역사상 별을 가장 많이 받은 소프트웨어입니다. 왓츠앱·텔레그램 등 메신저 26종으로 말을 걸면 내 컴퓨터에서 일해 주는 개인 AI 비서입니다. 저장소를 통째로 내려받아 전수조사하고(커밋 db4379bd) 10개 항목으로 대조했습니다 — 조사·판정·반박을 서로 다른 AI가 맡았고, 반박 단계에서 틀린 주장 0건 · 고칠 곳 10건이 나와 전부 고쳤습니다. 결과는 자비스 우세 4 · 반반 1 · OpenClaw 우세 5이고, 덩치는 상대가 큽니다(제품 코드 약 86배 · 별 약 1.4만 배).

한 줄로 — 그들이 공식 문서(VISION.md:134-135)에 "만들지 않겠다"고 적어 둔 두 줄, 곧 "AI에게 상하 조직을 만드는 틀"과 "무거운 지휘 계층"이 바로 자비스가 하는 일입니다. 전체 근거는 비교 보고서 자비스-vs-OpenClaw-전수조사-최종보고서-2026-08-14.md(적대 리뷰 반영 확정본).

반반 1 — 되살리기: 대화 기록을 안전하게 지키는 쪽은 그들, 조직 상태를 되살리고 거짓 기록으로 그럴듯하게 되살아나는 것까지 막는 쪽은 자비스(복원 직후 기록과 실제를 대조)입니다.

두 시스템은 지향점이 반대입니다. OpenClaw는 "누구나 어디서든 쉽게 쓰는 비서"를 지향해 접점을 넓혔고, 그래서 공식 문서에 상하 조직·무거운 지휘 계층을 만들지 않겠다고 적었습니다. 자비스는 "AI 여러 대를 믿을 수 있게 부리기"를 지향해 그 지휘 계층을 본체로 삼았습니다. 상대가 우세한 12개 항목을 하나씩 뜯어보면 — 4개는 자비스가 갚아야 할 숙제(실행 안 된 코드 측정·성능 증거·리눅스·문서 사이트), 나머지는 지향점이 달라 생긴 차이이거나 시간·인원의 차이입니다. 같은 잣대를 상대에게도 적용했습니다 — OpenClaw는 확장 프로그램이 본체와 똑같은 권한으로 돌고, 나쁜 확장으로 생긴 피해는 그들 정책상 보안 결함으로 접수되지도 않습니다. 폭과 개방성의 대가입니다. 그리고 자비스의 메신저 계층은 애초에 OpenClaw를 전수조사해 배운 결과물입니다(코드는 베끼지 않고 규칙만 다시 구현 · 무엇을 거부했는지도 함께 기록).

앱의 전용 풀 패널 — cysd가 단일 RPC로 플릿·사용량·시스템을 제공하고(외부 대시보드 무의존), 영속 분석은 cysd 내장 SQLite(analytics.db · open 실패 시 graceful degrade)에 쌓입니다. 철학: 로컬 우선(데이터가 머신 밖으로 나가지 않음) · 추가 인프라 0 · 에이전트 0ms 지연(hook은 fire-and-forget).

그 밖에: ⌘K Command Palette(노드 점프·60% 컨텍스트 순회·승인 처리) · Glance 모드(⌘G, 비기술자용 요약 화면) · 워크스페이스 그룹 · 부서(독립 데몬으로 프로젝트 격리) · RBAC PII 가림(CYS_CONTROL_REDACT=1). 상세 설계: docs/CONTROL_CENTER_DESIGN.md

설계 철학: 지침이 오케스트레이터에게 수동으로 시키는 모든 운영 의무 = 터미널의 기능 결함 목록. ①규약→데몬 보증으로 기계화 ②자기보고 우선·화면 파싱은 fallback ③자동화 3단 안전등급(alert→escalate→act, deny-by-default).

cys feed push --wait --title "git push 승인" --body "..."   # 결정까지 블록 (exit 0=allow, 2=deny, 3=timeout)
cys feed reply <request_id> allow                            # CLI 또는 UI Allow/Deny 버튼

자동 응답은 없습니다(HITL) — 요청 노드의 자기결재도 데몬이 거부합니다. 반복 위험 명령은 cys approval sign(master 전용, HMAC signed-prefix)으로 1회 서명해 통과시킵니다.

• 기본 전송(cys send)=steer: 즉시 stdin 주입 — 실행 중 입력을 조향으로 소화.
• cys send --queued=followup: 대상이 3초 이상 조용해지면 한 틱에 한 건씩 자동 배달.

시작 시 + 6시간마다 조용히 확인. 재설치 후 "디스크는 새 버전·프로세스는 구 데몬" 스큐가 남으면 배지 클릭 교대 또는 유휴 자동 교대(라이브 세션 0일 때 — 무손실)로 해소됩니다. 진단·수리는 cys doctor [--fix], 설치본 코드서명 봉인 자가진단은 cys doctor app-seal.

커스터마이즈와 공존: 사용자 수정본은 업데이트가 파괴하지 않습니다 — user-owned 파일은 보존+신버전 .new 병치, system 파일은 치유 전 .user 보존, ~/.cys/local/ 오버레이 (디렉티브 append·스킬 shadowing·훅 후행)는 업데이트가 존재 자체를 모릅니다. cys pack-plan(사전 미리보기) · cys pack-merge(3-way/AI 병합) — 상세는 User Manual §12.7.

함대의 승인 요청·보고를 외부 메신저로 내보내고, 허가된 발신자의 원격 승인을 받습니다 — 발신자 allowlist · 원격 승인 별도 허가 · 즉시 잠금(lockdown) · 모양 기반 redact 내장. cys channel status 참조.

NDJSON(한 줄 = JSON 하나), RPC 수십 종 + channel.* 13종, 이벤트 수십 종. 전수 목록과 환경변수 표는 User Manual §16–17에 있습니다.

git clone https://github.com/idoforgod/cys-terminal
cargo build --release
./target/release/cysd &                      # 데몬 (중복 기동 자동 거부)

cd ui && sh build.sh                          # 프런트엔드 번들 (bun)
cargo build -p cys-app                        # dev 실행: ./target/debug/cys-app
bun x @tauri-apps/cli build                   # 배포 번들

주의: ui/ 수정 후 앱 재빌드 필요(프런트엔드가 바이너리에 임베드됨). 세션(PTY)은 데몬 소유 — UI 재시작·앱 재설치에도 세션 유지(재attach).

• 네트워크 리스너 없음 — 사용자 소유 Unix 소켓(macOS) / DACL 봉인 named pipe(Windows)만.
• 발신자 신원은 커널 peer pid로 검증(자기신고 불신) · role→role ACL · 능력 게이트는 deny-by-default(리뷰어는 읽기 전용).
• 귀속(누가 보냈나)은 화면 문자열이 아니라 배달 원장이 판정한다 — 자기신고·pane 문자열을 불신하고, 원장 조회 증거 없이는 귀속 주장을 무효로 다룬다.
• 업데이트 이중 서명 — 앱은 Tauri updater 서명, 팩은 minisign(공개키 바이너리 핀·replay 단조성·fail-closed).
• 승인 자동응답 없음(HITL) · 자기결재 차단 · 외부 URL은 하드 허용목록(로컬 설정으로만 확장).
• 발행 전 비밀/PII 게이트: scripts/secret-scan.sh --all (fail-closed). 비밀 마스킹은 비가시 문자 우회를 하드코딩 열거가 아니라 유니코드 카테고리 포괄(Cc/Cf/Zl/Zp 제거)로 차단한다("열거는 다음 우회에 진다 — 범주로 막는다").
• 출고 게이트: 릴리스 전 실사용자 경로를 CI가 재현 — macOS는 사본에 quarantine을 부착 후 Gatekeeper 실평가(spctl/codesign/stapler), Windows는 PE 평판으로 검증하고, 못 통과하면 업로드 자체를 차단한다(fail-closed · 정적 패턴이 아니라 사용자가 실제로 걷는 경로를 재현).

취약점 신고: SECURITY.md · 상세: Architecture & Philosophy §6

• macOS에서 sysinfo가 cmdline 전체를 못 읽으면 프로세스명으로 중복 그룹핑(과탐 가능).
• cys run 중 Ctrl-C로 CLI가 죽으면 그룹 정리가 watchdog 주기(5초)로 넘어감.
• Control Center의 GPU/NPU 실시간은 현재 macOS(Apple Silicon) 전용 — Windows는 CPU/MEM만.
• NPU는 활용률(%) 공개 API가 없어 실측 전력(W)으로 표시(macOS).
• 단일-UID 신뢰 모델 — 승인 서명·자기결재 차단은 같은 계정 내 악성 프로세스에 대한 암호학적 방어가 아니라 탐지·fail-safe 층입니다.
• 임무 게이트는 동일 UID의 위조를 암호학적으로 막지 못합니다 — 배달 원장 감사흔적으로 다룹니다.
• Windows 업그레이드 원자성 수리는 맥 개발기 코드판독·모델검증까지이며, 실기 확인은 진행 중입니다.
• macOS 설치본은 무인증서입니다 — 설치도우미로 마찰을 낮췄어도 첫 실행 경고가 뜰 수 있고, '반쪽 설치 vs quarantine' 판별은 cys doctor app-seal로 합니다.
• radio는 교차채널 exactly-once·난청(놓침) 창 0을 원리적으로 보장하지 못합니다(해소 불가 — 관리 대상 잔여 리스크).

• macOS "손상되어 열 수 없음" 은 두 원인입니다 — ① 반쪽 설치(드래그 복사 경합) ② quarantine 속성. 판별은 cys doctor app-seal, 설치는 "Install cys.app" 도우미 사용을 권장합니다.
• 완전 초기화(윈도우 WebView2 저장값·잔존 부서 격리본 삭제 포함)는 docs/GUIDE-clean-reset-KR.md를 따르세요.

기여는 CONTRIBUTING.md, 서드파티 귀속은 NOTICE.md 참조. MIT License (LICENSE) · 문의: cysinsight@gmail.com