cmux

# /cmux — cmux Terminal Multiplexer Control cmux는 Ghostty 기반 macOS 네이티브 터미널로, 여러 AI 코딩 에이전트를 관리하기 위해 설계되었다. CLI(`cmux`) 또는 Unix 소켓(`/tmp/cmux.sock`)으로 프로그래밍 제어 가능. --- ## 1. 계층 구조 (4-Level Hierarchy) ``` Window → Workspace → Pane → Surface → Panel(Terminal|Browser) ``` | Level | 설명 | 생성 | 식별 | |-------|------|------|------| | Window | macOS 윈도우 | `⌘⇧N` | — | | Workspace | 사이드바 항목 (탭) | `⌘N` / `cmux new-workspace` | `CMUX_WORKSPACE_ID` | | Pane | 분할 영역 | `⌘D`(우) / `⌘⇧D`(하) / `cmux new-split` | Panel ID | | Surface | 패인 내 탭 | `⌘T` | `CMUX_SURFACE_ID` | | Panel | 터미널 또는 브라우저 | 자동 | Panel ID (내부) | ``` ┌─────────────────────────────────────────────┐ │ ┌──────────┐ ┌────────────────────────────┐ │ │ │ Sidebar │ │ Workspace "dev" │ │ │ │ │ │ ┌──────────┬─────────────┐ │ │ │ │ > dev │ │ │ Pane 1 │ Pane 2 │ │ │ │ │ server │ │ │ [S1][S2] │ [S1] │ │ │ │ │ logs │ │ │ Terminal │ Terminal │ │ │ │ │ │ │ └──────────┴─────────────┘ │ │ │ └──────────┘ └────────────────────────────┘ │ └─────────────────────────────────────────────┘ ``` --- ## 2. cmux 감지 (Detection) ```bash # 소켓 확인 SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}" [ -S "$SOCK" ] && echo "cmux socket available" # CLI 확인 command -v cmux &>/dev/null && echo "cmux CLI available" # cmux 내부인지 확인 [ -n "${CMUX_WORKSPACE_ID:-}" ] && echo "Inside cmux" ``` --- ## Fallback | 상황 | 동작 | |------|------| | cmux CLI 없음 | 일반 터미널로 fallback, 패널 분할 불가 | | cmux 소켓 타임아웃 | CLI 모드로 fallback, `--timeout-ms` 지정 | | cmux 외부 실행 | `CMUX_WORKSPACE_ID` 없으면 워크스페이스 ID 명시 필요 | --- ## 3. CLI 전역 옵션 | Flag | 용도 | |------|------| | `--socket PATH` | 커스텀 소켓 경로 | | `--json` | JSON 출력 | | `--window ID` | 특정 윈도우 대상 | | `--workspace ID` | 특정 워크스페이스 대상 | | `--surface ID` | 특정 서피스 대상 | | `--id-format refs\|uuids\|both` | ID 포맷 제어 | --- ## 4. Workspace 명령 ```bash # 목록 조회 cmux list-workspaces [--json] # 새 워크스페이스 cmux new-workspace # 현재 워크스페이스 cmux current-workspace [--json] # 선택 (전환) cmux select-workspace --workspace <id> # 닫기 cmux close-workspace --workspace <id> ``` ### Socket API ```json {"id":"1","method":"workspace.list","params":{}} {"id":"2","method":"workspace.create","params":{}} {"id":"3","method":"workspace.current","params":{}} {"id":"4","method":"workspace.select","params":{"workspace_id":"<id>"}} {"id":"5","method":"workspace.close","params":{"workspace_id":"<id>"}} ``` --- ## 5. Split & Surface 명령 ```bash # 분할 생성 (방향: left, right, up, down) cmux new-split right cmux new-split down # 서피스 목록 cmux list-surfaces [--json] # 서피스 포커스 cmux focus-surface --surface <id> ``` --- ## 6. Input 명령 (텍스트/키 전송) ```bash # 포커스된 터미널에 텍스트 전송 cmux send "echo hello" cmux send "ls -la\n" # \n = Enter # 키 전송 (enter, tab, escape, backspace, delete, up, down, left, right) cmux send-key enter # 특정 서피스에 전송 cmux send --surface <id> "command" cmux send-key --surface <id> enter ``` ### Socket API ```json {"id":"1","method":"surface.send_text","params":{"text":"echo hello\n"}} {"id":"2","method":"surface.send_key","params":{"key":"enter"}} {"id":"3","method":"surface.send_text","params":{"surface_id":"<id>","text":"command\n"}} ``` --- ## 7. Notification 명령 ```bash # 알림 전송 cmux notify --title "Title" --body "Body" cmux notify --title "T" --subtitle "S" --body "B" # 목록 cmux list-notifications [--json] # 전체 삭제 cmux clear-notifications ``` ### OSC 777 (간단한 터미널 알림) ```bash printf '\e]777;notify;Title;Body\a' ``` --- ## 8. Sidebar Metadata 명령 사이드바에 상태 배지, 진행률, 로그를 표시한다. ```bash # 상태 설정/제거/목록 cmux set-status <key> "<value>" [--icon <name>] [--color "<hex>"] cmux set-status build "compiling" --icon hammer --color "#ff9500" cmux clear-status <key> cmux list-status # 진행률 (0.0 ~ 1.0) cmux set-progress 0.5 --label "Building..." cmux set-progress 1.0 --label "Done" cmux clear-progress # 로그 (level: info, progress, success, warning, error) cmux log "Build started" cmux log --level error --source build "Compilation failed" cmux log --level success -- "All 42 tests passed" cmux clear-log cmux list-log [--limit N] # 사이드바 전체 상태 덤프 cmux sidebar-state [--workspace <id>] ``` --- ## 9. Browser Automation 명령 전체 레퍼런스는 `references/browser-automation.md` 참조. 핵심 명령만 아래에 요약: ```bash # 열기 / 닫기 cmux browser open <url> cmux browser open-split <url> cmux browser <surface> navigate <url> [--snapshot-after] # 대기 cmux browser <surface> wait --load-state complete --timeout-ms 15000 cmux browser <surface> wait --selector "#el" --timeout-ms 10000 # DOM 조작 cmux browser <surface> click "selector" [--snapshot-after] cmux browser <surface> fill "selector" --text "value" cmux browser <surface> type "selector" "text" # 검사 cmux browser <surface> snapshot --interactive --compact cmux browser <surface> screenshot --out /tmp/page.png cmux browser <surface> get text "selector" cmux browser <surface> eval "document.title" ``` --- ## 10. Utility 명령 ```bash cmux ping # 연결 확인 cmux capabilities [--json] # 사용 가능한 메서드 목록 cmux identify [--json] # 현재 포커스 컨텍스트 ``` --- ## 11. 환경 변수 | 변수 | 용도 | |------|------| | `CMUX_SOCKET_PATH` | 소켓 경로 오버라이드 | | `CMUX_SOCKET_ENABLE` | 소켓 활성화/비활성화 (1/0) | | `CMUX_SOCKET_MODE` | 접근 모드 (cmuxOnly / allowAll / off) | | `CMUX_WORKSPACE_ID` | 자동 설정: 현재 워크스페이스 ID | | `CMUX_SURFACE_ID` | 자동 설정: 현재 서피스 ID | --- ## 12. Python Socket Client ```python import json, os, socket SOCKET_PATH = os.environ.get("CMUX_SOCKET_PATH", "/tmp/cmux.sock") def rpc(method, params=None, req_id=1): payload = {"id": req_id, "method": method, "params": params or {}} with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock: sock.connect(SOCKET_PATH) sock.sendall(json.dumps(payload).encode("utf-8") + b"\n") return json.loads(sock.recv(65536).decode("utf-8")) ``` --- ## 13. 키보드 단축키 요약 ### Workspace | 액션 | 단축키 | |------|--------| | 새 워크스페이스 | `⌘N` | | 워크스페이스 1~8 이동 | `⌘1`~`⌘8` | | 마지막 워크스페이스 | `⌘9` | | 워크스페이스 닫기 | `⌘⇧W` | | 이름 변경 | `⌘⇧R` | ### Surface | 액션 | 단축키 | |------|--------| | 새 서피스 | `⌘T` | | 이전/다음 서피스 | `⌘⇧[` / `⌘⇧]` | | 서피스 1~8 이동 | `⌃1`~`⌃8` | | 서피스 닫기 | `⌘W` | ### Split | 액션 | 단축키 | |------|--------| | 우측 분할 | `⌘D` | | 하단 분할 | `⌘⇧D` | | 패널 이동 | `⌥⌘←/→/↑/↓` | | 브라우저 우측 분할 | `⌥⌘D` | | 브라우저 하단 분할 | `⌥⌘⇧D` | ### Browser | 액션 | 단축키 | |------|--------| | 브라우저 서피스 열기 | `⌘⇧L` | | 주소창 포커스 | `⌘L` | | 개발자 도구 | `⌥⌘I` | ### Notifications | 액션 | 단축키 | |------|--------| | 알림 패널 | `⌘⇧I` | | 최근 미읽음 이동 | `⌘⇧U` | --- ## 14. 소켓 설정 (Access Mode) | 모드 | 설명 | |------|------| | Off | 소켓 비활성화 | | cmux processes only | cmux 내부 프로세스만 허용 (기본값) | | allowAll | 모든 로컬 프로세스 허용 (`CMUX_SOCKET_MODE=allowAll`) | 소켓 경로: Release `/tmp/cmux.sock` / Debug `/tmp/cmux-debug.sock` --- ## 15. 자주 사용하는 패턴 ### 멀티 에이전트 워크스페이스 세팅 ```bash # 3개 워크스페이스 생성 + 각각에 명령 전송 cmux new-workspace # agent-1 cmux new-workspace # agent-2 cmux new-workspace # agent-3 # 특정 워크스페이스의 서피스에 명령 전송 cmux send --workspace <id> "claude code --resume " ``` ### 빌드 알림 패턴 ```bash npm run build && cmux notify --title "Build OK" --body "Ready" \ || cmux notify --title "Build FAIL" --body "Check logs" ``` ### 사이드바 진행률 표시 ```bash cmux set-progress 0.0 --label "Starting..." # ... work ... cmux set-progress 0.5 --label "Halfway" # ... work ... cmux set-progress 1.0 --label "Done" cmux log --level success -- "Task complete" ``` ### 브라우저 자동화 (로그인 → 스크래핑) ```bash cmux browser open https://example.com/login SURF=$(cmux browser identify --json | jq -r '.surface_id') cmux browser $SURF wait --load-state complete --timeout-ms 10000 cmux browser $SURF fill "#email" --text "user@example.com" cmux browser $SURF fill "#password" --text "$PASSWORD" cmux browser $SURF click "button[type='submit']" --snapshot-after cmux browser $SURF wait --text "Dashboard" cmux browser $SURF screenshot --out /tmp/dashboard.png ``` --- ## 아키텍처 요약 ``` cmux (Ghostty 기반 macOS 네이티브) ├── Window ← 최상위 컨테이너 │ └── Workspace ← 탭 단위 (new-workspace)