flowchart LR P[pstart<br/>fzf 로 프로젝트 선택] --> S[tmux 세션 + claude] S --> H[Claude Code 훅<br/>Notification · Stop · Submit] H -->|파일 생성/삭제| F[~/.claude/tmux-waiting/세션명] F -->|5초 폴링| B[상태바 ⏳] F --> W[컨트롤 창<br/>별도 창 · 세 대 합산] W -->|switch-client -c| M[메인 창<br/>모니터 1]
상세
왜 만들었나
프로젝트마다 Claude Code 를 tmux 세션 하나로 띄워 놓고 쓰는데, 맥과 맥 미니와 리눅스 노트북을 합치면 열 개 가까이 됩니다. 한 대에 몰아넣고 ssh 로 들어가는 게 단순하기는 한데 들고 다니는 기계와 항상 켜 두는 기계가 다르다 보니 세 대가 됐고, 그러다 보니 어느 세션이 제 입력을 기다리는지 알 수가 없어서 탭을 하나씩 돌아보는 날이 이어졌습니다.
마침 herdr 같은 도구를 추천받아 살펴봤습니다. 잘 만들어져 있는데 제게 필요한 건 둘뿐이었습니다. 누가 기다리는지 보는 것, 그리고 그 세션으로 편하게 넘어가는 것. 그래서 그 둘만 tmux 위에 직접 얹어 보기로 했습니다. (한글 입력 쪽 이슈가 아직 열려 있는 도구를 세션 열 개의 바닥에 깔기는 조금 이르다고 본 것도 있습니다.)
감지는 훅으로
Claude Code 훅으로 했습니다. 권한을 묻거나 답을 마치고 기다리기 시작하면(Notification · Stop) 세션 이름으로 파일을 하나 만들고, 제가 입력하면(UserPromptSubmit) 지웁니다. tmux 는 그 폴더를 5초마다 읽어 그리기만 하면 됩니다. 원격 기계의 폴더는 ssh 로 병렬 조회해서 같은 목록에 합칩니다.
tmux 가 주는 것은 상태바에 셸 명령 출력을 넣는 것(status-right '#(…)'), 팝업(display-popup), prefix 없는 키(bind -n), 다른 클라이언트의 세션을 바꾸는 것(switch-client -c) 같은 부품까지입니다. 그 위의 대기 감지 · 상태별 정렬 · 원격 합산 · 컨트롤 창은 전부 얹은 것입니다. (세션 전환 자체는 tmux 내장 choose-tree 로도 됩니다. 거기엔 “누가 기다리는가” 가 없어서 따로 만든 것입니다.)
만든 것
| 어디 | 무엇 |
|---|---|
| 상태바 왼쪽 | 기계 │ 세션명 │ git 브랜치 배지. 폰(폭 100열 미만)에서는 세션명만 |
| 상태바 오른쪽 | 입력 대기 세션 목록. 노랑 = 다른 세션, 빨강 = 지금 보는 세션 |
Alt+g / Alt+G | 기다리는 세션을 팝업으로 겹쳐 띄움 / 탭 자체를 전환 |
Alt+j | fzf 세션 피커. ● 현재 · ⏳ 대기(시각) · ▶ 진행 중 · 유휴 N분 순으로 정렬, 원격 세션 포함 |
Alt+a | claude agents 팝업 — 이 기계의 Claude 세션을 idle/busy 로 나열 |
Alt+m | 이 창을 “메인” 으로 등록 (컨트롤 창이 전환할 대상) |
sessions | 컨트롤 창. 세 대의 세션을 기계별로 나열, 줄 클릭 = 메인 창 전환 |
pstart | fzf 로 프로젝트를 골라 tmux 세션 + Claude 일괄 시작 |
파일은 ~/.tmux.conf 에 source-file 한 줄, 스크립트는 ~/.claude/hooks/tmux-*.sh 열세 개, 원복 스크립트 하나입니다. 상태바 갱신은 5초 간격이고, 훅 타이밍은 권한 프롬프트 → 즉시 ⏳, 답변이 끝나고 제 차례 → 60초 뒤 ⏳, 제가 입력하면 해제입니다.
자리를 세 번 옮겼습니다
| 순서 | 어디에 | 왜 걷어냈나 |
|---|---|---|
| 1 | 상태바를 두 줄로 늘려 아랫줄에 전 세션 | 첫째 줄과 같은 정보가 두 번 보임 |
| 2 | herdr 처럼 왼쪽 사이드바 | 세션마다 32열을 먹고, 클릭한 줄을 역산하는 방식이 갱신 타이밍과 어긋남 |
| 3 | 별도의 작은 컨트롤 창 | 확정. 거기서 고르면 메인 창이 바뀜. 처음엔 두 번째 모니터에, 지금은 같은 모니터 옆에 |
tmux 는 어느 클라이언트에서든 다른 클라이언트의 세션을 바꿀 수 있어서(switch-client -c) 새로 만든 것은 거의 없고, 어느 창이 메인인지 기억하는 파일 하나가 전부입니다.
쓰는 방식은 둘
① 컨트롤 창을 옆에 붙여 두고. 처음에는 모니터 하나에 풀스크린 터미널, 두 번째 모니터에 sessions 컨트롤 창을 띄웠는데 고개를 돌려야 해서 불편했습니다. 지금은 모니터 하나에서 Termius 로 풀스크린 창 옆에 컨트롤 창을 붙여 씁니다. 창이 독립돼 있어서, 앞서 걷어낸 사이드바(풀스크린 창 안에 패널로 넣은 것)보다 훨씬 편합니다. 오른쪽에 세 대의 세션이 기계별로 모여 있고, 줄을 클릭하면 왼쪽 메인 창이 그 세션으로 바뀝니다.
② 창을 넓게 쓰고, 기다리는 세션이 뜨면 팝업 피커로. 모니터가 하나거나 화면을 다 쓰고 싶을 때입니다. 컨트롤 창 없이 하단 상태바만 보다가, 오른쪽에 ⏳ 세션이 나타나면 Alt+j 로 피커를 열어 옮깁니다.
시작은 pstart
프로젝트 폴더 목록을 fzf 로 고르면(TAB 으로 여러 개) 폴더마다 tmux 세션을 만들고 그 안에서 claude "/start" 를 띄웁니다. 즐겨찾기 파일이 있어 평소 쓰는 것만 보이고, 이전 대화를 이어받는 -c 와 퍼미션 모드 -m 이 있습니다.
설정은 dotfiles 저장소에 묶어 세 대에 같이 배포합니다.
직접 만들어 보려면
아래를 Claude Code 에 그대로 붙여 넣으면 같은 구조를 만들어 줍니다. 제 것과 똑같이 나오지는 않을 텐데, 구조가 단순해서 어느 쪽으로든 30분 안에 돌아갑니다.
프롬프트 펼치기
tmux 위에 Claude Code 세션 계기판을 만들어 줘. 구조는 이렇게.
1. 감지 — Claude Code 훅
- ~/.claude/settings.json 의 hooks 에 Notification 과 Stop 에서 실행되는 스크립트를 등록.
스크립트는 현재 tmux 세션 이름을 알아내서 ~/.claude/tmux-waiting/<세션명> 파일을 만든다.
- UserPromptSubmit 과 SessionEnd 에서는 같은 파일을 지운다.
- 세션 이름은 $TMUX_PANE 으로 tmux display-message -p '#S' 를 써서 얻는다.
2. 표시 — tmux 상태바
- ~/.tmux.conf 에 status-interval 5, status-right 에 스크립트 호출.
스크립트는 ~/.claude/tmux-waiting/ 의 파일 목록을 읽어 "⏳ 세션1 세션2" 형태로 출력하고,
현재 세션이 목록에 있으면 색을 다르게 한다.
3. 전환 — fzf 피커
- prefix j (그리고 prefix 없이 Alt+j) 에 display-popup 으로 fzf 를 띄운다.
목록은 tmux list-sessions 인데, 대기 중인 세션을 위로 올리고 ⏳ 표시를 붙인다.
고르면 switch-client -t 로 전환.
- prefix g 는 대기 중인 첫 세션으로 바로 전환.
4. (선택) 원격 기계
- ~/.tmux-hosts.conf 에 "라벨 ssh호스트" 를 한 줄씩 적어 두면,
피커가 각 호스트의 ~/.claude/tmux-waiting/ 과 tmux list-sessions 를 ssh 로 병렬 조회해
"라벨/세션명" 으로 같은 목록에 넣는다. 고르면 ssh -t 호스트 tmux attach -t 세션명.
5. (선택) 시작 — pstart
- 프로젝트 루트 폴더의 하위 폴더를 fzf --multi 로 고르면,
폴더마다 tmux new-session -d -s <폴더명> -c <경로> 'claude' 를 실행하는 셸 함수.
파일은 ~/.claude/hooks/ 아래에 두고, 설치 스크립트와 원복 스크립트도 같이 만들어 줘.
기존 ~/.tmux.conf 는 덮어쓰지 말고 source-file 한 줄만 추가해.남는 것
herdr 를 그대로 써도 됩니다. 다만 필요한 기능이 둘뿐이면 그 둘만 직접 얹는 것도 하루면 되고, 남의 도구 모양을 두 번 따라가 보고 나서야 제 책상에 맞는 자리가 나왔다는 점에서 해볼 만했습니다.