Oh My Tmux! — 완성형 tmux config 배포판, 무엇을 바꾸고 어떻게 커스텀하나

gpakosz/.tmux(Oh My Tmux!)의 2파일 구조와 자동 소싱, vanilla tmux 대비 바꾸는 것(C-a 보조 prefix·vi 복사·SSH-aware 상태바), .tmux.conf.local 커스터마이징 워크플로(tmux_conf_* 노브·#!important·플러그인 자동 관리), 기본 키맵 요점과 stock 키맵을 지키는 tmux_conf_preserve_stock_bindings까지 — 채택 전에 '무엇을 상속하는지' 한 장으로.

게시 2026/07/12 업데이트 2026/07/12

By clang.engineer

조회 18 분읽는 시간

tmux 기본값은 손이 불편한 곳이 많다. 대부분은 기본값을 직접 다듬어 쓰지만, 정반대 노선 — 잘 짜인 .tmux.conf를 통째로 상속하는 것 — 도 있다. 그 카테고리의 사실상 유일한 강자가 Oh My Tmux!(gpakosz/.tmux, “oh-my-zsh의 tmux판” — 잘 만들어진 설정을 프레임워크처럼 통째로 얹는다)다.

이 글은 “채택하냐 마냐”의 판단글이 아니라(그건 요즘 얹는 tmux 플러그인의 Oh My Tmux! (다른 축) 절에서 다뤘다), 채택했다면 실제로 무엇을 상속하고 어떻게 커스텀하는지를 정리한 사용 설명이다. 통째 상속의 약점은 “안에 뭐가 들었는지 모르고 쓰는 것”이라, 그걸 없애는 게 목적이다.

OMT가 이 카테고리를 독주하는 이유

“완성형 tmux config 배포판”은 의외로 얇은 카테고리다. 실측(2026-07) 기준:

배포판	⭐	유지보수	성격
gpakosz/.tmux (OMT)	25.2k	✅ 활발	유일하게 크고 + 살아있음
samoshkin/tmux-config	2.3k	❌ 2024 방치	유명하나 멈춤 (nested-session 토글의 원조)
tony/tmux-config	1.9k	✅	배포판이라기보단 “예제 config”

별 개수만 25k가 아니라 활발히 유지보수되는 게 핵심이다. 그래서 “완성형을 통째로”를 택한다면 사실상 OMT 하나로 좁혀진다.

구조 — 건드리는 파일과 안 건드리는 파일

OMT의 설계는 딱 2파일로 갈린다.

.tmux.conf — 엔진. 직접 편집하지 않는다. upstream이 관리하고, 업데이트로 갱신된다.
.tmux.conf.local — 내 override. 모든 커스터마이징이 여기로 간다.

공식 설치는 리포를 ~/.tmux에 클론하고 심링크를 거는 형태다.

  
cd
git clone https://github.com/gpakosz/.tmux.git
ln -s -f .tmux/.tmux.conf   # ~/.tmux.conf → ~/.tmux/.tmux.conf
cp .tmux/.tmux.conf.local .  # 여기부터 내가 편집

.tmux.conf가 .tmux.conf.local을 어떻게 찾는지가 중요하다 — 하드코딩이 아니라 자기 위치를 자동 감지한다.

  
# .tmux.conf 하단: TMUX_CONF를 아래 순서로 탐색한 뒤
#   "$HOME/.tmux.conf"  "$XDG_CONFIG_HOME/tmux/tmux.conf"  "$HOME/.config/tmux/tmux.conf"
# TMUX_CONF_LOCAL = "$TMUX_CONF.local" 로 잡고 source 한다

덕분에 ~/.tmux.conf(홈)든 ~/.config/tmux/tmux.conf(XDG)든, 같은 자리에 .local만 두면 알아서 물린다. 심링크 레이아웃을 강제하지 않으므로, dotfiles 매니저로 엔진을 ~/.tmux.conf에 바로 떨궈도 동작한다.

vanilla tmux 대비 무엇을 바꾸나

OMT가 기본으로 켜 주는 것들(=내가 안 적어도 되는 것) 중 체감 큰 것만.

항목	vanilla	OMT 기본
보조 prefix	`C-b`만	`C-b` + `C-a` (GNU Screen 호환, `prefix2`)
인덱스	0부터	`base-index 1`·`pane-base-index 1`·`renumber-windows on`
복사 모드	emacs 키	vi 키 (하드코딩)
트루컬러	수동	`tmux_conf_24b_colour=auto` (COLORTERM 감지)
상태바	밋밋	powerline 테마 — prefix·mouse·synchronize 토글 표시등, 배터리·시계, 그리고 SSH/Mosh 접속 시 원격 호스트·유저 자동 표시(로컬일 땐 숨김)
마우스	off	off이되 `prefix + m`으로 토글(상태바에 on/off 표시)
분할	`"` 세로 · `%` 가로	`-` 세로 · `_` 가로

특히 상태바의 SSH/Mosh 인식이 OMT의 시그니처다 — #{hostname_ssh}·#{username_ssh} 변수가 원격 접속일 때만 값을 채워, “지금 이 pane이 로컬인지 원격 서버인지”가 한눈에 구분된다. (흔히 OMT의 기능으로 오해되는 중첩 세션 dimming은 사실 samoshkin의 F12 토글이다. OMT는 dimming이 아니라 원격 정보 표시 쪽이다.)

상태바 인디케이터 범례

status-right에 뜨는 한 글자 표시등들. 각 아이콘은 현재 상태를 켜졌을 때만 보여준다(꺼지면 사라짐). tmux_conf_theme_* 노브로 글리프를 바꿀 수 있다.

글리프	의미	조건
`⌨` (U+2328)	prefix 대기 중	`prefix` 키를 누른 직후
`↗` (U+2197)	마우스 모드 ON — 마우스 커서 형상화	`prefix + m`으로 토글
`↑` / `↓` (U+2191/2193)	배터리 충전 / 방전 — 전기가 배터리로 들어오면 위, 소모되면 아래	어댑터 연결 여부
`⚏` (U+268F)	pane 동기화 ON — 한 입력이 모든 pane에 복제	`:setw synchronize-panes` (OMT는 키 미지정)
`⚇` (U+2687)	세션 pairing — 여러 클라이언트가 같은 세션에 attach	다중 attach 시
`!`	root 셸 — 위험 경고(bold+blink)	루트로 tmux 실행 시

배터리 ↑/↓가 특히 직관적이다 — 스크롤·스크린샷 없이 “지금 충전 중인지”가 방향 하나로 읽힌다.

커스터마이징 워크플로 — 3가지 레버

모든 편집은 .tmux.conf.local에서, 세 가지 방식으로 한다.

1. `tmux_conf_*` 노브 (준비된 스위치)

자주 바꾸는 건 이미 변수로 노출돼 있다. 주석 처리된 값을 켜거나 바꾸면 된다.

  
tmux_conf_new_window_retain_current_path=true   # 새 창을 현재 경로에서
tmux_conf_new_pane_retain_current_path=true     # 새 pane도 (기본 true)
tmux_conf_copy_to_os_clipboard=true             # 복사 → 시스템 클립보드
# 테마 색: tmux_conf_theme_colour_1 … _17, tmux_conf_theme_status_left/right …

2. `-- user customizations` 자유 영역 (raw 명령)

노브에 없는 건 이 섹션에 tmux 명령을 날것으로 적는다 — 커스텀 bind, set, set-hook 등.

  
# -- user customizations -------------------------------------------------------
set -g mouse on          # 시작부터 마우스 on
set -g history-limit 10000
bind s choose-tree -Zs -O name   # 세션 트리를 이름순으로

여기서 함정 하나: OMT는 리로드 때 자기 바인딩을 다시 적용한다. OMT가 특정 바인딩·설정을 건드리지 못하게 막으려면 줄 끝에 #!important를 붙인다.

  
bind c new-window -c '#{pane_current_path}' #!important

3. `set -g @plugin` (플러그인)

TPM(Tmux Plugin Manager) 문법 그대로 선언하되, tpm 자체는 선언하지 않는다 — OMT가 tpm 설치·갱신·플러그인 설치까지 대신 한다(~/.tmux/plugins에 설치).

  
# /!\ do not add: set -g @plugin 'tmux-plugins/tpm'
# /!\ do not add: run '~/.tmux/plugins/tpm/tpm'
set -g @plugin 'christoomey/vim-tmux-navigator'
set -g @plugin 'tmux-plugins/tmux-resurrect'

tmux_conf_update_plugins_on_launch=true(기본)이라, 첫 실행 시 플러그인이 자동으로 깔린다 — vanilla + tpm에서 익숙한 prefix + I를 손으로 누를 필요가 없다.

테마는 OMT 기본을 그대로 쓰는 걸 권한다. “보기 좋게”가 목적이라면 OMT의 powerline이 이미 정석이고, 색만 바꾸고 싶으면 tmux_conf_theme_colour_* 노브로 충분하다. 굳이 별도 테마 플러그인(catppuccin 등)을 얹으면 OMT 상태바와 충돌한다.

기본 키맵 요점

vanilla와 달라 헷갈리기 쉬운 것 위주로. (전체는 리포 README 또는 .tmux.conf의 bind 줄 참고.)

키	stock(vanilla)	OMT 동작	왜 (편의)
`prefix + e`	미배정	`.tmux.conf.local`을 `$EDITOR`로 열고 저장 시 리로드	설정 편집→소싱을 한 키로 (파일 탐색·수동 리로드 불필요)
`prefix + r`	`refresh-client`	설정 리로드	잦은 리로드를 한 키로
`prefix + m`	`select-pane -m` (pane 마크)	마우스 on/off 토글	네이티브 선택 ↔ 휠·클릭·리사이즈를 순간 전환 (아래 tip)
`prefix + -` / `prefix + _`	`-`=`delete-buffer` · `_`=미배정	세로 / 가로 분할	방향과 무관한 stock `"`/`%` 대신 인접한 `-`/`_` 한 쌍 → 기억 부담↓
`prefix + h/j/k/l`	`l`=마지막 창 · `hjk`=미배정	pane 이동 (vi 방향)	vim 손버릇 그대로 (stock은 화살표·`o` 순환)
`prefix + H/J/K/L`	`L`=직전 클라이언트 · `HJK`=미배정	pane 크기 조절 (반복 가능)	소문자=이동 / 대문자=리사이즈 짝으로 묶음
`prefix + < / >`	window / pane 메뉴 (`display-menu`)	pane 순서 swap	화살표가 좌/우 이동 방향을 암시
`prefix + C-h / C-l`	미배정	이전 / 다음 창	창 이동도 방향성 있게 (stock `n`/`p` 대신)
`prefix + Tab`	미배정	마지막 창	에디터 탭 전환 관습(직전 것으로 토글)
`prefix + Enter`	미배정	복사 모드 진입 (`v` 선택, `y` 복사, `C-v` 사각 선택)	vim visual 흐름 그대로

실전 함정 — C-l 충돌. OMT는 루트 테이블에 bind -n C-l(화면 클리어 + clear-history)을 건다. vim-tmux-navigator도 pane 이동에 C-l을 쓰므로, 둘을 같이 쓰면 로드 순서에 따라 한쪽이 먹힌다. nvim↔tmux를 C-hjkl로 넘나든다면 이 지점을 반드시 확인하라.

왜 마우스는 “설정”이 아니라 “토글”인가. tmux 마우스를 ON으로 켜면 tmux가 마우스 이벤트를 가로채, 터미널 자신의 드래그 선택 → OS 클립보드 복사와 pane를 가로지르는 선택(선택이 한 pane 안으로 클리핑된다)이 죽는다. 반대로 ON이면 휠 스크롤백·클릭 pane 전환·드래그 리사이즈가 편하다. 둘이 배타적이라 고정값으로 둘 수 없고 순간 뒤집는 스위치가 되는 것 — 평소 ON으로 쓰다 로그·경로를 긁어 복사할 때만 prefix + m으로 껐다 켠다(상태바 ↗ 인디케이터로 현재 모드 확인). 터미널이 Shift(iTerm2는 Option) 드래그로 tmux 마우스를 우회해주면 덜 필요하지만, 그 modifier는 터미널마다 달라 이식성이 없다 — OMT는 어느 터미널에서든 되는 범용 탈출구로 토글을 기본 제공한다.

stock 키맵을 지키려면 — `preserve_stock_bindings`

위 키맵 표의 이면엔 함정이 하나 있다 — OMT의 키 상당수가 vanilla tmux의 stock 바인딩을 덮어쓴다. 다른 서버·머신에서 익힌 손버릇이 그만큼 깨진다.

키	vanilla(stock)	OMT	왜 (편의)
`n`	다음 창	언바운드 (창 이동은 `C-l`)	창 이동을 방향성 있는 `C-h`/`C-l` 한 쌍으로 통일
`p`	이전 창	paste-buffer	`p`=paste 니모닉 (vim·셸과 동일)
`m`	pane 마크(`select-pane -m`)	마우스 토글	마우스 on/off 순간 전환 (위 tip)
`l`	마지막 창	pane 오른쪽 이동	vim `hjkl` 패널 이동

("/% 분할, c 새 창, s/w 트리 등 나머지는 그대로다 — OMT는 -/_를 추가하지 "/%를 지우지 않는다.)

prefix + n을 눌렀는데 아무 일도 안 일어나거나 prefix + p가 난데없이 버퍼를 붙여넣는다면 이 때문이다. stock 키맵을 그대로 쓰고 싶다면 .tmux.conf.local 최상단의 노브 하나면 된다.

  
tmux_conf_preserve_stock_bindings=true

true면 OMT는 stock 바인딩을 보존하고 충돌하지 않는 확장만 얹는다 — 별도 probe 서버를 띄워 vanilla 바인딩을 떠온 뒤 병합하는 방식이다. 테마·상태바·플러그인 자동 관리 같은 OMT의 실제 가치는 그대로 챙기면서 키맵만 vanilla로 되돌린다.

실익 판단. OMT 키맵의 이득(hjkl pane 이동·r/e 편의)은 한계적인 반면, stock 키맵의 이득은 이식성 — 모든 서버·머신·튜토리얼·문서에서 동일하다. SSH로 남의 서버를 자주 탄다면 stock 손버릇이 훨씬 값지다. “tmux 기본을 그대로 쓴다”가 원칙이면 이 노브가 정답이고, 덤으로 앞의 C-l 충돌도 사라진다(stock은 prefix + C-l을 창 이동에 쓰지 않으니까).

채택할 것인가

OMT는 훌륭하지만, 이미 손수 curate한 .tmux.conf가 있다면 통째 상속은 오히려 후퇴일 수 있다 — 안 쓰는 기능이 딸려오고, 내 커스텀을 OMT의 override 방식에 다시 맞춰야 한다. 이 판단은 beyond-essentials 글의 Oh My Tmux! (다른 축) 절에서 깊게 다뤘다.

그럼에도 채택하기로 했다면, 규율 있게 하는 게 핵심이다 — 엔진(.tmux.conf)은 upstream을 특정 커밋에 고정해 추적하고, 커스텀은 .tmux.conf.local 하나로 격리한다. dotfiles를 chezmoi로 관리한다면 .chezmoiexternal로 이걸 그대로 구현할 수 있다(dotfiles 로드맵의 chezmoi 갈래 참고).

정리하면 OMT는 “잘 만든 남의 .tmux.conf를 상속하되, 내 손은 .tmux.conf.local 한 파일에만 댄다”는 계약이다. 그 계약이 무엇을 바꾸는지(위 표)와 어디를 만지는지(3 레버)를 알고 들어가면, “완성형 배포판 상속”의 최대 약점 — 블랙박스로 쓰는 것 — 이 사라진다. 처음부터 직접 쌓는 길은 tmux 로드맵의 1~2단계를 참고하면 된다.

tmux, 스크립트·플러그인