설정 파일
pytmux.conf 로 동작을 바꾸거나, 통합 설정 팝업 :settings 로 카테고리별로
조정합니다. :settings 에서 바꾼 파일 설정은 설정 파일에 자동으로 되쓰기 되고
(주석·바인딩 보존), 서버 옵션(window-size·vt-parser·
exit-empty 등)은 서버가 opts.json 에 영속합니다 — 어느 쪽이든 다시 켤 때 유지됩니다.
예외가 있습니다: automatic-rename·monitor-activity·
monitor-bell·synchronize-panes·pane-border-status 는
지금 보고 있는 탭에만 걸리는 상태라 opts.json 에 남지 않습니다.
설정 파일 위치와 형식
설정 파일은 ~/.config/pytmux/config, ~/.pytmux.conf, 또는 환경변수
PYTMUX_CONFIG 로 지정한 경로에서 읽습니다(pytmux.conf.example 참고).
여러 곳에 있으면 PYTMUX_CONFIG → $PYTMUX_HOME/config →
~/.config/pytmux/config → ~/.pytmux.conf 순으로 먼저 있는 하나만 씁니다.
각 줄은 set <이름> <값> 형식입니다. 실행 중에 source-file 로 다시 읽으면
prefix·키 바인딩·alias·hook·mouse·mode-keys·
상태줄 색(status-bg/status-fg)과 status-left/status-right·
tab-bar·default-path·claude-command 만 새로 적용되고,
나머지 줄은 클라이언트를 다시 시작해야 반영됩니다.
현재 값은 show-options 로 확인합니다.
실행 중에 바꿀 때는 명령 프롬프트에서 set 을 빼고
옵션 이름을 그대로 칩니다(예: :strip-box-drawing off, :lang en) —
:set … 이 먹는 것은 mouse·prefix·mode-keys 처럼
일부뿐이라, 가장 확실한 방법은 설정 팝업(:settings)에서
고르는 것입니다.
set 줄이 읽는 옵션은 다음뿐입니다 —
prefix · mouse · mouse-drag-copy · mouse-drag-threshold ·
copy-unwrap · set-clipboard · status-bg / status-fg /
status-left / status-right / status-position / status-interval ·
mode-keys · remote-title · tab-bar · set-titles ·
set-titles-string · default-path · claude-command ·
ambiguous-width · lang(language) · inactive-dim ·
inactive-dim-ratio · strip-box-drawing · alt-scroll ·
net-rtt-threshold.
아래 표에서 (런타임) 으로 표시한 옵션과 «동작 · 고급» 표의 옵션은 파일에 적어도 읽지 않으니,
실행 중에 명령 프롬프트나 :settings 로 바꿉니다.
자주 쓰는 옵션
| 설정 | 값 (기본) | 설명 |
|---|---|---|
prefix | C-a 등 (C-b) | prefix 키 |
mouse | on|off (on) | 마우스 on/off |
mouse-drag-copy | on|off|shift (on) | 좌드래그로 선택→클립보드 자동 복사(off=앱에 전달 / shift=평드래그를 앱에 주고 복사는 Shift+드래그로 — 제 선택 기능을 가진 fullscreen 앱을 마우스로 쓸 때) |
mouse-drag-threshold | 1~20 (3) | 드래그로 인정할 최소 이동 칸수 — 짧은 클릭이 드래그로 오인돼 클립보드가 바뀌는 것을 막습니다(1=예전 감도) |
copy-unwrap | on|off (on) | 마우스로 긁어 복사할 때 앱이 접은 줄바꿈과 그에 딸린 들여쓰기를 펴서, 여러 줄로 보이던 명령을 바로 붙여넣을 수 있게 합니다 |
set-clipboard | on|off (on) | 패널 안 앱이 OSC 52 로 보낸 복사를 이 클라이언트의 OS 클립보드에 반영 |
alt-scroll | on|off (on) | on=pytmux 가 휠 스크롤백 처리 / off=터미널 기본 |
net-rtt-threshold | 초 (0.4) | 클라↔서버 왕복 지연이 이 값을 넘으면 패널 외곽선을 빨갛게 합니다(0.05~10 · 재시작·재접속). 느린 원격 링크에서 늘 빨갛다면 올립니다 |
mode-keys | vi|emacs (vi) | 복사/스크롤 모드 키 스타일 |
ambiguous-width | auto|narrow|wide (auto) | CJK 모호폭 셀 크기(단말 자동 감지) |
tab-bar | always|auto (always) | 상단 탭바: 항상 / 2개 이상일 때만 |
default-path | current|home|<경로> (current) | 새 탭/패널 시작 디렉토리 |
claude-command | 명령 (claude) | ESC 모드 c·new-claude-tab 이 새 탭에서 실행할 Claude Code 명령(경로·플래그 포함) |
strip-box-drawing | on|off (on) | 붙여넣기 시 패널 테두리(박스드로잉) 제거 |
inactive-dim | on|off (on) | 비활성 패널 흐리게 |
inactive-dim-ratio | 0.0–0.8 (0.18) | 흐림 강도 |
language | ko|en (LANG) | UI 언어 |
상태줄 · 화면
| 설정 | 값 | 설명 |
|---|---|---|
status (런타임) | on|off|0–5 | 상태줄 줄 수 |
status-position | bottom|top | 상태줄 위치 |
status-left / status-right | 포맷 문자열 | #S·#h·#{pane_title}·strftime 등 |
status-interval | 1–60 | 상태줄 갱신 주기(초) |
status-format <줄> <포맷> (런타임) | 1~ + 포맷 문자열 | status 를 2줄 이상으로 켰을 때 보조 줄의 내용. 줄 번호는 1부터이며 포맷 기호는 status-left 와 같습니다 |
status-bg / status-fg | 색 | 상태줄 배경/전경색 |
set-titles / set-titles-string | on|off / 포맷 | 터미널 창 제목 설정 |
remote-title | full|host|name (full) | 원격 탭 이름을 보여 줄 형식 — full=⇄호스트:이름 · host=호스트:이름(아이콘만 뺌) · name=이름. 그릴 때만 접고 이름 자체는 바꾸지 않습니다 |
single-border (런타임) | on|off|toggle | 패널이 하나일 때도 테두리 |
pane-border-status (런타임) | on|top|off | 패널 테두리 제목줄(지금 탭에만 적용) |
동작 · 고급
이 표의 옵션은 설정 파일이 읽지 않습니다 — 명령 프롬프트(예: :exit-empty off)나
:settings 로 바꿉니다. 그중 coalesce-repaints·nest-auto-attach·
exit-empty·win-mouse-motion·vt-parser·window-size
는 서버가 opts.json 에 영속하고, 앞의 셋(automatic-rename·monitor-*·
synchronize-panes)은 지금 탭에만 걸립니다.
| 설정 | 값 | 설명 |
|---|---|---|
automatic-rename | on|off | 실행 앱으로 탭 자동 명명(지금 탭) |
monitor-activity / monitor-bell | on|off (off / on) | 비활성 탭 활동/벨 감지(지금 탭) |
synchronize-panes | on|off | 패널 입력 동기화(지금 탭) |
coalesce-repaints | on|off|toggle | ssh 반응성: 전체 리페인트 병합 |
nest-auto-attach | on|off|toggle | 중첩 pytmux 시 자동 remote-attach |
exit-empty | on|off|toggle (on) | 세션이 0개가 되면 서버 종료. off=빈 채로 상주(원격 서버용, 11장) |
win-mouse-motion | on|off|toggle (on) | Windows 마우스 이동 전달 |
mouse-debug | on|off (off) | 진단용 — 클라이언트가 받은 마우스·휠 이벤트와 화살표/페이지 키를 <소켓>.mouse.log 에 기록합니다. 원격에서 휠이 안 먹는 것처럼 환경에 따라 달라지는 입력 문제를 제보할 때 켭니다(글자·단축키는 기록하지 않습니다) |
vt-parser | native | VT 파서 백엔드. 현재는 자체 native 파서 단일이라 사실상 고를 것이 없습니다 — 옛 pyte 백엔드는 은퇴했고, 그 값을 넣어도 native 로 수렴합니다(옛 설정 파일 호환용으로만 받습니다) |
window-size | smallest|latest|largest (latest) | 여러 클라이언트가 한 세션을 볼 때 공유 격자 크기 기준(11장) |
pytmux.conf 예시
아래 줄을 그대로 복사해 붙여넣으면 됩니다. 키 바인딩도 함께 둘 수 있습니다.
| 지시어 | 뜻 |
|---|---|
set <옵션> <값> | 위 표의 설정 중 설정 파일이 읽는 것(맨 위 목록)만 먹습니다. 런타임 :set 과 같은 이름입니다. |
bind <키> <명령> | prefix 뒤 키. bind -n 은 prefix 없이 바로 듣습니다(7장).
내 바인딩은 내장 prefix 키보다 먼저 보므로, 같은 키(예: r 화면 다시 그림)에 묶으면 그 내장 키를 가립니다. |
alias <이름> <명령> | 명령 프롬프트에서 쓸 짧은 이름을 만듭니다 — 인자까지 통째로 담을 수 있어 자주 쓰는 조합을 한 단어로 줄입니다. |
hook <이벤트> <명령> | 정해진 순간에 자동 실행합니다(client-attached · after-new-window · alert-bell · claude-limit).
여기 적은 줄은 따옴표를 그대로 지켜 run-shell 에 인자 붙은 셸 명령을 넘길 수 있습니다. 런타임에서는 set-hook, 지금 걸린 목록은 show-hooks — 자세한 것은 7장. |
통합 설정 팝업 · 언어
:settings(별칭 config·preferences)는 옵션을
표시 · 입력 · 동작 · 상태줄 · 고급 · 키 카테고리(+ 플러그인의 Claude 카테고리)로
묶어 보여 줍니다. 여기서 바꾼 값은 파일 설정이면 설정 파일에, 서버 옵션이면 서버 opts.json 에
각각 자동 반영됩니다(지금 탭에만 걸리는 automatic-rename·monitor-*·
synchronize-panes·pane-border-status 는 opts.json 에 남지 않습니다).
UI 언어는 lang ko|en
(별칭 language)으로 즉시 바꾸며, 선택은 클라이언트에 저장됩니다.
:settings) — 카테고리별 조정. 숫자 항목(예: 드래그 인정 최소 이동)은
←→ 로 값을 올리고 내립니다.