<div align="center">
<h1>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
<img alt="ccmux logo" src="https://raw.githubusercontent.com/epilande/ccmux/HEAD/assets/logo.svg" width="120">
</picture>
<br>ccmux
</h1>
</div>
<p align="center">
<strong>모든 AI 코딩 에이전트(Claude Code, Codex, Cursor 등)를 tmux에서 실행하세요: 필요한 에이전트로 이동하고, 작업 트리로 생성하며, 그들 사이에서 작업을 전달할 수 있습니다.</strong>
</p>
<p align="center">
<img alt="ccmux picker showing live agent sessions grouped by project" src="https://github.com/user-attachments/assets/e4c41e9c-9221-47e2-86d4-362dd799651a" width="900">
</p>
<p align="center">
<a href="https://ccmux.dev">웹사이트</a> ·
<a href="https://ccmux.dev/docs/">문서화(Documentation)</a>
</p>
❓ 왜 필요한가요?
여러 AI 코딩 에이전트 세션을 tmux 패널에 걸쳐 실행할 때, 어떤 세션이 유휴 상태인지, 어떤 것이 권한을 기다리고 있는지, 어느 패널로 전환해야 하는지 파악하기 어렵습니다. ccmux는 세션 활동을 모니터링하는 백그라운드 데몬과 실시간 세션 상태를 한눈에 보여주는 대화형 TUI(Text User Interface)를 통해 이를 해결합니다.
이는 기존의 tmux 워크플로우와 함께 작동합니다. 에이전트를 실행하거나 구동하는 방식을 변경할 필요가 없습니다. ccmux는 패널에 이미 실행 중인 것을 발견하므로, 지원되는 에이전트와 함께 tmux를 사용하고 있기만 하면 작동합니다.
내장 지원 기능: Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity, Copilot, Gemini CLI를 지원하며, 설정(config)을 통해 사용자 지정 에이전트 정의도 가능합니다.
✨ 기능
주요 기능
- 🎯 실시간 세션 상태(Live Session States): 모든 에이전트를 유휴(idle), 작업 중(working), 또는 대기 중(waiting, 권한/계획 승인/질문)으로 추적하며, 도움이 필요할 때 즉시 플래그를 지정합니다.
- 🧩 다중 에이전트(Multi-Agent): Claude Code, Codex, Cursor, OpenCode, Pi, Antigravity, Copilot, Gemini CLI 외에도 설정(config)을 통해 사용자 정의 에이전트를 지원합니다.
- 🔄 실시간(Real-Time): 백그라운드 데몬(daemon)이 상태 변경을 SSE(Server-Sent Events)를 통해 즉시 스트리밍하며, 폴링이나 새로고침 과정이 필요 없습니다.
- 👁️ 실시간 미리보기(Live Preview): 선택된 세션의 패널 콘텐츠를 분할 화면으로 보여줍니다.
- ⚡ 제자리 작동(Act in Place): 미리보기 창을 탭하여 승인, 답변 또는 타이핑을 진행할 수 있으며, 입력 키가 해당 패널로 바로 전달됩니다.
- 🔔 조치 가능한 알림(Actionable Notifications): 데스크톱 알림에서 대기 중인 에이전트를 즉시 승인, 거부하거나 답장할 수 있습니다.
- 🪟 사이드바 모드(Sidebar Mode): 작업 패널 옆에 항상 표시되는 간결한 세션 레일을 제공합니다.
- 🔍 퍼지 검색(Fuzzy Search): 프로젝트, 브랜치 또는 경로별로 퍼지 매칭을 수행하며, 모든 최근 프롬프트, 캡처된 패널 콘텐츠, 그리고 온디맨드 실시간 전사본(live transcripts)에 대해 부분 문자열 매칭이 가능합니다.
- 📂 세션 그룹화(Session Grouping): 재정렬 및 고정(pinning)이 가능한 접을 수 있는 프로젝트 그룹을 제공합니다.
- 🌿 Git 및 PR 인식(Git & PR Aware): 브랜치 및 워크트리 감지, 실시간 CI(Continuous Integration) 및 검토 상태가 표시되는 열린 PR(Pull Request) 지원 기능을 갖추고 있습니다.
- 🌱 워크트리 워크플로우(Worktree Workflow): 새로운 Git 워크트리로 세션을 생성하거나 포크(fork)할 수 있으며, 커밋되지 않은 변경 사항을 더러운 체크아웃(dirty checkout)에서 이동시키고, 워크트리 패널의 잔여물을 정리할 수 있습니다.
- 📝 차이점 검토(Diff Review): <kbd>d</kbd>를 눌러 세션의 워킹 트리의 차이점을 hunk와 함께 패널 내에서 검토하거나, <kbd>D</kbd>를 눌러 브랜치가 포크된 이후 변경된 모든 내용을 검토할 수 있습니다.
- 🤖 백그라운드 에이전트 및 서브에이전트(Background Agents & Subagents): Claude Code의 백그라운드 에이전트도 행 형태로 표시됩니다. 실행 중인 서브에이전트는 미리보기에서 실시간 목록과 함께 'agents'로 표시됩니다.
- 🎛️ 세션 제어(Session Control): TUI(Terminal User Interface)에서 세션을 생성, 포크, 종료 및 재시작할 수 있으며, 스크립트화된 일회성 에이전트 턴을 위해
ccmux invoke를 사용할 수 있습니다.
- 🤝 세션 인계(Session Handoff): 세션의 마지막 응답을 CLI, 행 메뉴 또는 번들로 제공되는 릴레이 스킬(relay skill)을 통해 에이전트 간에 보낼 수 있습니다.
⌨️ 키보드 우선(Keyboard-First), 마우스 사용에 편리함: Vim 키와 숫자 점프 기능, 클릭하여 전환 및 오른쪽 클릭 컨텍스트 액션 제공
📦 설치 (Installation)
필수 조건 (Prerequisites)
- 활성 세션을 실행 중인 AI 코딩 에이전트가 있는 tmux
- git 2.31 이상 버전 (브랜치 및 워크트리 감지를 위해 필요함; ccmux는 이 정보 없이도 작동하지만, 기능 제한이 있음)
Homebrew
brew install ccmux
ccmux setup
소스 코드로부터 (From Source)
Bun이 필요합니다.
git clone https://github.com/epilande/ccmux.git
cd ccmux
bun install
...
ccmux setup은 권한 있는 세션 매칭을 위한 에이전트 후크(agent hooks)를 설치합니다. ccmux는 이것 없이도 작동하지만, 사용하는 것을 권장하며 후크를 사용한 세션 매칭을 참조하세요. 단순히 ccmux setup만 실행하면 PATH에서 찾을 수 있는 에이전트만 구성됩니다. 특정 에이전트에 설치하려면 --agent <이름> 플래그를 사용하세요 (감지되지 않더라도).
셸 완성 기능 (Shell Completions)
ccmux completion <셸 이름>은 zsh, bash 또는 fish용 완성 스크립트를 출력합니다. 이 스크립트는 명령어와 플래그를 완성하며, 실행 중인 데몬(daemon)에게 실시간 값(세션 ID 및 %pane ID 등 명령어가 값을 요구하는 모든 곳), 에이전트 이름, 호출 ID, 설정 키 및 그 값을 요청합니다. --cwd와 같은 디렉토리 플래그는 셸 자체의 경로 완성 기능으로 전달됩니다.
eval "$(ccmux completion zsh)"
...
zsh에서 eval은 스크립트가 compdef에 자신을 등록하기 때문에 반드시 compinit 이후에 실행되어야 합니다. 파일 시스템 경로(fpath)를 이용하는 방법은 이 과정을 우회하여 모든 셸 시작 시 ccmux가 실행되는 것을 방지합니다: ccmux completion zsh > ~/.zfunc/_ccmux를 사용하고, compinit 전에 fpath=(~/.zfunc $fpath)를 설정하세요. Homebrew 공식은 세 가지 셸 모두에 대한 완성 기능을 설치해 줍니다.
🚀 빠른 시작 (Quick Start)
- 평소처럼 tmux 패널에서 AI 코딩 세션을 시작합니다.
- 피커(picker)를 실행합니다:
ccmux
3. <kbd>j</kbd>/<kbd>k</kbd>로 이동하고, <kbd>Enter</kbd>를 눌러 세션으로 전환합니다.
> [!TIP]
> 어디서든 ccmux를 팝업으로 열 수 있도록 tmux 키에 바인딩하세요 (`~/.tmux.conf`에 추가):
>
> ```tmux
> # Prefix + C-p: open ccmux in a centered popup
> bind-key C-p display-popup -E -w 80% -h 75% "ccmux"
> ```
>
> 위의 바인딩을 사용하면 ccmux가 팝업을 연 터미널에 관계없이 자체적으로 작동합니다. 따라서 세션을 선택하면 해당 터미널이 전환되고, 다른 연결된 클라이언트는 원래 위치를 유지합니다. 피커는 선택 후 종료되므로 팝업은 스스로 닫히고 바로 해당 패널로 이동하게 됩니다. (`display-popup`은 tmux 3.2 이상이 필요합니다.)
>
> 만약 동일한 tmux 세션에 두 개의 터미널을 연결하거나, 바인딩이 누르는 터미널이 보고 있는 세션이 아닌 다른 세션에서 팝업을 여는 경우, ccmux에게 클라이언트를 명시적으로 전달해야 합니다:
>
> ```tmux
> bind-key C-p run-shell -C 'display-popup -E -w 80% -h 75% "ccmux --client-tty #{client_tty}"'
> ```
>
> `run-shell -C` 래퍼가 `#{client_tty}`를 확장시키는 역할을 합니다. 이는 `display-popup`이 자체 명령을 절대 확장하지 않기 때문입니다. 이전에 문서화된 `-e "CCMUX_CLIENT_TTY=#{client_tty}"` 형식은 tmux 3.3 이상에서도 여전히 작동합니다.
## 🎮 사용법 (Usage)
### CLI 명령어 (CLI Commands)
| 명령어 | 설명 |
| :--- | :--- |
| `ccmux` | 대화형 TUI(Text User Interface) 피커를 실행합니다 (기본값) |
| ... | |
데몬은 ccmux 명령(피커, show, invoke 등)을 처음 실행할 때 자동으로 시작됩니다. 이는 `127.0.0.1:2269`에서 실행되며 REST API와 SSE 이벤트 스트림을 모두 제공합니다.
### 미리보기 패널 (Preview Pane)
⚠️ `[IMG:N]` 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
<kbd>P</kbd>를 누르면 피커가 분할되고, 강조 표시된 세션의 실시간 창(live pane) 내용을 나란히 미리 볼 수 있습니다. <kbd>Tab</kbd>을 누르면 미리 보기 창에 포커스가 맞춰지고 제자리에서 작업을 수행할 수 있습니다. 입력한 키스트로는 해당 에이전트의 창으로 바로 전달되므로, ccmux를 떠나지 않고도 권한 승인, 질문 답변 또는 후속 내용 작성이 가능합니다.
미리 보기 헤더는 세션 이름을 표시합니다. 프로젝트 이름이 굵게 표시되고, 이후 해당 세션에 대한 에이전트 자체의 요약(요약을 제공하는 에이전트: Claude Code, Codex, OpenCode, Cursor, oh-my-pi, Copilot가 이 기능을 수행하며, 나머지 에이전트는 이 항목이 생략됩니다)이 이어지고, 마지막으로 작업 디렉터리 및 브랜치/버전/타겟 메타데이터가 표시됩니다.
세션에 에이전트가 실행 중일 경우, **Agents** 섹션에서 각 에이전트와 그 실행 상태(runtime)를 나열합니다. 완료된 에이전트는 목록에서 사라집니다.
### Hunk를 사용한 Diff 검토
`[hunk](https://github.com/modem-dev/hunk)`는 터미널용 디프(diff) 검토기입니다. `hunk`가 `PATH`에 설정되어 있다면, 피커에서 <kbd>d</kbd>를 눌러 ccmux를 벗어나지 않고 선택된 세션의 작업 트리(working-tree) 디프를 검토할 수 있습니다. 이때 피커는 일시 중지되고, `hunk diff --watch`가 세션 리포지토리 루트의 창을 차지하며, hunk가 종료되면 피커가 재개됩니다. 동일한 동작은 행 메뉴(<kbd>m</kbd>, 또는 마우스 오른쪽 버튼 클릭)에서도 가능합니다. 만약 작업 트리에 변경 사항이 없다면, ccmux는 빈 검토를 여는 대신 이를 보고합니다.
⚠️
<kbd>Shift+D</kbd>는 다른 차이점(diff)을 검토합니다. 이는 커밋되지 않은 내용뿐만 아니라 체크아웃된 내용이 **포크된 이후** 변경한 모든 내용을 포함합니다. 이것이 바로 워크트리(worktree)에서 작업하는 에이전트에 대해 물어볼 가치가 있는 질문입니다. 워크트리는 진행하면서 커밋하고, 브랜치 자체가 핵심임에도 불구하고 종종 비어있는 작업 트리를 갖기 때문입니다. 비교 기준점은 `ccmux spawn --worktree`가 해당 브랜치를 생성했을 때 기록한 내용이며, ccmux가 생성하지 않은 체크아웃의 경우 레포지토리 기본 브랜치와의 병합 기준점(merge-base)으로 대체됩니다. 이 기준점을 넘어서 자체 커밋이 없는 체크아웃은 비교할 포크 지점이 없으므로 <kbd>D</kbd>는 작업 트리를 보여주며, 이는 <kbd>d</kbd>와 동일합니다. 하지만 푸시되지 않은 커밋을 가진 메인 체크아웃은 포크 지점을 가지고 있으며, <kbd>D</kbd>가 이 내용도 보여줍니다.
에이전트에게 검토 피드백을 보내는 방법:
1. hunk에서 <kbd>c</kbd>를 눌러 줄 주석을 달고, <kbd>Ctrl+S</kbd>를 눌러 메모를 저장합니다.
2. 다른 검토 메모가 있다면 추가하고 hunk를 종료합니다.
3. 피커(picker)가 재개될 때 **검토 의견 보내기**를 확인합니다. ccmux는 짧은 소스 스니펫을 포함하여 캡처된 모든 메모를 하나의 프롬프트로 에이전트에게 전송하며, 상태를 확인할 수 있도록 피커에 머무릅니다.
해당 기능은 hunk의 세션 JSON 명령어(`hunk session list` / `session comment list`)에 의존합니다. 구형 hunk를 사용하는 경우 검토 자체는 여전히 작동하지만, 해당 옵션만 나타나지 않습니다.
`reviewHandback` 설정(preference)은 hunk가 종료될 때 발생하는 상황을 제어합니다:
- `confirm`(기본값): 프롬프트를 보내기 전에 사용자에게 묻습니다.
- `auto`: 대화 상자 없이 즉시 프롬프트를 전송하고 제출합니다.
- `fill`: 프롬프트를 에이전트의 컴포저에 붙여넣지만 제출하지는 않습니다. 이 텍스트는 세션으로 이동하여 직접 제출하거나 편집할 때까지 유지되며, 나중에 전송하거나 호출하면 여기에 내용이 추가되어 있을 수 있습니다.
검토 기능은 CLI(Command Line Interface)에서도 실행됩니다:
```bash
ccmux review # 현재 디렉터리 레포지토리 검토
ccmux review <id> # ID를 사용하여 세션의 레포지토리 검토
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
hunk를 brew install hunk로 설치합니다. <kbd>d</kbd> 푸터 힌트와 도움말 항목은 hunk가 실행 시 PATH에서 감지될 때만 나타납니다.
작업 창(working panes) 옆에 항상 표시되는 작고 간결한 세션 목록입니다. 미리 보기 패널이나 푸터 없이 상태 아이콘과 프로젝트 이름만 표시됩니다.
<p align="center">
<img alt="ccmux sidebar alongside working panes" src="https://github.com/user-attachments/assets/742642cf-b90b-445d-bc9a-38b6cfa0ab79" width="900">
</p>
ccmux sidebar --toggle
ccmux sidebar --toggle --width 40
ccmux sidebar --toggle --position right
...
이 스마트 토글은 일부 창에 사이드바가 없을 때 빈 공간을 채우고, 모든 창이 이미 사이드바를 가지고 있을 때는 모든 사이드바를 제거합니다. 새 창에는 자동으로 사이드바가 생성되며, 창 크기가 조정될 때 사이드바는 설정된 너비로 돌아갑니다(snap back).
--toggle이 선호하는 레이아웃을 사용하도록 기본값을 구성합니다:
ccmux config set sidebar.width 40
ccmux config set sidebar.position right
권장되는 tmux 키 바인딩 (~/.tmux.conf에 추가):
bind-key S run-shell "ccmux sidebar --toggle"
tmux 상태 표시줄 (status line)
데몬은 세션 수와 창 주의 표시(window attention marks)를 자동으로 게시합니다. 사용자가 자신의 ~/.tmux.conf 형식에서 옵션을 참조하기 전까지는 눈에 띄게 아무것도 변경되지 않습니다 (ccmux가 편집하지 않음):
set -g status-right '#{@ccmux_status} %H:%M'
set -g window-status-format '#I:#W#{@ccmux_mark}'
set -g window-status-current-format '#I:#W#{@ccmux_mark}'
tmux source-file ~/.tmux.conf로 다시 로드합니다. 게시 기능을 완전히 비활성화하려면, ccmux config set statusBar.enabled false를 설정하고 데몬을 재시작하십시오. 게시 기능은 tmux 서버가 사용 가능하지 않을 때 일시 중지되며, 데몬이 이를 감지하면 다시 시작됩니다.