cmux-help
cmux CLI 사용 가이드이자 전용 cmux 스킬로 가는 진입점. 안정적인 모델·함정만 정적으로 담고 커맨드 카탈로그·옵션은 라이브 출력에 위임한다. "cmux 사용법", "cmux 명령어", "cmux help", "cmux 옵션", "cmux 세션", "cmux split", "cmux 브라우저 열기", "cmux send", "cmux read-sc
SKILL.mdskills/cmux-help/SKILL.md
GitHubcmux CLI
cmux 앱을 Unix socket으로 제어하는 CLI. tmux와 유사하지만 macOS 네이티브 앱 기반이며 브라우저·마크다운 뷰어를 내장한다.
이 스킬은 자주 안 바뀌는 모델과 함정만 정적으로 담는다. 커맨드 목록·옵션 시그니처는 라이브 출력으로 위임한다 — drift 방지.
라이브 조회 (먼저 실행)
커맨드 syntax나 옵션이 필요하면 추측하지 말고 다음을 먼저 호출한다.
cmux --help # 전체 커맨드 목록
cmux <subcommand> --help # 가능한 경우
cmux docs # 토픽 인덱스 (사용 가능한 topic 목록 확인)
cmux docs <topic> # 해당 topic의 web URL과 curl 가능한 raw skill 경로 출력
cmux capabilities # 런타임 기능 플래그
cmux ping # 소켓 도달 확인
cmux identify --json # 현재 위치 (workspace/surface)
cmux tree --all # 전체 토폴로지
cmux docs <topic>은 항상 최신 업스트림 raw URL을 안내한다 (raw.githubusercontent.com/manaflow-ai/cmux/main/skills/...). 정적 문서가 stale하면 그쪽을 fetch.
전용 스킬로 라우팅 (fallback 체인)
cmux는 영역별 공식 스킬(cmux-browser, cmux-settings, cmux-customization, cmux-keyboard-shortcuts, cmux-workspace, cmux-diagnostics, cmux-markdown)을 제공한다. 이 cmux-help는 그 진입점이며, 깊은 작업은 이름이 대응되는 전용 스킬로 위임한다 (browser → cmux-browser, settings → cmux-settings …).
전용 스킬이 미설치라도 끊기지 않도록 다음 fallback 체인을 따른다.
- 전용 스킬이 설치돼 있으면 invoke.
- 없으면
cmux docs로 토픽 인덱스를 조회한 뒤, 해당cmux docs <topic>이 안내하는 rawSKILL.mdURL을 fetch — 전용 스킬과 동일 내용에 도달한다. - 그래도 막히면
cmux <command> --help.
②·③은 cmux 런타임이 항상 제공하므로 스킬 미설치와 무관하게 동작한다. 토픽으로 덮이지 않는 영역(diagnostics, markdown 등)은 ②를 건너뛰고 ③으로 간다.
사용자가 설치를 요청하면 전체 설치는 npx skills add manaflow-ai/cmux -g -y, 개별 설치는 --skill <name>을 붙여 수행한다.
핵심 개념 (안정)
4계층
Window (macOS 윈도우)
└─ Workspace (사이드바 항목 — tmux의 session)
└─ Pane (분할 영역 — tmux의 pane)
└─ Surface (pane 안의 탭 — terminal / browser / markdown)
tmux와 가장 다른 점: Surface. 한 pane 안에 여러 surface가 탭으로 공존하며 terminal·browser·markdown이 혼재 가능.
Handle 형식
| 형식 | 예시 | 비고 |
|---|---|---|
| short ref | workspace:2, surface:7 |
출력 기본 |
| UUID | 550e8400-... |
고유, 장황 |
| index | 2 |
숫자만 |
--id-format uuids|both로 출력 형식 변경tab-action은tab:<n>형식도 수용
환경변수
cmux 터미널 안에서 자동 설정. 대부분 커맨드의 기본값. cmux 밖에서 호출하면 명시 필요.
| 변수 | 기본 대상 |
|---|---|
CMUX_WORKSPACE_ID |
--workspace |
CMUX_SURFACE_ID |
--surface |
CMUX_TAB_ID |
--tab |
CMUX_SOCKET_PATH |
소켓 경로 오버라이드 |
글로벌 옵션
--json— 자동화 시 필수, ref 파싱 안정--id-format <refs|uuids|both>--socket <path>,--password <value>
소켓 인증 우선순위: --password > CMUX_SOCKET_PASSWORD > Settings 저장값.
자주 틀리는 함정 (안정)
- send + send-key 분리:
cmux send 'cmd'만으로는 실행 안 됨. 반드시cmux send-key Enter별도 호출. 가장 흔한 실수. - read-screen 타이밍: send 직후엔 이전 화면을 반환할 수 있다.
sleep또는 완료 패턴(✓,PASS, prompt 복귀) polling. - snapshot ref 수명:
browser snapshot --interactive의e1/e2/...는 DOM 변경(navigation, Ajax) 시 stale. 액션 뒤 반드시 re-snapshot. - WKWebView 제약: cmux 브라우저는 viewport emulation·network interception·trace recording 미지원. CDP 기반 도구(Playwright 등)와 다름.
- 소켓 미연결: cmux 앱이 꺼져 있으면 모든 커맨드 실패.
cmux ping으로 사전 확인. - cmux 바깥에서 실행: 일반 터미널에서는
CMUX_*env가 비어 있으니--workspace/--surface명시 필요. - new-workspace --command: shell init(PATH, direnv 등) 전에 실행될 수 있음. 복잡한 초기화는
send+send-key로 분리. - browser open vs goto: surface 지정 없는
open은 새 browser split/surface 생성. 기존 surface 이동은goto|navigate를 선호한다. 현재 CLI는 surface를 지정한open을 navigate처럼 처리할 수 있으므로 실제 동작은cmux browser --help로 확인한다.
핵심 워크플로우 (안정)
명령 실행 + 결과 읽기
cmux send --surface surface:3 'pnpm test'
cmux send-key --surface surface:3 Enter
sleep 2
cmux read-screen --surface surface:3 --lines 50
긴 결과는 --scrollback/--lines로 범위 조절.
병렬 workspace 세팅
cmux new-workspace --name "server" --cwd ~/project --command "pnpm dev"
cmux new-workspace --name "test" --cwd ~/project --command "pnpm test --watch"
cmux new-workspace --name "agent" --cwd ~/project
브라우저 자동화 루프
cmux --json browser open https://example.com
# 반환된 surface ref 기억 (예: surface:7)
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
cmux browser surface:7 fill e1 "query"
cmux --json browser surface:7 click e2 --snapshot-after
# DOM 변경 후 반드시 re-snapshot
cmux browser surface:7 snapshot --interactive
세부 옵션(cookies, storage, dialog, download, frame 등)은 cmux browser --help 또는 cmux docs browser.
plan 실시간 표시
cmux markdown /tmp/plan.md
# 이후 파일 수정 시 뷰어 자동 갱신
tmux와의 차이 (안정)
- session → workspace
send-keys 'cmd' Enter→send 'cmd'+send-key Enter(Enter 분리)split-window -h/-v→new-split <left|right|up|down>(방향 이름)- pane 안에 surface 탭 개념 추가 (terminal/browser/markdown 혼재)
- cmux 고유: 디렉토리 인자(
cmux <path>), 내장 브라우저, 마크다운 뷰어
tmux 호환 커맨드(capture-pane, resize-pane, pipe-pane, wait-for, swap-pane, break-pane, join-pane, find-window, next/previous/last-window, set-buffer/paste-buffer, set-hook 등)도 다수 제공. 정확한 옵션은 cmux <command> --help 또는 cmux docs api.