| name | cmux |
| description | cmux CLI reference for AI agents: workspace/pane/surface management, send/read-screen, browser automation, sidebar notifications, tmux migration. 터미널 분할, 출력 캡처, 브라우저 자동화, 멀티에이전트 병렬 실행. cmux --help v0.62.2 검증. |
cmux — AI 에이전트 터미널 가이드
Version: v0.63.1 (2026-03-31 검증, cmux --help 기반)
사전 조건
- macOS 14+,
brew tap manaflow-ai/cmux && brew install --cask cmux
- cmux 앱 실행 중이어야 CLI 동작
- 환경변수 자동 설정:
CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH, CMUX_TAB_ID
계층
Window > Workspace(사이드바 탭) > Pane(분할) > Surface(터미널/브라우저 탭)
참조: window:1, workspace:1, pane:1, surface:1, tab:1 또는 UUID.
환경변수로 --workspace/--surface 생략 가능. 출력 형식: --id-format refs|uuids|both (기본: refs).
Socket Auth
--password > CMUX_SOCKET_PASSWORD 환경변수 > Settings 저장 비밀번호 순 우선.
핵심 CLI
탐색
| 명령어 | 설명 |
|---|
cmux identify [--no-caller] | 현재 컨텍스트 (JSON) |
cmux tree [--all] [--workspace <ref>] | 전체 계층 트리 |
cmux list-workspaces | 워크스페이스 목록 |
cmux list-panes [--workspace <ref>] | 패인 목록 |
cmux list-pane-surfaces [--pane <ref>] | 패인 내 서피스(탭) 목록 |
cmux list-panels [--workspace <ref>] | 패널 목록 |
cmux find-window [--content] [--select] "query" | 내용으로 서피스 검색 |
cmux capabilities | 소켓 메서드 + 프로토콜 버전 (JSON) |
cmux sidebar-state [--workspace <ref>] | 사이드바 전체 상태 한번에 조회 (cwd, git, ports, status, progress, logs) |
Window 관리
| 명령어 | 설명 |
|---|
cmux list-windows | 윈도우 목록 |
cmux current-window | 현재 윈도우 |
cmux new-window | 새 윈도우 |
cmux focus-window --window <ref> | 윈도우 포커스 |
cmux close-window --window <ref> | 윈도우 닫기 |
cmux move-workspace-to-window --workspace <ref> --window <ref> | 워크스페이스를 다른 윈도우로 이동 |
생성/관리
| 명령어 | 설명 |
|---|
cmux <path> | 디렉토리를 새 워크스페이스에서 열기 (앱 미실행 시 자동 시작) |
cmux new-workspace [--name <title>] [--cwd <path>] [--command "cmd"] | 워크스페이스 생성 |
cmux ssh <dest> [--name <title>] [--port <n>] [--identity <path>] [--no-focus] | SSH 워크스페이스 생성 (원격 프록시 포함) |
cmux select-workspace --workspace <ref> | 워크스페이스 선택(전환) |
cmux rename-workspace [--workspace <ref>] "name" | 워크스페이스 이름 변경 |
cmux close-workspace --workspace <ref> | 워크스페이스 닫기 |
cmux workspace-action --action <name> [--workspace <ref>] [--color <name|#hex>] | 액션: pin, unpin, close-others, close-above/below, move-up/down/top, mark-read/unread, set-color, clear-color |
네임드 컬러 (16종): Red, Crimson, Orange, Amber, Olive, Green, Teal, Aqua, Blue, Navy, Indigo, Purple, Magenta, Rose, Brown, Charcoal
cmux workspace-action --workspace workspace:1 --action set-color --color Blue
cmux workspace-action --action set-color --color "#C0392B"
cmux workspace-action --action clear-color
| cmux new-split <left\|right\|up\|down> [--workspace <ref>] [--surface <ref>] | 패인 분할 |
| cmux new-pane [--type <terminal\|browser>] [--direction <dir>] [--url <url>] | 패인 생성 (타입/방향/URL 지정) |
| cmux focus-pane --pane <ref> [--workspace <ref>] | 패인 포커스 |
| cmux new-surface [--type <terminal\|browser>] [--pane <ref>] [--url <url>] | 서피스(탭) 추가 |
| cmux close-surface [--surface <ref>] [--workspace <ref>] | 서피스 닫기 |
| cmux rename-tab [--surface <ref>] <title> | 서피스 탭 이름 변경 |
| cmux tab-action --action <name> [--tab <ref>] | 탭 액션: rename, close-left/right/others, pin/unpin, reload, duplicate, new-terminal-right/new-browser-right |
| cmux move-surface --surface <ref> [--pane <ref>] [--window <ref>] | 서피스를 다른 패인/윈도우로 이동 |
| cmux reorder-surface --surface <ref> (--index <n> \| --before <ref> \| --after <ref>) | 서피스 순서 변경 |
전송 & 캡처 (핵심)
| 명령어 | 설명 |
|---|
cmux send [--surface <ref>] "text\n" | 서피스에 전송 (\n=Enter) |
cmux send-key [--surface <ref>] <key> | 키 전송 (enter, ctrl+c, tab 등) |
cmux send-panel --panel <ref> <text> | 패널에 직접 전송 |
cmux send-key-panel --panel <ref> <key> | 패널에 키 전송 |
cmux read-screen [--surface <ref>] [--lines <n>] [--scrollback] | 출력 읽기 |
cmux capture-pane [--surface <ref>] [--lines <n>] [--scrollback] | tmux 호환 별칭 |
cmux wait-for [-S|--signal] <name> [--timeout <sec>] | 시그널 대기(-S 없이) / 보내기(-S) |
cmux set-buffer [--name <name>] <text> | 버퍼에 텍스트 저장 |
cmux list-buffers | 버퍼 목록 |
cmux paste-buffer [--name <name>] [--surface <ref>] | 버퍼 내용 붙여넣기 |
Claude 통합
| 명령어 | 설명 |
|---|
cmux claude-hook <event> [--surface <ref>] | 이벤트: session-start, active, stop, idle, notification, prompt-submit |
cmux claude-teams [claude-args...] | Claude Teams 모드 시작 |
cmux omo [opencode-args...] | OpenCode 통합 |
cmux codex <install-hooks|uninstall-hooks> | Codex CLI 훅 관리 |
cmux remote-daemon-status [--os <os>] [--arch <arch>] | 원격 데몬 상태 확인 |
cmux markdown [open] <path> | 마크다운 뷰어 패널 (라이브 리로드, 문서 리뷰에 유용) |
내장 브라우저 (WebKit)
cmux browser [--surface <ref>] <subcommand> — --snapshot-after로 자동 스냅샷.
탐색 & 상태
browser open [url] # 브라우저 분할 생성 (서피스 지정 시 navigate처럼 동작)
browser open-split [url] # 명시적 분할 생성
browser goto|navigate <url> [--snapshot-after]
browser back|forward|reload [--snapshot-after]
browser url|get-url # 현재 URL 반환
browser wait [--selector <css>] [--text <t>] [--url-contains <t>] [--load-state <interactive|complete>] [--function <js>] [--timeout-ms <ms>]
DOM 스냅샷 & 스크린샷
browser snapshot [-i|--interactive] [--cursor] [--compact] [--max-depth <n>] [--selector <css>]
browser screenshot [--out <path>] [--json]
browser highlight <selector> # 요소 시각적 하이라이트
--compact와 --max-depth로 토큰 절약 가능. --selector로 특정 영역만 스냅샷.
인터랙션
browser click|dblclick|hover|focus <selector> [--snapshot-after]
browser check|uncheck <selector> [--snapshot-after]
browser scroll-into-view <selector> [--snapshot-after]
browser type <selector> <text> [--snapshot-after] # 기존 값에 추가
browser fill <selector> [text] [--snapshot-after] # 값 대체 (빈 text = 클리어)
browser press|keydown|keyup <key> [--snapshot-after] # 키보드 (Enter, Escape 등)
browser select <selector> <value> [--snapshot-after] # 드롭다운
browser scroll [--selector <css>] [--dx <n>] [--dy <n>] [--snapshot-after]
검색 & 프레임
browser find <role|text|label|placeholder|alt|title|testid|first|last|nth> ...
browser frame <selector|main> # iframe 전환
browser get <url|title|text|html|value|attr|count|box|styles> [selector]
browser is <visible|enabled|checked> <selector>
browser eval <script>
browser find는 Playwright 스타일 로케이터 — CSS 셀렉터보다 견고.
다이얼로그 & 네트워크
browser dialog <accept|dismiss> [text] # JS alert/confirm/prompt 처리
browser download [wait] [--path <path>] [--timeout-ms <ms>]
browser cookies <get|set|clear> [...]
browser storage <local|session> <get|set|clear> [...]
browser network <route|unroute|requests> # 네트워크 가로채기/모킹
browser viewport <width> <height> # 뷰포트 크기 설정
탭 & 스크립트 주입
browser tab <new|list|switch|close|<index>>
browser addinitscript|addscript <script> # JS 주입
browser addstyle <css> # CSS 주입
browser state <save|load> <path> # 브라우저 상태 저장/로드
browser console <list|clear>
browser errors <list|clear>
사이드바
cmux notify --title "제목" --body "내용" [--subtitle "부제"] [--workspace <ref>]
cmux list-notifications
cmux clear-notifications
cmux log --level <info|progress|success|warning|error> [--source "name"] [--workspace <ref>] -- "메시지"
cmux list-log [--limit <n>] [--workspace <ref>]
cmux clear-log [--workspace <ref>]
cmux set-status <key> <value> [--icon <name>] [--color <#hex>] [--workspace <ref>]
cmux list-status [--workspace <ref>]
cmux clear-status <key> [--workspace <ref>]
cmux set-progress <0.0-1.0> [--label "텍스트"] [--workspace <ref>]
cmux clear-progress [--workspace <ref>]
tmux→cmux 변환
| tmux | cmux |
|---|
new-session -d -s N | new-workspace + rename-workspace N |
split-window -v/-h | new-split down/right |
send-keys -t P "cmd" C-m | send --surface P "cmd\n" (패인에 탭 여러개면 list-pane-surfaces로 확인) |
capture-pane -t P -p | capture-pane --surface P |
capture-pane -p -S - | read-screen --scrollback |
kill-session -t N | close-workspace --workspace N |
wait-for ch | wait-for ch [--timeout 30] |
pipe-pane "cmd" | pipe-pane --command "cmd" [--surface <ref>] |
resize-pane -L/-R/-U/-D N | resize-pane --pane <ref> -L|-R|-U|-D [--amount N] |
swap-pane -t T | swap-pane --pane <ref> --target-pane <ref> |
break-pane | break-pane [--pane <ref>] [--surface <ref>] [--no-focus] |
join-pane -t T | join-pane --target-pane <ref> [--no-focus] |
select-window -n/-p/-l | next-window / previous-window / last-window |
last-pane | last-pane [--workspace <ref>] |
clear-history | clear-history [--surface <ref>] |
set-buffer / paste-buffer | set-buffer [--name <n>] <text> / paste-buffer [--name <n>] [--surface <ref>] |
respawn-pane | respawn-pane [--surface <ref>] [--command <cmd>] |
display-message -p "text" | display-message [-p] <text> |
| (없음) | browser, markdown, notify, claude-hook, sidebar-state, rename-tab |
AI 패턴
멀티에이전트
cmux new-workspace --cwd /path/to/project \
--command "claude -p 'task A' --dangerously-skip-permissions"
cmux rename-workspace "agent-A"
SPLIT=$(cmux new-split right)
SURF=$(echo "$SPLIT" | grep -o 'surface:[0-9]*')
cmux send --surface "$SURF" "claude -p 'task B' --dangerously-skip-permissions\n"
cmux new-workspace --command "claude -p 'write a file'"
cmux send --surface surface:20 "cmd\n"
주의: claude -p 종료 시 scrollback이 비워짐. [DONE] echo 시그널로 완료 감지 불가.
대신 결과 파일 존재 여부나 cmux wait-for 시그널을 활용할 것.
서피스 탭 이름 변경
cmux rename-tab --surface surface:2 "Codex"
cmux rename-tab --surface surface:13 "Gemini"
출력 캡처 & 대기
cmux read-screen --surface surface:2 --lines 30
while ! cmux read-screen --lines 10 | grep -q "ready"; do sleep 1; done
cmux wait-for build-done --timeout 60
cmux wait-for -S build-done
개발서버 + 브라우저
cmux new-split right
cmux send --surface surface:2 "npm run dev\n"
cmux browser open http://localhost:3000
cmux browser wait --text "Welcome" --timeout-ms 5000
cmux browser snapshot -i --compact
cmux browser click "button#submit" --snapshot-after
마크다운 뷰어
cmux markdown open ./docs/plan.md
주의사항
omc team 내부는 tmux 직접 호출 — 수동 작업시만 cmux- SSH/원격/CI: cmux 불가 →
command -v cmux >/dev/null || tmux ...
- 사이드바 명령은 cmux 터미널 내부에서만 동작
- macOS 14+ 전용. Gatekeeper 경고 시:
xattr -cr /Applications/cmux.app
cmux send 범위 제한: 다른 워크스페이스의 서피스로는 전송 불가. 같은 워크스페이스 내 new-split으로 생성한 서피스에만 동작claude -p 완료 감지: 종료 시 scrollback이 초기화되므로 echo 시그널([DONE]) 감지 불가. 대신 결과 파일 존재 확인(ls) 또는 cmux wait-for 시그널 방식 사용claude -p 권한: 파일 쓰기·도구 사용 시 반드시 --dangerously-skip-permissions 추가- Codex CLI (
cdd): cmux send "prompt\n"의 \n이 Enter를 트리거하지 않는 경우 있음. cmux send "prompt" 후 cmux send-key enter를 별도 실행할 것. Claude Code(ccd)는 \n 정상 동작.
트러블슈팅
| 문제 | 해결 |
|---|
cmux: command not found | 앱 실행 확인. sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux |
| 소켓 연결 실패 | cmux 앱 재시작. 소켓: ~/Library/Application Support/cmux/cmux.sock |
CMUX_WORKSPACE_ID 없음 | cmux 터미널 내에서만 자동 설정 |
| Ghostty 설정 충돌 | ~/.config/ghostty/config에서 미지원 설정 주석 처리 |
Surface is not a terminal (send 시) | 다른 워크스페이스 서피스 대상 불가. new-split으로 같은 워크스페이스 내 서피스 생성 후 send |
claude -p 완료 후 scrollback 비어있음 | 프로세스 종료 시 scrollback 초기화됨. 완료 감지는 파일 존재 확인(ls fizzbuzz.*) 또는 cmux wait-for 시그널 사용 |
claude -p가 파일을 저장하지 않음 | --dangerously-skip-permissions 플래그 누락. 도구 사용(Write 등)에 필수 |
| Socket Auth 오류 | --password, CMUX_SOCKET_PASSWORD 환경변수, 또는 Settings에서 비밀번호 확인 |
