tmux 연동
tmux는 multi-saas-kit에서 Claude Code의 운영 대시보드 역할을 합니다. 3줄 상태바 + 하단 pane-border에 세션 정보, LLM 상태, 작업 요약이 실시간 표시됩니다.
상태바 레이아웃
┌─────────────────────────────────────────────────────────────────┐
│ [__claude] 세션 메모 1줄 CPU:5% MEM:32% [f1f43][H 05] │ ← 1줄
│ 세션 메모 2줄 (+3) GS(3470) GU(53) PS(76) │ ← 2줄
│ 💬 ai-core 설계 문서 작성 │ ← 3줄
├──────────────────────────────────────── ─────────────────────────┤
│ │
│ Claude Code 터미널 │
│ │
├─────────────────────────────────────────────────────────────────┤
│ [H 0:31, 13msg] O:✅ K:✅ C:⏳ G:❌ │ ← pane-border
└─────────────────────────────────────────────────────────────────┘
영역별 정보
| 위치 | 좌측 | 우측 |
|---|---|---|
| 1줄 | [세션명] + 메모 1줄 | CPU/RAM + 세션 ID [f1f43] + Handoff [H 05] |
| 2줄 | 메모 2줄 + 잔여줄 수 (+N) | PI (프롬프트 주입 상태) |
| 3줄 | (빈 공간) | 💬 마지막 작업 요약 |
| 하단 border | Handoff 경과 + 메시지 수 | Multi-LLM 프로바이더 상태 |
핵심 활용 팁
1. 세션별 메모 (Ctrl+\)
가장 자주 쓰는 기능. prefix 없이 바로 vim 팝업이 열립니다.
| 단축키 | 동작 |
|---|---|
Ctrl+\ | 메모 편집 (vim 팝업, 빠른 접근) |
Ctrl+A → n | 메모 편집 (prefix 방식) |
Ctrl+A → N | 새로고침 |
메모 파일: ~/.config/tmux-notes/{session_name}.txt
# __claude.txt 예시
TODO: .ai-core config 재설계
- global.json 토글 통일
- detail/ 분리 완료
2. 작업 요약 자동 표시
3줄 우측에 Claude가 매 턴 기록하는 작업 요약이 표시됩니다.
# AGENTS.SYSTEM.md 지침에 의해 Claude가 자동 실행
echo "$(date +%H:%M)|ai-core 설계 문서 작성" > \
~/.config/tmux-notes/.last-question-$(tmux display-message -p '#S').txt
→ 상태바: 💬 ai-core 설계 문서 작성 00:30
3. Multi-LLM 상태 모니터링
하단 pane-border 우측에서 LLM 프로바이더별 상태를 확인합니다:
| 표시 | 의미 |
|---|---|
| ✅ | 활성 (응답 완료) |
| ⏳ | 대기 중 (요청 진행) |
| ❌ | 비활성 또는 에러 |
| ⬛ | 설정에서 비활성 |
4. Handoff 상태 확인
하단 pane-border 좌측에서 handoff 상태를 확인합니다:
[H 0:31, 13msg] ← 31분 전 handoff, 이후 13건 대화
[NO-HO] ← handoff 없음
색상으로 긴급도 표시:
- 0건: 회색 (방금 저장)
- 1~5건: 녹색 (최근)
- 6~15건: 노랑 (갱신 권장)
- 16건+: 빨강 (stale 위험)
5. PI(프롬프트 주입) 상태
2줄 우측에서 현재 시스템 프롬프트 주입 현황을 확인합니다:
GS(3470) GU(53) PS(76) PU PP
| 코드 | 의미 | 소스 |
|---|---|---|
| GS | Global System | /AGENTS.SYSTEM.md |
| GU | Global User | /AGENTS.USER.md |
| PS | Project System | {project}/AGENTS.SYSTEM.md |
| PU | Project User | {project}/AGENTS.USER.md |
숫자는 주입된 토큰 수. 어떤 지침이 적용 중인지 한눈에 파악 가 능합니다.
6. 프로젝트 전환
tmux 세션을 전환하면 상태바가 자동으로 해당 프로젝트 정보를 표시합니다. 메모, 세션 ID, Handoff, LLM 상태 모두 세션별로 분리됩니다.
세션명 규칙
tmux 세션명 = 프로젝트 단위. 폴더 구분자를 변환합니다:
| 프로젝트 경로 | tmux 세션명 |
|---|---|
workspace/quant.how | workspace--quant__how |
workspace/patent.how | workspace--patent__how |
| (루트) | __claude |
변환 규칙: / → --, . → __
설치
make tmux-notes-setup
이 명령은:
- 기존
~/.tmux.conf백업 .ai-core/tmux/tmux-notes/를~/.config/tmux-notes로 심링크- 새
~/.tmux.conf생성
# 적용
tmux source ~/.tmux.conf
의존성
- tmux 3.0+ (status 3줄 + pane-border 지원)
- xclip (클립보드 연동, 선택)
- vim (메모 편집)
스크립트 목록
.ai-core/tmux/tmux-notes/ 폴더의 12개 스크립트:
| 스크립트 | 역할 | 표시 위치 |
|---|---|---|
sysinfo.sh | CPU/RAM/SWAP 사용률 | 1줄 우측 |
session-id.sh | Claude 세션 ID 앞 5자 | 1줄 우측 |
prompt-status.sh | PI 상태 (GS/GU/PS/PU) | 2줄 우측 |
last-question.sh | 마지막 작업 요약 | 3줄 우측 |
handoff-status.sh | Handoff 경과시간 + 메시지 수 | pane-border 좌측 |
multi-llm-status.sh | LLM 프로바이더 상태 | pane-border 우측 |
claude-usage.sh | Claude 토큰 사용량 | (캐시 기반) |
claude-usage-updater.sh | Usage 백그라운드 갱신 | (데몬) |
chorus-usage-updater.sh | Chorus LLM 사용량 갱신 | (데몬) |
session-context.sh | summaries에서 topic 추출 | (선택적) |
discussion-mode.sh | chorus/legacy 모드 표시 | (선택적) |
setup.sh | 설치 스크립트 | - |
tmux 설정 주요 항목
| 설정 | 값 | 이유 |
|---|---|---|
prefix | Ctrl+a | Ctrl+b보다 편리 |
status-interval | 2초 | 빠른 상태 갱신 |
status 3 | 상단 3줄 | 충분한 정보 표시 |
mouse on | 마우스 지원 | 복사/붙여넣기 편의 |
escape-time 0 | ESC 지연 제거 | vim 사용자 필수 |
비활성화된 위험 단축키
실수 방지를 위해 다음이 비활성화되어 있습니다:
d(detach) — 실수로 세션 나가기 방지&(kill-window),x(kill-pane) — 삭제 방지- 패널 분할/전환 키 (
%,",o등) — 단일 패널 운영
설정 수정
# 프로젝트 설정 (공유됨)
vim .ai-core/tmux/tmux-notes/tmux-setup.conf
tmux source ~/.tmux.conf
# 개인 설정 추가 (Git 제외)
cat > ~/.tmux.conf.local << 'EOF'
set -g status-style bg=blue
EOF
파일 경로
.ai-core/tmux/
└── tmux-notes/
├── tmux-setup.conf ← tmux 설정 (source 대상)
├── setup.sh ← 설치 스크립트
├── *.sh ← 상태바 스크립트 (12개)
├── {세션명}.txt ← 세션별 메모 (런타임)
└── .last-question-{세션명}.txt ← 작업 요약 (런타임)