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 ← 작업 요약 (런타임)