본문으로 건너뛰기

tmux 터미널 환경

tmux를 활용한 효율적인 터미널 환경과 AI 세션 연동 가이드입니다.

📝 초안 (Draft)

이 문서는 검토 중입니다. 내용이 변경될 수 있습니다.

개요​

tmux는 터미널 멀티플렉서로, SSH 연결이 끊어져도 세션을 유지하고 여러 터미널을 관리할 수 있습니다. Foundation에서는 Claude Code와 연동하여 세션별 컨텍스트를 관리합니다.

기본 사용법​

설치​

# Ubuntu/Debian
sudo apt install tmux

# macOS
brew install tmux

핵심 명령어​

# 새 세션 생성
tmux new -s session-name

# 세션 목록
tmux ls

# 세션 연결
tmux attach -t session-name

# 세션 분리 (세션 유지한 채 나가기)
# Ctrl+b, d

# 세션 종료
exit

기본 단축키​

단축키동작
Ctrl+b, d세션 분리 (detach)
Ctrl+b, c새 윈도우
Ctrl+b, n다음 윈도우
Ctrl+b, p이전 윈도우
Ctrl+b, %수직 분할
Ctrl+b, "수평 분할
Ctrl+b, 방향키패인 이동

Claude Code 연동​

세션별 컨텍스트​

Foundation은 tmux 세션별로 다른 Claude Code 컨텍스트를 자동 로드합니다.

.claude/config/append-system-prompt/tmux/
├── project-a.md     # project-a 세션용 프롬프트
├── project-b.md     # project-b 세션용 프롬프트
└── _default.md      # 기본 프롬프트 (비활성)

세션별 프롬프트 설정​

# 1. tmux 세션 생성
tmux new -s myproject

# 2. 해당 세션용 프롬프트 파일 생성
echo "이 세션은 myproject 작업 중입니다." > \
  .claude/config/append-system-prompt/tmux/myproject.md

# 3. Claude Code 실행 시 자동으로 해당 프롬프트 로드
claude

활성화 확인​

Claude Code 실행 시 outputStyle에 [APPEND SP] 표시로 확인:

| 💉 Inject | 🖥️ tmux:myproject |

권장 설정​

.tmux.conf​

# ~/.tmux.conf

# 마우스 지원
set -g mouse on

# 256색 지원
set -g default-terminal "screen-256color"

# 히스토리 증가
set -g history-limit 50000

# 인덱스 1부터 시작
set -g base-index 1
setw -g pane-base-index 1

# 상태바 설정
set -g status-position top
set -g status-bg colour235
set -g status-fg colour136

# 현재 윈도우 강조
setw -g window-status-current-style fg=colour166,bold

적용​

# 설정 다시 로드
tmux source-file ~/.tmux.conf

프로젝트별 세션 관리​

세션 네이밍 규칙​

# 프로젝트별 세션
tmux new -s quant-how
tmux new -s docs-site
tmux new -s admin-panel

# 작업별 세션
tmux new -s feature-auth
tmux new -s bugfix-login

세션 스크립트​

#!/bin/bash
# start-project.sh

PROJECT=$1
cd ~/projects/$PROJECT

tmux new-session -d -s $PROJECT
tmux send-keys "cd ~/projects/$PROJECT" C-m
tmux send-keys "make up NAME=$PROJECT" C-m
tmux split-window -h
tmux send-keys "claude" C-m
tmux attach -t $PROJECT

원격 개발 패턴​

SSH + tmux​

# 1. 원격 서버 접속
ssh dev-server

# 2. tmux 세션 연결 (또는 생성)
tmux attach -t work || tmux new -s work

# 3. 작업 후 분리 (연결 유지)
# Ctrl+b, d

# 4. 나중에 다시 연결
ssh dev-server
tmux attach -t work

장점​

  • SSH 연결이 끊어져도 작업 유지
  • 여러 터미널을 하나의 SSH 연결로 관리
  • Claude Code 세션도 유지됨

유용한 플러그인​

tmux Plugin Manager (TPM)​

# 설치
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# .tmux.conf에 추가
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'

run '~/.tmux/plugins/tpm/tpm'

tmux-resurrect​

세션 저장/복원:

# 저장: Ctrl+b, Ctrl+s
# 복원: Ctrl+b, Ctrl+r

관련 문서​