ccm — Claude Code Manager for tmux
ccm은 한 번에 여러 프로젝트에서 Claude Code를 실행하는 개발자를 위한 tmux 플러그인입니다. 각 Claude 세션은 라이브 상태 감지 기능이 있는 태그가 지정된 tmux 창이 됩니다. 따라서 어떤 창이 응답 중인지, 어떤 창이 승인을 기다리는지, 어떤 창이 유휴 상태인지 기억하려고 창을 전환할 필요가 없습니다.
이는 본질적으로 주의력 관리자(attention manager) 역할을 합니다: 모든 프로젝트는 상태(BUSY / IDLE / permission 대기)를 가지며, 대시보드는 이를 긴급도 순으로 정렬하고, 한 번의 키 입력만으로 다음에 필요한 곳으로 이동할 수 있게 해줍니다.
팝업 대시보드를 통해 모든 프로젝트의 상태(busy / idle / waiting for permission), git 브랜치, 리스닝 포트를 한눈에 확인할 수 있습니다. 스냅샷 기능은 tmux 재시작 후에도 프로젝트 창을 복원해 줍니다. 데스크톱 알림은 주의가 필요한 프로젝트만 표시합니다.
ccm의 가치는 병렬 처리 수준에 따라 커집니다: 2~3개 프로젝트에서 유용하며, 4개 이상의 프로젝트에서는 일일 인프라로 활용 가능합니다. 여러 프로젝트에서 에이전트를 병렬로 실행하는 Max-tier 사용자에게 가장 적합합니다.
프로젝트(project) 하나는 폴더(folder) 하나, 그리고 tmux 창(tmux window) 하나와 같습니다. 하나의 창은 임의의 수의 패널(Claude Code, 셸, 개발 서버, Agent Teams 팀원 등)을 포함할 수 있습니다. 각 Claude Code 패널의 상태(PERMIT / BUSY / IDLE)는 해당 창으로 집계되며, ccm 대시보드 (prefix + Tab)를 통해 창 간 전환이 이루어집니다.
대시보드(Dashboard) (prefix + Tab)에는 하단에 모드-2 상태 표시줄이 보입니다:
- 리소스 관리(Resource Management) — 유휴 Claude Code 세션은 메모리와 CPU를 확보하기 위해 10분 후 자동으로 종료되며, 다시 전환할 때 자동 재시작 및 재개됩니다.
- 대시보드(Dashboard) — 실시간 Claude Code 상태(BUSY / IDLE / PERMIT)가 표시되는 대화형 팝업입니다.
- 트리 뷰(Tree View) — 탐색 기능이 있는 계층적 세션/창/패널 디스플레이입니다.
- Git 통합(Git Integration) — 프로젝트별 git 브랜치와 dirty 상태 표시기가 제공됩니다.
- 포트 감지(Port Detection) — 프로젝트별 리스닝 포트를 보여줍니다.
- 스냅샷(Snapshots) — 프로젝트를 저장하고 해당 창을 복원합니다.
- 프로젝트 간 메시징(Cross-Project Messaging) —
ccm send <project> <message> 명령어를 사용합니다.
상태 기반 안전 게이팅(state-based safety gating, PERMIT-safe)을 통해 프로젝트 간에 프롬프트를 전달하며, 대상이 바쁠 때는 나중에 전송하기 위한 큐잉(queues, store-and-forward) 기능을 제공합니다.
권한 모드 가시성 (Permission-Mode Visibility) — 각 프로젝트의 Claude Code 권한 모드(manual / accept / plan / auto / bypass)가 ccm status 및 대시보드에서 표시되어 "이 프로젝트는 절대로 권한을 요청하지 않는다"라는 것이 미스터리가 되지 않게 합니다.
Sidekick 지원 (Sidekick Support) — Claude 옆에 분할 창으로 두 번째 에이전트 CLI를 실행합니다. ccm은 이를 자체 추적 목록에서 제외하고 존재함을 표시합니다. 다른 모델 실행 및 두 번째 에이전트 CLI로 릴레이(Relaying with a second agent CLI) 사용법을 참고하세요.
자동 시작 (Auto-start) — Claude Code는 아직 실행되고 있지 않은 프로젝트에 연결할 때 자동으로 시작됩니다.
상태 라인 (Status Line) — 활성 프로젝트 상태를 tmux status bar에 주입합니다.
다중 바이트 텍스트 (Multi-byte text) — 프로젝트 이름의 CJK 문자 및 이모지가 대시보드, 상태 표시줄, CLI 테이블에서 올바르게 정렬됩니다.
Agent Teams 호환 (Agent Teams Compatible) — Claude Code의 Agent Teams와 함께 작동합니다: ccm으로 프로젝트를 관리하면서 각 프로젝트 내에서 병렬 에이전트를 실행할 수 있습니다.
- tmux 3.2 이상
- Python 3.9 이상
- TPM (또는 수동 설치)
- jq
- fzf
- Claude Code
v2.1.107+(본 페이지 상단의 배지에서 확인 가능하며, v2.1.288을 기준으로 테스트되었습니다.)
~/.tmux.conf 파일에 추가하세요.
:
set -g @plugin 'yohasebe/tmux-ccm'
tmux를 다시 로드하고 prefix + I를 눌러 설치합니다.
ccm은 표준 플러그인 진입점(standard plugin entry point)을 사용하므로, TPM 호환 모든 플러그인 관리자에서 작동합니다 — TPM 또는 tpack과 같은 대체재가 가능합니다. 어느 쪽이든 ccm 전용 설정은 필요하지 않습니다.
git clone https://github.com/yohasebe/tmux-ccm.git ~/.tmux/plugins/tmux-ccm
~/.tmux.conf 파일에 추가하세요.
:
source-file ~/.tmux/plugins/tmux-ccm/ccm.tmux.conf
CLI 사용(ccm add, ccm status 등)을 위해서는 플러그인 디렉토리를 PATH에 추가해야 합니다:
# .zshrc 또는 .bashrc 파일에서
export PATH="$HOME/.tmux/plugins/tmux-ccm:$PATH"
# .zshrc 파일에서 (compinit 이전에)
fpath=($HOME/.tmux/plugins/tmux-ccm/completions $fpath)
Claude Code를 사용해 본 적이 없다면, 먼저 초기 인증을 완료해야 합니다.
claude
이 명령을 실행하면 플랜(구독 또는 API 키)을 선택하고 브라우저를 통해 인증하는 대화형 설정 화면이 열립니다. 인증을 완료한 후, 다음 설정 마법사를 실행하세요:
ccm init
이 명령어는 연결 훅 설치, 자동 복원 기능, 상태 표시줄 구성을 한 번에 안내합니다.
참고
훅은 플러그인 로드 시(TPM을 통해) 자동으로 설치되며, 플러그인 업데이트 시 최신 상태로 유지됩니다. 수동 제어를 선호하는 경우 ccm setup-hooks와 ccm remove-hooks를 사용하세요.
| 키 | 동작 | 기본값 |
|---|
prefix + Tab | 대시보드 팝업 토글 | 활성화됨 |
prefix + T | 트리 뷰 팝업 토글 | 비활성화 (선택 사항) |
prefix + C | ccm 메뉴 열기 | 비활성화 (선택 사항) |
기본적으로 충돌을 방지하기 위해 대시보드 키 바인딩만 활성화됩니다. 트리 뷰와 메뉴는 대시보드 내에서 t 또는 m을 눌러 접근할 수도 있습니다.
대시보드 키 바인딩을 재정의하거나 선택적 바인딩을 활성화하려면 ~/.tmux.conf에 다음 내용을 추가하세요:
중요
모든 set -g @ccm-* 옵션은 ~/.tmux.conf에서 ccm 플러그인이 로드되기 전에 배치되어야 합니다.
— 즉, source-file 라인(수동 설치)과 TPM의 run 라인(TPM 설치) 모두보다 전에 위치해야 합니다. 이 플러그인은 로드 시점에 옵션을 읽기 때문에, 나중에 설정된 값은 조용히 무시됩니다.
set -g @ccm-key-dashboard "Tab" # 기본값; 재할당하려면 수정 (예: "F12")
set -g @ccm-key-menu "C" # 선택 사항: 메뉴를 위해 prefix + C 활성화
set -g @ccm-key-tree "T" # 선택 사항: 트리 뷰를 위해 prefix + T 활성화
...
팁
더 빠른 접근을 원한다면, @ccm-key-dashboard-noprefix를 사용하여 단일 키(prefix 없음)에 대시보드 토글 기능을 바인딩할 수 있습니다. 예를 들어 F1을 사용하려면:
# ccm 플러그인 로드 라인보다 전에 와야 합니다 (위의 중요 참고).
set -g @ccm-key-dashboard-noprefix "F1"
F1을 누르면 열리고, 다시 F1을 누르면 닫힙니다. 팝업 제목에 있는 색상이 지정된 ccm 로고는 유지됩니다 (직접 bind-key -n F1 display-popup …를 작성하는 것은 기계적으로 작동하지만, 전체 -T 형식 문자열을 복제하지 않으면 로고가 손실됩니다.)
프로젝트 상태가 변경될 때 데스크톱 알림(macOS 및 Linux)을 보낼 수 있습니다:
set -g @ccm-notify "permit,completed" # PERMIT 및 완료 시 알림
| 값 | 동작 |
|---|
permit,completed (기본값) | 권한 요청 및 완료 시 알림 |
permit | 권한이 필요할 때 알림 |
completed | 완료 시 알림 (Claude가 응답을 마쳤을 때) |
all | 모든 상태 변경 |
off | 알림 없음 |
알림 소리 활성화:
set -g @ccm-notify-sound "on" # 기본값: off (macOS에서 "Glass" 사운드 재생)
set -g @ccm-notify-sound-name "Ping" # 선택 사항: 사운드 사용자 정의 (macOS 전용)
기본적으로 ccm은 macOS 알림을 위해 osascript를 사용합니다. 각 알림은 Notification Center에 추가되며, 사용자가 해제할 때까지 남아 있습니다. 장시간 실행되는 다중 프로젝트 설정의 경우 수백 개의 오래된 알림이 쌓여 WindowServer / NotificationCenter에 높은 CPU 부하를 줄 수 있습니다.
terminal-notifier 설치는 이를 해결합니다. ccm은 프로젝트별 그룹 ID(-group ccm-<project>)를 보내므로, 동일한 프로젝트에 대한 새로운 알림은 Notification Center에서 이전 알림을 쌓지 않고 대체합니다.
brew install terminal-notifier
ccm은 PATH에서 이를 자동 감지하고 우선적으로 사용합니다. 설정이 필요하지 않습니다.
중요
terminal-notifier가 알림을 보내는 첫 번째 경우, macOS에서 권한 대화 상자가 표시될 수 있습니다. 승인해 주세요. 이후 ccm 알림이 보이지 않으면 시스템 설정 → 알림 → terminal-notifier를 열고 "알림 허용"이 켜져 있는지 확인하세요. 알림은 terminal-notifier의 자체 번들 ID(사용하는 터미널 에뮬레이터와 무관)로 전달되므로, 승인은 일회성이며 Terminal.app / iTerm2 / WezTerm / kitty / ghostty에서 동일하게 작동합니다.
Notification Center에서 ccm 알림을 대량으로 지우려면 (terminal-notifier 필요):
ccm clear-notifications
이것은 ccm-으로 접두사가 붙은 그룹 ID를 가진 알림만 제거합니다.
— 다른 터미널에서 발생하는 알림(배포 경고, 모니터링 등)은 그대로 유지됩니다. 이 명령어는 제거한 항목의 개수를 보고합니다.
만약 terminal-notifier를 설치할 수 없고 축적 문제를 발견하면, @ccm-notify "permit"을 설정하여 조치가 필요한 PERMIT 알림만 받고 더 자주 발생하는 COMPLETED 알림은 건너뛸 수 있습니다.
ccm은 Linux에서 notify-send를 사용합니다. macOS의 -group에 해당하는 프로젝트별 중복 제거 기능이 없으므로, 장시간 실행되는 세션의 볼륨을 제한하려면 @ccm-notify "permit"을 설정하십시오.
ccm clear-notifications는 macOS 전용입니다. Linux에는 기존 알림을 열거하거나 제거할 수 있는 명령줄 API가 없기 때문에, 이 명령어는 "terminal-notifier is not installed"라고 보고하고 종료됩니다.
ccm은 tmux 상태 표시줄에 활성 프로젝트 상태를 보여줍니다. 표시 모드를 구성하십시오:
set -g @ccm-status-line 2 # default
| 값 | 모드 | 설명 |
|---|
0 | 아이콘 (Icon) | 우선순위 아이콘과 창 인덱스가 status-right에 추가됩니다 (가장 보수적이며 — tmux의 기존 chrome을 변경하지 않습니다) |
1 | 전체 (Full) | 창 목록을 ccm 스타일의 색상 항목으로 대체합니다 |
2 | 전용 라인 (Dedicated line) (기본값) | 모든 프로젝트에 대한 브랜치/포트 세부 정보와 함께 메인 바 아래에 전용 상태 라인을 추가합니다 |
모드 2가 기본값입니다. 기존 tmux 테마를 그대로 유지하고 싶다면 모드 0이 가장 보수적인 선택지입니다.
모드 1은 tmux의 창 목록을 완전히 대체하므로, ccm이 관리하지 않는 창은 사라집니다. 일반적인 tmux 작업을 같은 세션에서 계속하려면 모드 0 또는 2를 선택하십시오 — 둘 다 창 목록을 그대로 유지합니다.
등록된 프로젝트가 많으면 대부분의 시간 동안 SHELL 상태이며, 도움이 필요한 하나를 놓치기 쉽습니다. 모드 1과 2는 Claude 세션을 호스팅하는 창만 나열할 수 있습니다:
set -g @ccm-status-line-hide-shell on
IDLE 프로젝트는 계속 표시됩니다 — 세션이 살아 있고 대기 중이며, 이때 턴이 끝나면 * elapsed 마커가 나타납니다. 오직 SHELL
숨겨짐(hidden)을 확인하세요. 유휴 세션은 CCM_IDLE_EXIT_TIMEOUT 후에 자동으로 종료되므로, 방치된 프로젝트는 세션이 끝나면 바에서 사라지고, 다시 연결하여 Claude가 재시작되면 돌아옵니다. 대시보드와 ccm status는 항상 모든 프로젝트를 나열합니다.
Mode 1은 status-right에 쓰기 때문에 tmux가 오른쪽 정렬로 그리며, 따라서 항목들이 시계 옆에 위치하고 가장 높은 우선순위의 것이 가장 오른쪽에 있습니다. 이 쪽이 바 공간이 부족할 때 살아남습니다. 만약 왼쪽에서 오른쪽으로 읽고 싶다면:
set -g @ccm-status-line-position left
항목들이 바의 먼 쪽, 즉 가장 높은 우선순위부터 채워지며 빈 창 목록 자리를 채웁니다. status-left에는 아무것도 쓰이지 않습니다. 이 항목들을 이동시키는 패딩은 status-right에 있으므로, 테마의 왼쪽 부분이 손상되지 않습니다. 바가 너무 좁아서 해당 세그먼트 아래로 밀려나지 않게 배치하려면, ccm은 가장 보고 싶은 항목을 잘라내는 대신 오른쪽 레이아웃을 유지합니다.
기존 status-right(시계 등)에 우선순위 아이콘과 창 인덱스를 추가합니다. 활성 프로젝트가 존재할 때, 창 번호가 표시됩니다 (예: 5: PERMIT ⚠). 모든 것이 유휴 상태일 때는 단일 ≡ 아이콘이 표시됩니다:
... 기존 status-right ... 5: PERMIT ⚠ 14:32
└────────────┘
창번호 + 최고 우선순위 상태
| 우선순위 | 조건 | 아이콘 | 색상 |
|---|
| 1 (최고) | 프로젝트 중 하나가 PERMIT인 경우 | ⚠ | 노랑 |
| 2 | 프로젝트 중 하나가 BUSY인 경우 | ◉ | 주황 |
| 3 (최저) | 모든 프로젝트가 IDLE인 경우 | ≡ | 회색 |
아이콘을 클릭하여 전체 세부 정보를 위한 대시보드를 엽니다.
표준 tmux 창 목록을 프로젝트 이름과 상태 아이콘을 보여주는 ccm 스타일의 항목으로 대체합니다. 기존 status-right(시계 등)는 보존됩니다.
2:weather-cli ● 3:recipe-blog ◉ 4:todo-react ◉ 5:api-server ⚠
메인 바 아래에 하나 이상의 tmux 상태 표시줄을 추가합니다. 사용 가능한 경우 git 브랜치와 포트 세부 정보를 포함하여 유휴(idle) 프로젝트를 포함한 모든 프로젝트를 보여줍니다. 메인 상태 바는 수정되지 않습니다. (위의 대시보드 스크린샷 참조 — 하단 행은 모드 2가 작동하는 모습을 보여줍니다.)
... 일반적인 상태 표시줄, 변경 없음 ... 14:32
────────────────────────────────────────────────────────────────────── (gutter)
5:api-server (main) ⚠ PERMIT · 3:recipe-blog (main) ◉ BUSY
...
| 상태 | 아이콘 | 색상 |
|---|
| PERMIT | ⚠ | 노란색 |
| BUSY | ◉ | 주황색 |
| IDLE | ● | 파란색 |
| IDLE (최근 완료) | 프로젝트 이름 뒤에 * <경과 시간> 표시 | 녹색 |
| SHELL | ■ | 짙은 회색 |
라인은 터미널 너비와 프로젝트 수에 따라 자동으로 확장됩니다.
만약 어두운 회색 구획(gutter)이 사용자의 테마와 충돌한다면, tmux 옵션을 통해 기본 색상 팔레트를 재정의할 수 있습니다:
