cmux는 어떻게 설치하나요?

Homebrew로 간단히 설치할 수 있습니다. 터미널에서 'brew tap manaflow-ai/cmux' 후 'brew install --cask cmux'를 실행하면 됩니다. Homebrew가 없거나 tap이 안 될 경우 GitHub Releases 페이지에서 DMG 파일을 직접 다운로드할 수 있습니다.

cmux의 read-screen과 send 명령은 어떻게 활용하나요?

cmux read-screen [pane-id]로 특정 Pane의 현재 화면 내용을 텍스트로 읽을 수 있고, cmux send [pane-id] '명령어'로 해당 Pane에 명령을 전송할 수 있습니다. 이를 통해 Claude Code가 다른 터미널의 빌드 결과나 테스트 출력을 읽고 적절한 후속 명령을 실행하는 워크플로우를 구성할 수 있습니다.

cmux와 Claude Code를 연동하면 어떤 워크플로우가 가능한가요?

하나의 Pane에서 실행 중인 Claude Code가 다른 Pane의 서버 로그나 테스트 결과를 read-screen으로 모니터링하고, 문제 발생 시 send로 자동으로 명령을 보내는 자율 디버깅 워크플로우를 구성할 수 있습니다. 내장 WebKit 브라우저로 터미널을 벗어나지 않고 웹 결과도 확인할 수 있습니다.

cmux는 기존 터미널과 무엇이 다른가요?

cmux는 AI 에이전트가 터미널 화면을 읽고, 명령을 보내고, 브라우저를 제어하고, 알림을 받을 수 있도록 설계된 macOS 네이티브 터미널입니다. identify, read-screen, send 같은 에이전트 전용 CLI API를 제공해 에이전트 간 터미널 오케스트레이션이 가능합니다.

cmux의 4단계 계층 구조는 어떻게 구성되어 있나요?

Window > Workspace > Pane > Surface의 4단계 계층 구조로 구성됩니다. Window는 최상위 앱 창, Workspace는 논리적 작업 공간, Pane은 분할된 터미널 영역, Surface는 실제 터미널 세션입니다. Ghostty 엔진 기반 GPU 가속 렌더링을 사용합니다.

cmux를 Claude Code와 어떻게 연동하나요?

cmux 환경 변수가 자동으로 주입되어 Claude Code가 현재 cmux 세션을 인식합니다. Claude Code에서 cmux의 read-screen API를 호출해 다른 Pane의 출력을 읽고, send API로 명령을 보낼 수 있습니다. 리더-워커 패턴으로 하나의 Claude가 다른 여러 Claude 세션을 조율하는 구성이 가능합니다.

cmux를 사용하려면 Ghostty를 별도 설치해야 하나요?

아닙니다. cmux는 libghostty를 라이브러리로 임베드하고 있어 Ghostty를 별도로 설치할 필요가 없습니다. 다만, Ghostty의 설정 파일(~/.config/ghostty/config)이 있으면 cmux가 이를 읽어서 테마와 폰트를 적용합니다.

cmux에서 여러 AI 에이전트를 동시에 운영할 수 있나요?

가능합니다. 리더-워커 패턴이 커뮤니티에서 검증된 구성입니다. 리더 에이전트가 cmux read-screen으로 워커 에이전트의 진행 상황을 모니터링하고, cmux send로 수정 명령을 전달하는 구조입니다.

AI/DevTools for AI

cmux란? cmux 설치 및 사용해보기 - AI 에이전트를 위해 설계된 터미널(cmux vs tmux 비교)

Q: cmux는 무료인가요?

cmux 코어는 AGPL-3.0 라이선스의 오픈소스 프로젝트로 무료 사용 가능합니다. 다만, 별도의 'Founder's Edition' 유료 구독이 존재하며, 우선 지원, AI 기능 조기 접근, iOS 앱, 클라우드 VM 등의 프리미엄 기능을 제공합니다.

안녕하세요! 갓대희 입니다.

오늘은 AI 코딩 에이전트를 터미널에서 본격적으로 활용하는 사람이라면 알아두면 좋은 도구, cmux에 대해 다뤄보려 한다.

Claude Code, OpenAI Codex, Gemini CLI 등 다양한 AI 에이전트를 터미널에서 병렬로 돌리다 보면 tmux만으로는 한계를 느끼게 된다. 브라우저를 따로 띄워야 하고, 에이전트 간 상태 공유가 안 되고, 사이드바에 진행률을 표시할 방법도 없다. cmux는 이런 문제를 네이티브 레벨에서 해결하는 AI 에이전트 전용 터미널이다.

cmux란 무엇인가
- tmux의 한계와 cmux의 등장
- tmux vs cmux 비교
설치 및 환경 확인
핵심 개념: 계층 구조와 환경변수
기본 CLI 명령어 레퍼런스
- 워크스페이스 관리
- 패인 분할과 서피스
- 텍스트 전송과 출력 캡처
AI 에이전트 핵심: 출력 캡처와 동기화
내장 브라우저 자동화
사이드바: 알림, 진행률, 상태 표시
tmux에서 cmux로 마이그레이션

실전 활용

실전: Claude Code + cmux 연동
실습: 멀티에이전트 병렬 실행
실습: 개발서버 + 브라우저 E2E 검증
Claude Code / OMC 통합 가이드

심화 분석

경쟁 도구 생태계 (Claude Squad, Pane, Amux, Calyx 비교)
커뮤니티 반응
제한사항과 미래 전망
트러블슈팅
자주 묻는 질문 (FAQ)
참고 자료

cmux 주요 요약
cmux는 AI 코딩 에이전트를 위해 설계된 macOS 네이티브 터미널이다. 내장 WebKit 브라우저, Unix socket API, 사이드바 알림 시스템, tmux 호환 명령어를 제공하며, Claude Code/Codex/Gemini CLI를 병렬로 실행하고 프로그래밍 방식으로 제어할 수 있다. 이 글에서는 설치부터 실전 멀티에이전트 운용, 경쟁 도구 비교, 커뮤니티 반응까지 단계별로 안내한다.

1. cmux란 무엇인가

cmux는 manaflow-ai가 개발한 AI 코딩 에이전트 전용 macOS 네이티브 터미널이다. 2026년 2월에 출시되어 GitHub 9.4k+ 스타를 기록 중이다(2026년 3월 기준). Ghostty의 렌더링 엔진(libghostty)을 사용하며, Swift + AppKit으로 구축된 네이티브 앱이다.

tmux의 한계와 cmux의 등장

tmux는 수십 년간 터미널 멀티플렉서의 표준이었다. 하지만 AI 에이전트를 본격적으로 운용하다 보면 이런 한계에 부딪힌다:

브라우저 자동화가 불가 - 개발 서버의 UI를 확인하려면 별도 브라우저+Playwright 설정이 필요
사이드바 상태 표시 없음 - 어떤 에이전트가 어떤 작업 중인지 한눈에 파악 불가
프로그래밍 API 부재 - capture-pane 출력을 파싱하는 것이 주요 통신 수단
Git/PR 상태 연동 없음 - 워크스페이스별 브랜치, PR 번호 표시 불가

cmux는 이 모든 문제를 "AI 에이전트를 위해 터미널을 다시 만들자"라는 관점에서 해결한다.

tmux vs cmux 비교

구분	tmux	cmux
플랫폼	Linux/macOS/Windows(WSL)	macOS 14+ 전용
UI	TUI (텍스트 기반)	네이티브 GUI (사이드바, 탭)
내장 브라우저	없음	WebKit 내장 (DOM 조작, 스크린샷)
알림 시스템	없음	사이드바 뱃지, 진행률, 알림
세션 지속성	detach/reattach (SSH 생존)	앱 재시작 시 레이아웃 복원 (프로세스는 미복원)
프로그래밍 API	제한적 (control mode)	Unix socket JSON-RPC + 풍부한 CLI
AI 에이전트 지원	범용 (특화 기능 없음)	Claude/Codex/Gemini 병렬 실행 최적화
원격 서버	SSH에서 동작	로컬 macOS 전용 (SSH 불가)

tmux를 완전히 버려야 할까?

아니다. tmux는 SSH 원격 서버 작업, CI/CD 환경, Linux 서버에서 여전히 필수다. cmux는 로컬 macOS에서 AI 에이전트를 운용하는 시나리오에 특화되어 있다. 두 도구는 경쟁이 아닌 보완 관계다.

2. 설치 및 환경 확인

Homebrew 설치 (권장)

# Homebrew로 설치

brew tap manaflow-ai/cmux
brew install --cask cmux

# CLI를 시스템 전역에서 사용하려면 (선택)

sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux

Homebrew가 없거나 tap이 안 될 경우, GitHub Releases에서 DMG를 직접 받아도 된다.

macOS 보안 경고 (Gatekeeper)

처음 실행할 때 "확인되지 않은 개발자" 경고가 뜰 수 있다.

Gatekeeper 해결 방법
시스템 설정 > 개인정보 보호 및 보안 > 하단 "확인 없이 열기" 클릭. 또는 터미널에서:
xattr -cr /Applications/cmux.app

설치 확인

cmux 앱을 실행한 후, 터미널에서 다음 명령어로 환경을 확인한다.

# 버전 확인

$ cmux version
cmux 0.62.2 (77) [6c203b514]

# 환경변수 확인 (cmux 터미널 내에서 실행)

$ echo $CMUX_WORKSPACE_ID
9A5E82C8-296F-467D-B07E-58B75F49D52E    # 값은 환경마다 다름

$ echo $CMUX_SURFACE_ID
89FA79ED-C36D-4325-A1F1-6D3118073A21    # 값은 환경마다 다름

$ echo $CMUX_SOCKET_PATH
~/Library/Application Support/cmux/cmux.sock

# 현재 컨텍스트 확인

$ cmux identify
{
  "caller": {
    "tab_ref": "tab:1",
    "is_browser_surface": false,
    "pane_ref": "pane:1",
    ...
  }
}

환경변수가 설정되어 있다면 cmux 터미널 내에서 실행 중인 것이다.

CMUX_WORKSPACE_ID와 CMUX_SURFACE_ID가 자동 설정되므로, 대부분의 cmux 명령어에서 --workspace와 --surface 플래그를 생략할 수 있다. 이것이 cmux의 핵심 편의 기능 중 하나다.

3. 핵심 개념: 계층 구조와 환경변수

cmux의 모든 것은 4단계 계층 구조로 이해할 수 있다.

Window                          (앱 윈도우)
  └── Workspace                 (사이드바 탭 — git 브랜치, PR 상태 표시)
        └── Pane                (분할 영역)
              └── Surface       (터미널 탭 또는 브라우저 패널)

화면 왼쪽에 사이드바가 있고, 오른쪽이 터미널 영역이다. cmux의 계층 구조를 실제 UI에 매핑하면 이렇다.

계층	설명	참조 형식	비유
Window	앱 윈도우	`window:1`	건물
Workspace	사이드바의 각 탭 (프로젝트 단위)	`workspace:1`	층(Floor)
Pane	워크스페이스 내 분할 영역	`pane:1`	방(Room)
Surface	패인 내 터미널/브라우저 탭	`surface:1` 또는 UUID	책상(Desk)

환경변수 자동 설정

`CMUX_WORKSPACE_ID`	현재 워크스페이스 ID. 모든 명령의 기본 `--workspace`
`CMUX_SURFACE_ID`	현재 서피스 ID. 모든 명령의 기본 `--surface`
`CMUX_SOCKET_PATH`	Unix 소켓 경로 (기본: `~/Library/Application Support/cmux/cmux.sock`)

4. 기본 CLI 명령어 레퍼런스

아래 명령어는 모두 cmux --help (v0.62.2) 출력에서 직접 검증한 것이다.

워크스페이스 관리

# 새 워크스페이스 생성 (사이드바에 탭 추가)

cmux new-workspace [--cwd /path/to/project] [--command "npm run dev"]

# 워크스페이스 이름 변경

cmux rename-workspace "my-project"

# 워크스페이스 목록 / 트리 구조 / 현재 워크스페이스

cmux list-workspaces
cmux tree [--all]
cmux current-workspace

# 워크스페이스 전환 / 닫기

cmux select-workspace --workspace workspace:2
cmux close-workspace --workspace workspace:2

ex) cmux new-workspace

ex) cmux rename-workspace "dev"

패인 분할과 서피스

# 패인 분할 (left, right, up, down)

cmux new-split right
cmux new-split down

# 새 서피스(탭) 추가 — 터미널 또는 브라우저

cmux new-surface                               # 터미널 탭
cmux new-surface --type browser --url https://localhost:3000  # 브라우저 탭

# 패인/서피스 목록 및 닫기

cmux list-panes
cmux list-pane-surfaces
cmux close-surface --surface surface:2

ex) 패인 분할 right : cmux new-split right

ex) 나머진.. 직접 해보시면 좋을 것 같다. 안해도 된다. ( AI에게 공식 문서, 문법을 잘 가이드만 해도 알아서 잘 쓴다. )

텍스트 전송과 출력 캡처

# 현재 서피스에 텍스트 전송 (\n = Enter)

cmux send "npm run dev\n"

# 특정 서피스에 전송

cmux send --surface surface:2 "npm test\n"

# 키 전송 (enter, ctrl+c, tab, escape 등)

cmux send-key ctrl+c
cmux send-key --surface surface:2 enter

# 출력 캡처 (AI 에이전트 핵심 기능!)

cmux read-screen --lines 30               # 최근 30줄
cmux read-screen --scrollback              # 전체 스크롤백 버퍼
cmux capture-pane --surface surface:2 --lines 50  # tmux 호환 별칭

5. AI 에이전트 핵심 : 출력 캡처와 동기화

AI 에이전트에게 핵심적인 기능은 다른 패인에서 실행 중인 프로세스의 출력을 읽는 것이다. tmux에서는 tmux capture-pane이 유일한 방법이었는데, cmux는 이를 더 풍부하게 제공한다.

read-screen / capture-pane

# read-screen: 서피스의 터미널 출력 읽기

cmux read-screen                              # 현재 서피스
cmux read-screen --surface surface:2 --lines 50  # 특정 서피스, 최근 50줄
cmux read-screen --scrollback                  # 전체 스크롤백

# capture-pane: tmux 호환 별칭 (동일 기능)

cmux capture-pane --surface surface:2 --lines 50

ex) 왼쪽 패인에서 오른쪽 패인 읽기

다른 터미널 탭에서 뭐가 돌아가고 있는지를 코드 한 줄로 읽어왔다. AI 에이전트가 이걸 쓰면 "백엔드 서버 로그를 읽어서 에러를 파악하고, 프론트엔드 코드를 수정"하는 흐름이 가능해진다.

send: 다른 터미널에 명령 보내기

ex) 왼쪽 패인에서 오른쪽 패인에 명령 전송

wait-for: 시그널 기반 동기화

tmux에서도 tmux wait-for이 있었지만, cmux의 wait-for는 타임아웃을 지원하여 더 안전하다.

# 패턴 1: 시그널 기반 동기화

# 대기 측 (에이전트 A)
cmux wait-for build-done --timeout 60

# 시그널 측 (에이전트 B, 빌드 완료 후)
cmux wait-for -S build-done

# 패턴 2: 폴링 기반 대기 (특정 출력 감지)

# "ready" 문자열이 나올 때까지 대기
while ! cmux read-screen --surface surface:2 --lines 10 | grep -q "ready"; do
  sleep 1
done
echo "서비스 준비 완료!"

find-window: 내용으로 서피스 검색

# 터미널 내용으로 서피스 찾기

cmux find-window --content "error" --select    # "error"가 포함된 서피스로 이동
cmux find-window "npm"                         # "npm" 관련 서피스 검색

6. 내장 브라우저 자동화

cmux의 주요 기능 중 하나는 WebKit 기반 내장 브라우저다. 별도의 Playwright나 Selenium 없이도 터미널에서 바로 웹 페이지를 조작할 수 있다. WebKit을 사용하므로 Safari 유저에이전트로 동작하며, 이는 Chromium 기반 도구가 흔히 맞닥뜨리는 봇 감지를 우회하는 데도 유리하다.

(출처: cmux PROJECTS.md)

브라우저 명령어 구조
cmux browser [--surface <ref>] <subcommand> [args]
대부분의 조작 명령에 --snapshot-after 플래그를 붙이면 조작 후 DOM 스냅샷을 자동 반환한다.

네비게이션

cmux browser open http://localhost:3000         # 브라우저 패인 생성 + URL 열기
cmux browser goto http://localhost:3000/login   # 현재 브라우저에서 이동
cmux browser back                               # 뒤로
cmux browser forward                            # 앞으로
cmux browser reload                             # 새로고침
cmux browser url                                # 현재 URL 확인

DOM 조작

# DOM 스냅샷 (접근성 트리 기반, AI 에이전트에 최적)

cmux browser snapshot -i                       # --interactive: 안정적 요소 참조 반환

# 클릭, 입력, 체크

cmux browser click "button#submit" --snapshot-after
cmux browser fill "input[name='email']" "user@example.com" --snapshot-after
cmux browser type "#search" "검색어"
cmux browser check "input[type='checkbox']"
cmux browser select "#country" "KR"

# 값 추출

cmux browser get text "h1"                     # 텍스트 추출
cmux browser get html ".content"               # HTML 추출
cmux browser get value "input#name"            # input 값
cmux browser get title                         # 페이지 제목
cmux browser is visible ".modal"               # 요소 가시성 확인

ex) cmux browser screenshot --out ~/Desktop/cmux-browser-test.png

ex) cmux browser snapshot -i

ex) cmux browser eval "document.title"

대기와 JavaScript

# 요소/텍스트/URL 대기

cmux browser wait --selector ".loaded"              # CSS 셀렉터 대기
cmux browser wait --text "Welcome"                  # 텍스트 출현 대기
cmux browser wait --url-contains "/dashboard"       # URL 변경 대기
cmux browser wait --load-state complete             # 페이지 로드 대기
cmux browser wait --timeout-ms 5000                 # 타임아웃 지정

# JavaScript 실행

cmux browser eval "document.title"
cmux browser eval "document.querySelectorAll('li').length"

# 스크린샷

cmux browser screenshot --out ./capture.png

7. 사이드바: 알림, 진행률, 상태 표시

cmux의 사이드바는 각 워크스페이스의 상태를 실시간으로 보여준다. AI 에이전트가 진행 상황을 시각적으로 리포트하는 데 활용할 수 있다.

# 데스크톱 알림

cmux notify --title "빌드 완료" --body "3분 소요" --subtitle "frontend"

# 사이드바 로그 (level: info, progress, success, warning, error)

cmux log --level success --source "test" "42/42 테스트 통과"
cmux log --level error --source "build" "TypeScript 컴파일 실패"

# 진행률 바

cmux set-progress 0.75 --label "빌드 진행 중..."
cmux clear-progress

# 상태 표시 (사이드바 배지)

cmux set-status "phase" "testing" --icon "sparkle" --color "#28a745"
cmux clear-status "phase"

ex) 알림 및 상태 표시

8. tmux에서 cmux로 마이그레이션

기존 tmux 스크립트나 워크플로우를 cmux로 변환할 때 참고하는 매핑 테이블이다.

모든 cmux 명령은 cmux --help 및 cmux browser --help (v0.62.2) 출력에서 검증했다.

tmux 명령	cmux 명령
`tmux new-session -d -s name`	`cmux new-workspace` + `cmux rename-workspace name`
`tmux split-window -v / -h`	`cmux new-split down / right`
`tmux send-keys -t %1 "cmd" C-m`	`cmux send --surface surface:1 "cmd\n"`
`tmux capture-pane -t %1 -p`	`cmux capture-pane --surface surface:1`
`tmux kill-session -t name`	`cmux close-workspace --workspace workspace:1`
`tmux list-panes`	`cmux list-panes` / `cmux tree`
`tmux wait-for channel`	`cmux wait-for channel --timeout 30`
`tmux resize-pane -D 10`	`cmux resize-pane --pane pane:1 -D --amount 10`
`tmux pipe-pane "cat > log"`	`cmux pipe-pane --command "cat > log"`
(없음)	`cmux browser open URL` (내장 브라우저)
(없음)	`cmux identify` (현재 컨텍스트 확인)
(없음)	`cmux notify / log / set-progress` (알림)

Best Practice: tmux + cmux 조합 사용

두 도구는 대체재가 아니라 보완재다. (현재 까지는 그렇게 보인다. )

원격 서버: tmux로 세션을 유지하고 프로세스를 관리한다. SSH 연결이 끊겨도 작업이 살아있다.
로컬 개발: cmux에서 AI 에이전트를 오케스트레이션한다. 브라우저, 알림, 크로스 세션 API를 활용한다.
연결: cmux의 Surface 안에서 ssh server && tmux attach로 원격 tmux 세션에 접속하면, 양쪽의 장점을 모두 활용할 수 있다.

9. 실전: Claude Code + cmux 연동

cmux 안에서 Claude Code를 실행하고, Claude가 cmux CLI를 통해 다른 터미널의 상태를 직접 확인하는 것을 체험한다.

환경 준비

# 왼쪽 패인: Claude Code 실행
claude

# 오른쪽 패인: 간단한 서버 또는 프로세스 실행
python3 -m http.server 8000

Claude에게 cmux 사용 요청

Claude Code에게 다른 패인의 상태를 확인해달라고 요청한다.

Claude에게 보낸 프롬프트 예시
"오른쪽 패인(surface:4)에서 서버가 돌아가고 있어. cmux read-screen으로 서버 로그를 읽어서 상태를 알려줘."

많은 사용기에서 AI 에이전트가 초기에 cmux를 tmux로 오인하는 경우가 있다고 보고된다. 이를 방지하려면 프로젝트 루트의 CLAUDE.md에 "이 환경은 cmux입니다. tmux가 아닌 cmux CLI를 사용하세요."를 추가해두는 것이 좋다.

최종 원하는 내용 출력 완료

이 전체 과정에서 탭을 전환하지 않았다
Claude Code가 cmux CLI를 통해 다른 터미널의 출력을 직접 읽고, 분석하고, 필요하면 명령을 직접 보내는 것까지 가능하다.

ex) 이외 내가 테스트 했던 내역들 참고

- 좌측 페인 : 클로드 코드 / 우측 페인 : 클로드 코드가 조작하는 영역

- 좌측 페인 : 클로드 코드 / 우측 페인 : 브라우저 / 좌측 하단 페인 : 신규 터미널(미캡쳐)

10. 실습 : 멀티에이전트 병렬 실행

cmux를 활용하면 여러 AI 에이전트를 병렬로 실행하고, 각각의 상태를 모니터링할 수 있다.

시나리오: 3개 에이전트 병렬 리서치

#!/bin/bash

# Step 1: 에이전트별 워크스페이스 생성

cmux new-workspace --command "claude 'React 19 새 기능을 조사해줘'"
cmux rename-workspace "agent-react"

cmux new-workspace --command "claude 'Next.js 15 마이그레이션 가이드를 작성해줘'"
cmux rename-workspace "agent-nextjs"

cmux new-workspace --command "claude 'TypeScript 5.5 변경사항을 정리해줘'"
cmux rename-workspace "agent-typescript"

# Step 2: 진행 상황 모니터링

cmux read-screen --workspace workspace:2 --lines 5
cmux read-screen --workspace workspace:3 --lines 5
cmux read-screen --workspace workspace:4 --lines 5

# Step 3: 특정 에이전트 출력에서 결과 찾기

cmux find-window --content "완료" --select

cmux claude-teams 명령

cmux v0.62.2에는 cmux claude-teams [claude-args...] 명령이 내장되어 있다.
이는 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수를 설정하고 tmux 호환 심(shim)을 PATH에 자동 주입하여 Agent Teams 모드를 활성화하는 통합 명령이다.

- 이 부분도 추후 충분히 테스트 하고 갱신 예정.

11. 실습 : 개발서버 + 브라우저 E2E 검증

Playwright 없이도 cmux의 내장 브라우저로 간단한 E2E 검증이 가능하다.

#!/bin/bash

# Step 1: 개발서버 시작 (분할 패인)

cmux new-split right
cmux send --surface surface:2 "cd my-app && npm run dev\n"

# Step 2: 서버 준비 대기

while ! cmux read-screen --surface surface:2 --lines 10 | grep -q "ready"; do
  sleep 1
done
echo "개발서버 준비 완료!"

# Step 3: 브라우저에서 검증

cmux browser open http://localhost:3000
cmux browser wait --text "Welcome" --timeout-ms 10000
cmux browser snapshot -i
cmux browser fill "input[name='email']" "test@example.com"
cmux browser fill "input[name='password']" "test1234"
cmux browser click "button[type='submit']" --snapshot-after
cmux browser wait --url-contains "/dashboard" --timeout-ms 5000
cmux browser get text "h1"    # "Dashboard"가 출력되면 성공

# Step 4: 정리

cmux send-key --surface surface:2 ctrl+c
cmux close-surface --surface surface:2

- 이 부분도 추후 충분히 테스트 하고 갱신 예정.

12. Claude Code / OMC 사용시 경험 공유

Claude Code와 oh-my-claudecode(OMC)를 cmux에서 사용할 때 상충 되는 부분이 있었다.

나의 경우 omc를 사용할때 특히 cmux 스폰이 잘 안되어 다음 과 같은 규칙을 추가 해서 cmux 를 사용 하도록 우회 하였다.

( 아직 잘 만들어지고, 검증된 cmux관련 skills가 없다보니 나름 고민하고 적용해 보았다. )

OMC Teams와 tmux 의존성

주의: OMC 내부는 tmux를 직접 호출한다

OMC의 팀 시스템은 Node.js의 execFile('tmux', args)로 tmux를 직접 호출한다. 따라서 /team이나 /omc-teams 명령을 사용하려면 tmux가 여전히 설치되어 있어야 한다. cmux는 에이전트가 수동으로 터미널을 조작하는 경우에 사용한다.

Claude Code Hook 연동

# Claude Code 세션 이벤트를 사이드바에 반영

cmux claude-hook session-start    # 세션 시작 시
cmux claude-hook stop              # 세션 종료 시
cmux claude-hook notification      # 알림 발생 시

전역 규칙 파일 설정

# ~/.claude/rules/cmux-guide.md에 가이드 배치

# cmux 터미널 환경 — AI 에이전트 규칙
# tmux 대신 cmux CLI를 사용하세요.
# 핵심 명령어: read-screen, capture-pane, browser, wait-for
# 환경변수: CMUX_WORKSPACE_ID, CMUX_SURFACE_ID (자동 설정)

cmux 감지 + tmux 폴백 패턴

# cmux가 있으면 cmux 사용, 없으면 tmux 폴백
if command -v cmux &>/dev/null && [ -n "$CMUX_WORKSPACE_ID" ]; then
  cmux new-split right
  cmux send --surface surface:2 "npm run dev\n"
else
  tmux split-window -h
  tmux send-keys "npm run dev" C-m
fi

13. 경쟁 도구 생태계 (Claude Squad, Pane, Amux, Calyx 비교)

cmux와 비슷한 영역의 도구들을 비교한다 (2026년 3월, 각 프로젝트 README 기준).

항목	cmux	Claude Squad	Pane	Amux	Calyx
기반 기술	Ghostty(libghostty) + Swift	tmux 기반 Go 래퍼	자체 터미널 에뮬레이터 (AGPL-3.0)	tmux 기반 Python 래퍼	macOS native (Ghostty 기반)
플랫폼	macOS (공식)	macOS, Linux	macOS, Linux, Windows	tmux 지원 환경	macOS (macOS 26+)
브라우저 내장	O (WebKit)	X	X	X	X
에이전트 API	전용 CLI (identify, read-screen, send, notify)	tmux send-keys 기반	자체 API	tmux send-keys 기반	GUI 기반 관리
특징	GPU 가속, 알림 시스템, 에이전트 불가지론적	다중 에이전트 관리, git worktree 연동	크로스플랫폼, 내장 git workflow 탭	웹 대시보드, REST API	Liquid Glass UI, macOS 26 네이티브

위 비교는 2026년 3월 기준. 참고: Claude Squad, Pane, Amux, Calyx.

"Primitive, Not Solution" 철학

경쟁 도구와 cmux의 큰 차이는 "조합 가능한 프리미티브(Composable Primitives)" 철학이다. Claude Squad나 Amux가 완성된 솔루션을 지향한다면, cmux는 read-screen, send, notify 같은 원자적 빌딩 블록을 제공하고, 조합은 사용자와 에이전트에 맡긴다. Unix 철학의 "한 가지 일을 잘 하는 도구"와 맞닿아 있다.

경쟁 구도: Calyx의 등장

구분	cmux	Calyx
기반	libghostty + Swift/AppKit	libghostty + Tauri/React
UI 특징	네이티브 macOS, 세로 탭	Liquid Glass UI (macOS 26 디자인)
에이전트 연동	Unix Socket CLI API	내장 MCP 서버
성숙도	v0.62.2, 9.4k+ Stars	초기 단계, 신규 프로젝트

(참고: DEV Community — Calyx vs cmux)

14. 커뮤니티 반응

cmux는 2026년 3월 현재 GitHub 9.4k+ Stars를 기록하며 빠르게 성장 중이다. 최근 3일(3월 15~18일)에만 90개 이상의 커밋이 머지되었다.

"I just discovered the BEST terminal for AI agents: 'Cmux'. Horizontal tabs, vertical tabs, web view built-in, notifications when the agent finishes, live agent status. As a heavy Claude Code user, this is a game changer."
(AI 에이전트를 위한 최고의 터미널 'Cmux'를 발견했다. Claude Code 헤비 유저로서, 이건 게임 체인저다.)

— @melvynxdev (~14,500 views, ~152 reposts)

"tmux grids are awesome, but I feel a need to have a proper 'agent command center' IDE for teams of them, which I could maximize per monitor."
(에이전트 팀을 모니터별로 최대화할 수 있는 '에이전트 커맨드 센터' IDE가 필요하다.)

— @karpathy (Andrej Karpathy)

Karpathy의 이 트윗에 cmux 공동 창립자 Lawrence Chen이 직접 답변하며 cmux의 tmux 호환 레이어와 네이티브 스플릿/탭 기능을 소개했다. (출처: Lawrence Chen 답변 트윗)

"I love cmux. If you're running AI coding agents you need this terminal. Ghostty-based, vertical tabs, built-in browser, and a unix socket API that lets you script everything." — (출처: X)
"Claude Code just became unstoppable with Cmux!"
"Conductor, Superset, or cmux. Which should you use?" — cmux가 에이전트 터미널 3강 구도에 포함 (출처: X)

Hacker News: 안정성 지적도 등장

"I switched to cmux for a while, but had to switch back to Ghostty due to its unreliability, high memory and CPU usage and a bunch of bugs."
(cmux를 한동안 썼지만, 불안정성과 높은 메모리/CPU 사용량 때문에 다시 Ghostty로 돌아가야 했다.)

— tekacs, HN "Show HN: Horizon" 토론, 2026-03-17

전체 감정 분석 (2026년 3월 기준)

긍정 (~80%)	"Game changer", Claude Code 필수 동반자, 에이전트 시대 정의
중립 (~10%)	경쟁 도구와의 비교 탐색, 관망
부정 (~10%)	안정성/메모리 이슈, AGPL 라이선스 우려, macOS 전용

(참고: 개발자 커뮤니티 종합, 2026-03-18 기준)

15. 제한사항과 미래 전망

현재 제한사항

macOS 전용: Swift + AppKit 기반이라 Linux/Windows 공식 지원 없음 (커뮤니티 포트 존재)
세션 복원의 한계: 레이아웃, 디렉토리, 스크롤백, 브라우저 URL은 복원되지만, 실행 중이던 프로세스는 복원되지 않는다
SSH 환경 미지원: GUI 앱이므로 헤드리스 서버에서 사용 불가 (tmux가 여전히 필수)
초기 단계: v0.62.2로 아직 1.0 이전, breaking change 가능성
AGPL-3.0 라이선스: 상용 통합 시 라이선스 조건 확인 필요
WKWebView 기반: DOM 조작, 스크린샷 등은 가능하지만, CDP 전용 기능(CPU/메모리 프로파일링 등)은 불가
소켓 간헐적 불안정: v0.62.x에서 "Connection refused" 발생 가능 (재시도로 해결)
화면 스크래핑 방식: read-screen은 화면에 렌더링된 텍스트를 읽는 RPA 방식이다. CLI 출력 형식이 바뀌면 파싱이 깨질 수 있다.

세션 복원에 대한 오해 방지

cmux의 세션 복원은 레이아웃과 컨텍스트를 복원하는 것이지, 실행 중이던 서버나 프로세스를 다시 시작해주는 것은 아니다.

(출처: cmux README — Session Restore)

미래 전망

크로스 플랫폼: 커뮤니티 Linux/Windows 포트가 이미 존재. 공식 채택 여부는 미정
에이전트 간 통신: 현재 단방향 read/send에서 양방향 메시지 교환으로 발전 가능
Ghostty 엔진: libghostty가 계속 발전 중이라 렌더링 개선이 자동 반영
터미널 vs IDE: Cursor 같은 AI IDE와의 공존 방식은 사용자 선택에 달린 문제

cmux는 도구 하나가 아니라 '개념의 신호탄'이다. "터미널끼리 말하게 하라"는 방향은 계속 확산될 것이다. cmux 창시자는 이 철학을 "a primitive, not a solution"으로 표현한다.

16. 트러블슈팅

문제	해결
`cmux: command not found`	cmux 앱 실행 확인. CLI 링크: `sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux`
소켓 연결 실패 (Connection refused)	cmux 앱 실행 확인 후 재시작. 소켓: `~/Library/Application Support/cmux/cmux.sock`
iTerm2에서 `CMUX_WORKSPACE_ID` 없음	환경변수는 cmux 터미널 내에서만 자동 설정됨
브라우저 열기 불안정	2단계로 분리: `cmux browser open` 후 `sleep 1 && cmux browser goto URL`
SSH 서버에서 cmux 사용 불가	macOS 네이티브 앱이므로 SSH 불가. 원격은 tmux 사용
OMC `/team`이 cmux 안 쓰는 이유	OMC 내부가 tmux를 직접 호출. npm 패키지라 변경 불가
Ghostty 설정 충돌	`~/.config/ghostty/config`를 cmux가 읽음. 문제 시 해당 라인 주석 처리
macOS 보안 경고 (Gatekeeper)	시스템 설정 > 보안 > "확인 없이 열기" 또는 `xattr -cr /Applications/cmux.app`

17. 자주 묻는 질문 (FAQ)

Q1. cmux는 무료인가요?

cmux 코어는 AGPL-3.0 오픈소스로 무료다. 별도의 "Founder's Edition" 유료 구독이 있으며, 우선 지원, AI 기능 조기 접근, iOS 앱, 클라우드 VM 등을 제공한다. (출처: cmux GitHub — License)

Q2. Ghostty를 별도 설치해야 하나요?

아니다. cmux는 libghostty를 임베드하고 있어 별도 설치 불필요. 다만, Ghostty 설정 파일(~/.config/ghostty/config)이 있으면 cmux가 읽어서 테마/폰트를 적용한다.

Q3. iTerm2나 Warp 대신 cmux를 써야 하나요?

AI 에이전트를 많이 쓰는 개발자라면 cmux가 유리하다. 에이전트 없이 일반 터미널 작업만 한다면 iTerm2나 Warp의 안정성이 더 높다. 에이전트 활용 여부가 선택 기준.

Q4. tmux와 cmux를 동시에 사용할 수 있나요?

가능하다. cmux Surface 안에서 tmux 세션을 실행할 수 있다. 다만 read-screen이 읽는 내용은 tmux가 렌더링한 화면이 되므로, 에이전트 API의 효용성은 다소 줄어들 수 있다.

Q5. 업데이트가 너무 잦은데 안정적인가요?

약 7주 만에 v0.62.2까지 도달, 24개 이상 릴리스. 안정성이 중요하면 brew pin cmux로 버전을 고정하거나, CHANGELOG에서 breaking change 확인 후 업데이트를 권한다.

Q6. Claude Code가 cmux를 tmux로 착각하는 경우?

프로젝트 CLAUDE.md에 "이 환경은 cmux입니다. tmux가 아닌 cmux CLI를 사용하세요."를 추가하면 된다. 대부분 한두 번 사용 후 자동 인식한다. (참고: 섹션 9 스크린샷)

Q7. 여러 AI 에이전트를 동시에 운영할 수 있나요? (리더-워커 패턴)

가능하다. 리더-워커 패턴이 커뮤니티에서 검증된 구성이다. 리더 에이전트가 cmux read-screen으로 워커 에이전트를 모니터링하고, cmux send로 수정 명령을 전달한다. 리소스 격리가 필요하면 Docker 컨테이너 활용을 권장한다. (출처: HN 창시자 코멘트)

18. 참고 자료

이 글에서 사용한 모든 명령어는 cmux --help 및 cmux browser --help (v0.62.2) 출력에서 직접 검증했습니다.
cmux는 빠르게 발전 중인 도구이므로, 버전 업데이트 시 cmux --help로 최신 명령어를 확인하는 것을 권장합니다.

cmux v0.62.2 기준 | 2026년 3월 23일 작성
명령어 검증: cmux --help 및 cmux browser --help 실제 출력 기반

저작자표시 비영리 변경금지 (새창열림)

'AI > DevTools for AI' 카테고리의 다른 글

[Python] 파이썬 로컬 개발 환경 설정 : AI 관련 코딩 실습 준비 (1)	2025.11.30
[Python 웹 환경] Google Colab 활용 가이드 : AI 관련 코딩 실습 준비 (0)	2025.11.18

Contents