User Manual
이 문서는 pytmux 를 처음 쓰는 분부터 일상적으로 쓰는 분까지 참고할 수 있도록, 설치 → 첫 실행 → 패널/탭 다루기 → 마우스·메뉴·명령 → Claude Code 연동 → 설정·운영까지 차근차근 설명합니다.
pytmux 의 시계·달력·디렉토리 트리(ncd)·IME 배지·Claude 통합·프롬프트 히스토리·사용 한도 등은 모두 플러그인입니다(플러그인 디렉토리를 지우면 그 기능이 조용히 사라집니다). 플러그인을 직접 만들려면 Plugin-Authoring-Guide 를 참고하세요.
- pytmux 가 무엇인가요
- 설치
- 첫 실행 — 화면 한 바퀴
- 핵심 개념: 탭 → 윈도우 → 패널, 그리고 영속성
- 패널 다루기 (분할·이동·크기·줌·교환)
- 탭 다루기 (생성·전환·이름·재정렬)
- 스크롤백(복사 모드)
- 마우스로 거의 다 하기
- 메뉴와 명령 프롬프트
- 붙여넣기 · 클립보드 · 이미지
- Claude Code 연동
- 상태줄·시계·달력·정보 팝업
- detach / attach 와 셸 영속성
- 네트워크 응답성과 재접속
- 작업 보존 서버 재시작
- 설정 파일
- 명령 레퍼런스
- 키 바인딩 레퍼런스
- 외부에서 서버 제어 (CLI)
- 문제 해결 FAQ
pytmux 는 Python + Textual 로 만든 tmux 유사 터미널 멀티플렉서입니다. 하나의 터미널 창 안에서 여러 셸을 패널로 나눠 쓰고, 앱이나 터미널 창을 닫아도 셸 세션이 계속 살아 있게 해 줍니다.
tmux 와 다른 점은 마우스와 메뉴를 1급으로 지원한다는 것입니다. 단축키를 다 외우지
않아도, 우클릭 메뉴(prefix Enter)와 명령 프롬프트(prefix :)로 거의 모든 동작을 할 수
있습니다. 경계선을 드래그해 패널 크기를 바꾸고, 휠을 굴려 스크롤백을 봅니다.
구조는 클라이언트 ↔ 서버입니다. 셸 PTY 는 백그라운드 데몬(서버)이 보유하고, 화면을 그리는 앱(클라이언트)은 거기에 붙었다 떨어졌다 합니다. 그래서 앱을 닫아도 셸은 죽지 않습니다.
pip install -r requirements.txt
# 또는 직접: pip install textual pyte wcwidth- macOS / Linux (POSIX PTY) 에서 동작합니다. Python 3.11 이상을 권장합니다.
-
Windows 네이티브(WSL/Cygwin 불필요)는 ConPTY 백엔드로 지원합니다.
추가로
pip install pywinpty가 필요합니다(requirements.txt에win32조건부 포함).
어디서든 python3 pytmux.py 대신 pytmux 로 실행하려면 래퍼를 설치합니다.
./install.sh # 기본 위치(~/.local/bin)에 'pytmux' 래퍼 설치
./install.sh /usr/local/bin # 다른 디렉터리에 설치
BIN=pt ./install.sh # 다른 이름(pt)으로 설치
./uninstall.sh # 제거(설치 시 쓴 DIR/BIN 인자를 동일하게)Windows(PowerShell) 에서는 install.ps1 / uninstall.ps1 을 사용합니다.
원격 로그인하면 곧바로 pytmux 세션으로 들어가도록 셸 설정(~/.zshrc 등)에 아래를
추가합니다. tmux 의 tmux new-session -A -s main 자동 실행을 대체하는 용도입니다.
# 인터랙티브 SSH/mosh 로그인일 때만 pytmux 세션에 attach.
if command -v pytmux >/dev/null && [[ -o interactive ]] && [[ -t 1 ]] \
&& [[ -z "$PYTMUX" ]] && [[ -n "$SSH_CONNECTION$SSH_TTY" ]]; then
pytmux
fi중첩 방지 가드는 pytmux 가 패널 셸에 심는 $PYTMUX 환경변수를 검사합니다(비인터랙티브
도구 셸은 가로채지 않으므로 자동화 명령을 막지 않습니다).
python3 pytmux.py # 서버가 없으면 자동 기동 후 attach, 있으면 attach
# 래퍼를 설치했다면 어디서든: pytmux처음 실행하면 평소 쓰던 셸이 거의 전체 화면으로 뜹니다. 위에는 탭바, 아래에는 상태줄이 있습니다.
화면 요소는 다음과 같습니다.
-
상단 탭바 — 탭 목록 + 마지막 탭 오른쪽의
[+](새 탭 추가). 탭이 하나여도 기본 표시됩니다(set tab-bar auto면 2개 이상일 때만 표시). 활성 탭은 아래 콘텐츠와 연결된 노트북 탭 모양(활성색 배경 블록)으로 이어집니다. -
[x]— 콘텐츠 영역 오른쪽 위 모서리입니다. 현재 탭 닫기(확인 팝업). - 콘텐츠 영역 — 현재 탭의 윈도우(패널 집합)입니다. 패널이 하나면 테두리는 옵션입니다.
-
하단 상태줄 —
[세션]· 탭 목록(현재 탭*표시) · 줌 상태 · 오른쪽에 시계/날짜.
조작은 세 가지 방식 모두 가능합니다.
-
키보드 —
Ctrl-b(prefix)를 누른 뒤 명령 키. - 마우스 — 클릭(포커스), 드래그(크기·swap), 휠(스크롤백), 우클릭(메뉴).
-
메뉴/명령 —
prefix Enter(메뉴),prefix :(명령 프롬프트).
pytmux 는 단일 세션 모델입니다. tmux 처럼 여러 세션을 만들지 않습니다. 대신 다음과 같은 계층을 가집니다.
flowchart TD
S["세션 (단 하나)"]
S --> T1["탭 1"]
S --> T2["탭 2"]
S --> T3["탭 3"]
T1 --> W1["윈도우"]
T2 --> W2["윈도우"]
T3 --> W3["윈도우"]
W1 --> PA["패널 A"]
W1 --> PB["패널 B"]
W2 --> PC["패널 C"]
W3 --> PD["패널 D"]
W3 --> PE["패널 E"]
W3 --> PF["패널 F"]
- 탭(최상위) — 새 탭을 만들면 새 터미널 윈도우(단일 패널)가 열립니다. 1번부터 번호.
- 윈도우 — 각 탭에 종속된 단일 윈도우입니다. 이를 패널 집합으로 분할합니다.
- 패널 — 실제 셸 PTY 하나입니다. 좌우/상하로 쪼개 여러 개를 동시에 봅니다.
tmux 용어로는 pytmux 의 "탭" = tmux 의 "window", pytmux 의 "패널" = tmux 의 "pane" 입니다. 그래서 탭 명령은
new-tab과new-window두 이름을 모두 받습니다.
셸 영속성: 셸 PTY 를 서버(백그라운드 데몬)가 보유하므로, 앱을 닫거나(prefix d
detach), 상위 터미널 창을 닫아도 셸은 계속 돌아갑니다. 다시 pytmux 하면 이어서 붙습니다.
-
prefix %— 좌우 분할(세로선으로 나눔) -
prefix "— 상하 분할(가로선으로 나눔)
패널이 둘 이상이면 각 패널이 테두리 박스로 감싸지고, 현재 활성(포커스) 패널의 테두리
전체가 파란색, 비활성은 회색입니다. 인접 패널 경계는 ┬ ┴ ├ ┤ 로 연결됩니다.
-
prefix o— 다음 패널로 순환 -
prefix ←↑↓→— 방향으로 패널 이동 - 마우스 클릭 — 해당 패널로 즉시 포커스
-
ESC모드에서←↑↓→— prefix 없이 패널 이동(명령 모드)
-
prefix HJKL— 패널 경계를 왼/아래/위/오른쪽으로 이동 - 경계선 드래그 — 마우스로 패널 사이 경계를 끌어 크기 변경
한글 IME 가 켜진 상태에서
prefix H/J/K/L(시프트 구분이 안 되는 두벌식)은 동작이 애매할 수 있습니다. 이때는 마우스 드래그나 영문 입력 상태를 사용하세요.
-
prefix z또는 명령resize-pane -Z
줌하면 해당 패널이 콘텐츠 영역을 가득 채우고, 상태줄에 Z 표시가 뜹니다. 다시 누르면
원래 레이아웃으로 복귀합니다.
- Shift + 왼쪽 버튼 드래그 — 두 패널 위치를 맞바꿉니다(드래그 중 원본은 흐리게, 대상은 강조).
- 명령
swap-pane -t <n>— 현재 패널과 n 번 패널 교환 - 명령
rotate-window— 윈도우 안 패널들을 회전
-
prefix x— 현재 패널 삭제(kill-pane? (y/N)확인 뒤y).
-
명령으로 삭제 —
ESC를 눌러 명령 모드로 들어간 뒤:로 명령 프롬프트를 열고kill-pane을 입력해 Enter 합니다(prefix :로 바로 열어도 됩니다).
-
layout-save <name>— 현재 탭 레이아웃을 이름으로 저장 -
layout-load <name>— 저장 레이아웃을 현재 탭에 덮어쓰기(이름 생략 시 선택기) -
layout-load-new <name>— 저장 레이아웃을 새 탭으로 열기 -
next-layout— 프리셋 레이아웃 순환
-
prefix c— 새 탭(새 윈도우, 단일 패널) -
prefix n/prefix p— 다음/이전 탭 -
prefix l— 직전 탭(마지막으로 보던 탭) -
prefix 1~prefix 9— 번호로 탭 선택(1번부터) - 탭바 탭 클릭 — 해당 탭으로 전환
-
[+]클릭 — 새 탭
Claude Code 가 도는 탭에는 상태 아이콘(
○/◐/⊘)이 함께 표시됩니다(§11.1).
-
prefix ,— 탭 이름변경(입력창) - 명령
rename-tab <name>(=rename-window)
POSIX 에서는 포그라운드 프로세스(fg)를 기반으로 탭 이름이 자동으로 따라갑니다(ssh
감지 등).
- 탭바에서 탭 드래그 — 마우스로 순서 변경
-
ESC모드로 탭바를 하이라이트한 뒤 Shift+←→ 로 이동, Enter 로 확정 - 명령
move-tab-left/move-tab-right/move-tab-first/move-tab-last
ESC 를 눌러 명령 모드로 들어간 뒤 위 방향키로 탭바에 포커스를 올리면 다음 키를
쓸 수 있습니다.
-
←→— 탭 선택 -
Enter— 전환 -
+/a— 새 탭 추가 -
x/d— 탭 닫기 -
Shift+←→— 탭 이동(재정렬),Enter로 확정
esc e— 패널에 ESC 보내기:Shift+ESC로 앱에 ESC 를 못 보내는 터미널(일부 Windows Terminal 설정 등 Shift 수정자가 누락되는 환경)에서,ESC를 눌러 모드에 들어간 뒤e를 누르면 활성 패널(앱)에 ESC(\x1b)가 전달되고 모드를 빠집니다. (단독ESC두 번은 모드만 진입/종료할 뿐 앱에 ESC 를 보내지 않습니다 — 앱 ESC 통로는Shift+ESC·esc e·send-escape.)
-
prefix &— 현재 탭 삭제(확인) - 콘텐츠 오른쪽 위
[x]클릭 — 현재 탭 닫기(확인) - 명령
kill-tab(=kill-window)
탭을 닫을 때는 중앙 확인 박스가 뜹니다. 탭이 둘 이상이면 그 탭만 닫는 일반 확인입니다 (고정 탭이면 "고정 탭 닫기" 문구로 한 단계 더 확인 — §6.6).
마지막 탭을 닫을 때는 의미가 다릅니다 — 그 탭을 닫으면 pytmux 자체가 종료되고
모든 셸이 함께 종료되므로, 일반 확인 대신 "pytmux 종료" 경고 팝업이 떠 한 번 더
확인을 받습니다(기본 포커스는 안전하게 취소에 있습니다).
자주 쓰는 탭(빌드·로그·에디터 등)을 탭바 오른쪽 고정 구역에 분리해 두면, 비고정 탭이 많아 탭바가 스크롤돼도 항상 보이고 실수로 닫는 것을 한 단계 더 막아 줍니다.
-
토글 방법
-
prefix P(대문자) — 활성 탭 고정/해제. (소문자p는 분할/직전 탭에 쓰이므로P) -
ESC모드에서P— 활성 탭 고정/해제 후 모드 종료 - 메뉴 → 탭 → 탭 고정 토글
- 명령
pin-tab/unpin-tab/pin-toggle -
드래그 — 탭을 구분자(
‖) 위나 반대 구역의 탭 위로 끌어다 놓으면 고정/해제가 토글됩니다(같은 구역 안 드래그는 종전대로 순서만 바뀝니다).
-
-
표시 — 고정 탭은 구분자
‖오른쪽 구역에 핀 글리프*를 붙여 모입니다. 탭 선택기(prefix w, choose-tree)에서도 고정 탭에*표식이 붙습니다. - 닫기 보호 — 고정 탭을 닫으려 하면 "고정 탭 닫기" 확인이 한 번 더 떠 실수 닫기를 막습니다.
-
원격 탭 —
remote-attach로 병합된 원격 탭도 고정할 수 있습니다. 고정은 보고 있는 내 탭바 레이아웃에만 적용되며 원격 서버에는 영향을 주지 않습니다.
고정/해제는 탭 번호를 다시 매깁니다(tmux 의
move-window와 같은 성질) — 보이는 순서가 곧 번호 순서입니다.
tmux 와 달리 copy-mode 로 따로 들어가지 않아도, 패널 위에서 휠을 올리면 바로 지난 출력을 볼 수 있습니다. 패널마다 독립적입니다.
키보드로 스크롤백 모드에 들어가려면 prefix [ 를 누릅니다.
| 키 | 동작 |
|---|---|
↑ / ↓
|
한 줄 위/아래 |
PageUp / PageDown
|
한 화면 위/아래 |
g / G
|
맨 위 / 맨 아래 |
q |
스크롤백 모드 종료 |
복사 모드 키 스타일은 설정 set mode-keys vi|emacs 로 바꿀 수 있습니다.
| 동작 | 결과 |
|---|---|
| 패널 클릭 | 해당 패널로 포커스 이동 |
| 경계선 드래그 | 패널 크기 조절 |
| 패널 위쪽 테두리(헤더 행) 드래그 | 패널 들어올리기(pick-up) — 다른 패널에 놓으면 swap, 탭바의 탭에 놓으면 그 탭으로 이동, [+]에 놓으면 새 탭으로 분리 |
| 패널 Shift+드래그 | 텍스트 선택 → 복사(OS 클립보드+페이스트 버퍼) |
| 휠 위/아래 | 커서가 올라간 패널 스크롤백 |
| 우클릭 | 컨텍스트 메뉴 |
상단 탭바 탭 / [+] / ◀▶
|
탭 전환 / (마지막 탭 오른쪽)새 탭 / 가로 스크롤 |
| 탭바에서 탭 드래그 | 탭 재정렬(패널 위로 끌어 놓으면 그 패널과 분할 합류 join) |
콘텐츠 오른쪽 위 [x]
|
현재 탭 닫기(확인 팝업) |
| 하단 바 시계 / 날짜 클릭 | 시계 모드 / 이번 달 달력 오버레이 토글 |
| 하단 바 REC / 토큰 / 서버이름 클릭 | 통합 정보 팝업 |
| 토큰 사용량 클릭 | 토큰 사용량 팝업 |
| Claude 권한모드 footer 클릭 | 권한모드 선택 팝업(auto/default/plan) |
일부 터미널(iTerm2 등)이 alt-screen 에서 휠을 화살표로 바꿔 스크롤백이 안 열릴 때가 있습니다. 그때는
set alt-scroll on(기본) 으로 pytmux 가 휠을 직접 처리하게 두세요.
이 표는 앱 안에서도 볼 수 있습니다 —
:mouse-help(별칭mouse,list-keys와 같은 "키 · 마우스" 팝업) 또는 우클릭 메뉴의 마우스 제스처 도움말.
단축키를 외우지 않아도 메뉴로 거의 모든 동작을 할 수 있습니다. 방향키로 선택하고 Enter 로 실행합니다(첫 항목이 파란색으로 하이라이트). 마우스 클릭도 됩니다.
메뉴는 그룹(서브메뉴) 으로 정리되어 있습니다. 최상위에는 자주 쓰는 항목(검색·명령·
설정·마우스 도움말·토글 등)과 함께 패널 ▸·레이아웃 ▸·탭 ▸ 같은 그룹 진입점이
보이고(플러그인이 항목을 더하면 플러그인 ▸ 도 나타납니다), 그룹을 고르면(Enter)
서브메뉴가 열립니다(Esc 로 상위 메뉴로 돌아갑니다). 토글 항목은 메뉴를 닫지 않습니다.
detach·서버 종료 같은 되돌리기 어려운 동작은 구분선 아래로 따로 떼어 두었습니다.
바닥에 입력창(모달)이 열립니다. 맨 왼쪽에 고정 : 프리픽스가 표시되고(백스페이스로
지워지지 않습니다) 그 뒤에 tmux 와 비슷한 명령을 입력합니다.
입력 중 도우미는 다음과 같습니다.
-
?또는help(commands) — 명령 목록 팝업을 엽니다(아래 §9.3). -
자동완성 — 타이핑하면 회색 고스트로 미리보기(자주 쓰는 옵션
-h등까지 제안), 오른쪽 화살표(→) 또는 Tab 으로 수락합니다. -
명령어/인자 구분 — 첫 토큰(명령어)에 옅은 배경이 칠해져 인자와 한눈에 구분됩니다
(예:
split-window만 강조,-h는 평문). -
토글/선택지 인자(on/off 등) — 명령을 다 치면 오른쪽에
‹ 토글 켜기 끄기 ›처럼 선택지가 떠, 좌우(←→) 또는 상하(↑↓) 화살표로 고르고 Enter 로 실행합니다 (예:monitor-activity,single-border,synchronize-panes). -
인자 이력·추천 —
remote-attach처럼 호스트·이름을 직접 치는 명령은 이전에 입력한 인자를 기억해 다음에 추천합니다. 명령 뒤에 한 칸 띄우면 최근 인자가 후보로 펼쳐져 ↑↓ 로 고르고 Tab 으로 채울 수 있고, 몇 글자 치면 고스트로 자동완성됩니다 (→/Tab 수락).remote-attach·remote-new-tab·remote-detach는 호스트 이력을 공유하고, 레이아웃 이름(layout-save/layout-load)·run-shell·send-keys도 기억됩니다. 이력은 서버별 상태파일에 남아 재시작·재접속 후에도 유지됩니다.
예시는 다음과 같습니다.
new-tab # 새 탭(= new-window)
split-window -h # 좌우 분할(-v 는 상하)
kill-pane # 현재 패널 삭제
resize-pane -Z # 줌 토글
swap-pane -t 2 # 2번 패널과 교환
rename-tab build # 탭 이름변경
select-tab 3 # 3번 탭으로
detach # 앱만 떼기(셸 유지)
전체 명령은 §17 명령 레퍼런스에 있습니다.
명령 이름을 외우지 못해도, 카테고리별로 정리된 전체 명령 목록을 팝업에서 찾아 바로 명령줄에 채울 수 있습니다.
진입 방법 — 셋 중 아무거나:
- 명령 프롬프트(
prefix :또는ESC→:)를 연 뒤?를 입력 - 명령 프롬프트에서
help(또는commands/list-commands)를 입력하고 Enter -
ESC명령 모드에서 곧바로?— 프롬프트를 거치지 않고 바로 팝업이 열립니다
구성과 사용 방법:
-
카테고리 탭 — 명령이 많아
패널·탭·복사/스크롤·레이아웃·모드·Claude·설정/기타로 나뉘어 있습니다.←→또는 탭 클릭으로 전환합니다. 각 탭에는 (검색 중이면) 일치 개수가 함께 표시됩니다(예:패널 (13)). -
검색 — 그냥 타이핑하면 상단 검색창에 들어가 즉시 필터링됩니다. 모든 탭에
일치 개수가 갱신되어 어느 카테고리에 결과가 있는지 한눈에 보입니다.
Backspace로 지웁니다. -
이동 —
↑↓로 명령 사이를 오가고,Home/End로 목록 처음·끝으로 점프합니다. 목록이 길면 오른쪽 스크롤바가 표시됩니다. -
선택 —
Enter를 누르면 그 명령이 명령줄에 채워집니다(팝업이 닫히고 프롬프트로 돌아감). 이어서 인자를 더 입력한 뒤 다시Enter로 실행하거나, 인자가 필요 없으면 곧바로Enter로 실행합니다. -
닫기 —
Esc또는 오른쪽 위[x]클릭.
화면 하단의 안내줄(
타이핑 검색 · ←→/클릭 탭 · ↑↓ 명령 · Home/End 처음·끝 · Enter 선택 · Esc 닫기)에 이 조작이 항상 요약돼 있습니다.
옛 Norton Utilities 의 NCD(Norton Change Directory) 처럼, 디렉토리 전용 트리를 화면 가득 띄워 방향키·타이핑만으로 디렉토리를 골라 빠르게 이동합니다(파일은 안 보이고 디렉토리만 — 파일 매니저가 아니라 "디렉토리 바꾸기" 도구).
열기 — 명령 프롬프트에서 ncd(별칭 nc). 인자 없이 바로 열립니다.
트리는 드라이브 루트(/)부터 현재 패널의 디렉토리(cwd)까지 펼쳐진 채 열리고,
커서는 현재 디렉토리에 놓입니다 — 지금 위치에서 시작해 위(부모)·아래(하위)·옆
(형제) 어디로든 갈 수 있습니다.
조작:
-
↑↓— 이동. -
→— 접힌 디렉토리의 하위를 펼칩니다(필요할 때 서버에서 지연 로드). -
←— 펼쳐져 있으면 접고, 접혀 있으면 부모(상위)로 올라갑니다. -
이름 타이핑(speed search) — 디렉토리 이름 일부를 치면 현재 위치부터 그 이름으로
시작하는(없으면 부분일치) 디렉토리로 즉시 점프합니다. 방향키를 누르면 검색어가
초기화되고,
Backspace로 한 글자 지웁니다. 하단 안내줄에찾기: …로 보입니다. -
Enter— 현재 패널의 셸을 그 디렉토리로cd하고 닫습니다(NCD 의 핵심). -
Shift+Enter(또는Ctrl+O) — 그 디렉토리에서 시작하는 새 패널을 분할로 엽니다(pytmux 확장). 터미널이Shift+Enter를 구분 못 하면Ctrl+O를 쓰세요. -
Esc— 아무 동작 없이 닫기.
Enter의 cd 는 대상 패널이 셸 프롬프트 상태일 때 의미가 있습니다(claude/vim 등이 실행 중이면 그 앱 입력으로 들어갑니다 — 실제 셸 cd 와 같은 한계).
- 붙여넣기 패스스루 — 멀티라인 텍스트를 bracketed paste 로 그대로 전달합니다. 그래서 Claude Code CLI 등에서 줄마다 실행되지 않고 한 번에 붙습니다.
- 이미지 붙여넣기 — 내부 프로그램이 공유 OS 클립보드에서 읽어 동일하게 동작합니다.
- 명령
paste-clipboard(=Ctrl+V) — OS 클립보드(텍스트/이미지) 붙여넣기. - 명령
send-escape— 활성 패널에 ESC 전달(Shift+ESC가 안 먹는 터미널용).
OS(터미널) 네이티브 마우스 드래그로 pytmux 화면을 복사하면 패널 좌/우 경계의
박스드로잉(│ ├ ┤ ─ 등)이 줄 앞·뒤에 딸려 들어와 코드 붙여넣기가 깨집니다.
strip-box-drawing(기본 ON)은 붙여넣기(Ctrl+V/paste-clipboard) 경로에서 줄
앞·뒤의 박스드로잉 런만 떼고 테두리 전용 줄은 버려 이 오염을 제거합니다.
- 줄 내부 박스드로잉(markdown 표·아트)·원래 빈 줄·ASCII
|·들여쓰기는 보존하므로 일반 텍스트엔 안전합니다(박스드로잉이 없으면 무동작). 터미널 bracketed paste 는 제외. - 토글:
settings→ 입력 → "붙여넣기 테두리 제거", 또는strip-box-drawing on|off. - 자세한 설명은 Settings-Popup#붙여넣기-테두리-정화.
Shift+Enter(줄바꿈 LF) · Shift+Tab(backtab/CSI Z) · Shift+Escape(ESC) 는 prefix
없이 바로 활성 패널로 전달됩니다. Claude Code 등에서 Shift+Enter 로 멀티라인 입력,
Shift+Tab 으로 권한/자동 모드 순환에 씁니다. (그냥 Enter 는 제출 CR, 그냥 ESC 는
명령 모드 진입이라 구분됩니다.)
pytmux 는 패널에서 돌리는 Claude Code CLI 에 특화된 보조 기능이 많습니다. 탭바의 상태 아이콘, 하단 상태줄의 컨텍스트·토큰이 모두 pytmux 가 Claude Code 출력을 읽어 자동으로 채운 것입니다.
Claude Code 가 실행 중인 탭에 상태 아이콘을 표시합니다.
-
○— 대기(입력 받을 준비) -
◐— 처리중 -
⊘— 사용량 리밋으로 멈춤
비활성 탭의 작업이 끝나면 탭 배경색으로 완료를 알립니다(그 탭을 보면 해제됩니다).
프롬프트 확인은 claude-prompt-history 플러그인이 맡습니다 — 평소엔 아무것도 그리지
않고, 필요할 때만 transient 하게 나타납니다.
-
:명령 프롬프트에서prompt-history(별칭prompts·ph)를 입력하는 동안, 대상(활성) Claude 패널 위에 직전 프롬프트 미리보기가 잠깐 나타납니다. - Enter 로 실행하면 프롬프트 팝업이 열립니다 — ↑↓ 로 이전 프롬프트들을 살펴보고, Enter 를 누르면 그 프롬프트가 입력된 스크롤백 위치로 점프합니다(Esc 닫기).
- 미리보기 최대 행수는
prompt-history-lines <1-3>으로 설정(영속)합니다.
- 플러그인이므로
pytmuxlib/plugins/claude-prompt-history/디렉토리를 지우면 기능 전체가 조용히 사라집니다(delete-to-disable).
프롬프트 작성창 (블록 선택 편집). Claude Code 의 프롬프트 입력기는 범위 선택 후
수정·삭제 편집을 지원하지 않습니다. 긴 프롬프트를 다듬고 싶을 때는 ESC → Insert
로 pytmux 자체 작성창을 띄우세요(옵트인 — 필요할 때만). 활성 패널의 프롬프트 줄
바로 위에 떠서 이전 출력을 보며 작성할 수 있고, 입력한 내용을 시드로 가져옵니다.
-
Enter= 전송(활성 패널에 붙여넣기) ·Shift+Enter(또는Ctrl+J) = 줄바꿈 — Claude Code 프롬프트와 같은 규칙입니다.Ctrl+S도 전송,Esc는 취소입니다. -
Shift+방향키·Home·End로 블록 선택,Ctrl+A로 전체 선택 후 삭제·교체 편집이 됩니다(자식 프롬프트엔 없는 편집을 작성창이 제공). - 전송은 bracketed paste 로 감싸 멀티라인이 줄마다 제출되지 않게 하고, 끝에
Enter 를 붙이지 않아 자동 제출되지 않습니다(검토 후 직접
Enter). 취소해도 작성 내용은 초안으로 남아 다음에 다시 엽니다.
활성 Claude 패널의 모델·컨텍스트·한도를 상태줄 왼쪽에 표시합니다 — 예:
opus-4.8 · ctx:10%/1M · 37%/5h 사용.
-
opus-4.8— 현재 모델(배지에서 자동 인식). -
ctx:10%/1M— 컨텍스트 사용량% / 윈도우 크기. Claude 가 잔량(예:N% context left)을 그리면100-N(사용량)으로 환산해 보입니다. 못 그리면 세션 누계로 근사(~). -
37%/5h 사용— 5시간 세션 한도 사용률(/usage실측, 아래 §11.8). 단 모델이 Sonnet 이면 5h 세션은 Anthropic 이 모델 통합값으로만 제공해 모델별 측정이 불가하므로, 대신 주간 Sonnet only % (12%/주(Sonnet))를 보입니다.
상태줄의 이 토큰 영역을 클릭/터치하면 토큰 사용량 팝업이 열립니다. 팝업은 위쪽에 노트북 탭(클릭 또는 키)으로 보기를 전환하는 구조이며, 활성 탭은 박스 테두리와 같은 주황색으로 본문까지 이어집니다. 한 번에 한 차원만 보여 줍니다:
| 탭 | 키 | 내용 |
|---|---|---|
| 기간 |
h시 d일 w주 m월 |
시간 버킷별 토큰 합. 서브옵션 정렬(o)로 시간순↔토큰순 |
| 계정 | c |
계정별 전체 이력 합(행 선택 시 그 계정으로 필터+드릴다운) |
| 세션 | p |
Claude 세션별 합. 세션(대표 탭:패널 라벨)·타임스탬프(세션 시작 시각)·토큰 3열 — 이름 없는 세션을 시작 시각으로 식별 |
| 한도 | l |
/usage 실측 한도 상세 + 다음 리셋까지 카운트다운(아래) |
| 대사 | r |
실측 Δ%(실제 /usage) vs 추정 Σ(스크랩) 추세 대조 진단 |
| 경고 | — | 포맷 미인식·반복 루프·장기 턴 등 상태 경고 설명 |
/usage |
u |
숨은 세션으로 실측 한도 즉시 갱신(§11.8) |
시나리오 |
s |
토큰 절감 설정 팝업(§11.7) |
a 로 계정 필터를 순환하고, 방향키로 스크롤, Esc 로 닫습니다. 모든 전환은 서버
왕복 없이 즉시 이뤄집니다. 맨 위 요약줄에 /usage 로 확보한 세션(5h)·주간 한도 %와
현재 창 추정 Σ가 한 줄로 깔립니다.
캐시 토큰 포함: 토큰 수치(기간/세션/계정/모델 표와 상태줄 누계)는 Claude 의 트랜스크립트 기록(
~/.claude/projects/*.jsonl)에서 읽은 정확한 4항목 합 (입력·출력·캐시 생성·캐시 읽기)입니다. 화면 footer 의↑/↓ N tokens스크랩은 캐시 토큰을 못 봐 실제의 ~0.4%만 잡으므로, 요약줄에activity~보조신호로만 곁들여집니다(에이전트 세션 토큰의 대부분은 캐시 읽기라 둘은 200배 이상 차이날 수 있습니다).
시간(h) 뷰에서는 각 시각의 **세션 5h 한도 누적%**를 초록(여유)·노랑(≥50%)·빨강
(≥80%) 계단식 가로 막대로 그려, 5h 창이 차오르다 리셋되는 흐름을 한눈에 봅니다.
막대 앞 연한 톤은 직전 시각에서 이어진 누적이고, 옆 1w% 열은 같은 시각의 주간 한도%
입니다.
한도(l) 뷰는 /usage 실측 한도를 막대(세션 5h·주 전체·주 Sonnet, % 사용·리셋
시각)와 현재 창 추정 Σ, 그리고 다음 리셋까지의 블록-숫자 카운트다운으로 보여 줍니다.
사용량은 세션 동안 유지·누적되며 token-log 로 파일에 영속 기록됩니다.
패널에서 돌던 Claude 세션이 끝나면, pytmux 가 그 패널 프롬프트 위쪽 스크롤 영역에
토큰 사용량 요약(/usage 한도)을 자동으로 한 번 끼워 넣어 줍니다 — 화면(프롬프트)을
깨지 않으면서, 세션을 닫고 나서도 마지막 사용량을 바로 확인할 수 있습니다
(auto-token-on-exit, 기본 ON).
패널에서 돌리던 Claude Code 가 사용량 리밋에 걸려 멈추면, 출력에 표시된 해제 시각을 읽어 그 시각이 되면 자동으로 재개 메시지를 입력합니다.
-
prefix R— 패널마다 켜고 끕니다. 켜진 패널은 상태줄 왼쪽에 주황색AR배지가 뜹니다.
Claude Code 가 패널 하단에 그리는 권한모드 footer(auto mode on …)를 클릭하면
권한모드 선택 팝업이 열립니다(auto/default/plan 순환 주입).
-
claude-auto-mode on— idle 진입 시 자동으로 오토모드로 맞춥니다.
-
claude-rules— 시작 규칙을 편집해 두면 새 세션이나/clear직후 첫 프롬프트에 자동 주입됩니다.
token-saver(별칭 claude-settings)로 Claude 보조 설정 팝업을 엽니다. 각 행을
Enter(또는 클릭)로 토글/순환합니다.
이전의 토큰 과사용 자동 완화(컨텍스트 잔량 자동 정리·하드스톱 자동
/compact·실측 한도 게이트·일/세션/계정 예산·모델 과선택 힌트)는 제거됐습니다. 토큰 추적·로그·상태줄 표시는 그대로이고, 설정 팝업에는 아래의 옵트인 보조 동작만 남습니다.
-
토큰리밋 자동재개 — 리밋이 풀리는 시각에 자동으로
continue를 보냅니다. - 세션 종료 시 토큰 사용량 화면 — 세션이 끝나면 한도 요약을 패널에 표시합니다.
-
권한모드 자동 오토 — idle 진입 시 권한모드를
auto로 맞춥니다(bypass는 건드리지 않음). -
프롬프트 단위 클리어 — 응답이 끝날 때마다 진행상황을 문서화한 뒤
/clear합니다. -
장기 턴 / 반복 루프 경고 — 한 턴이 너무 오래 돌거나(폭주 의심) 같은 출력이 반복되면
(루프 의심) 상태줄에
⚠배지로 알립니다(알림만, 자동 개입 없음).
또한 PTY 밖 알림 훅으로 자리를 비웠을 때도 알림을 받을 수 있습니다 — 리밋 도달·무장된
자동재개 시 set-hook claude-limit 'run-shell …'(또는 claude-auto-armed) 등으로 데스크톱
알림·소리에 연결합니다(기본 미바인딩).
claude-usage(별칭 usage) 또는 토큰 팝업의 /usage 버튼으로, 사용자에게 안 보이는
숨은 Claude 세션을 잠깐 띄워 /usage 패널을 읽어 세션(5시간)·주간 한도 %와 리셋 시각
을 가져옵니다(현재 화면엔 전혀 안 뜹니다). 결과는 토큰 팝업 맨 위와 상태줄 5h 표기에
실측값으로 반영됩니다.
Claude 데스크탑 앱 원격 제어로 연결된 패널은 화면에 Remote Control active 가
보입니다. 이 표시를 클릭/터치하면 정보 팝업이 열리고, 거기서 [r] 로 원격 제어를
켜고 끕니다(해당 패널에 /rc 슬래시 명령을 주입).
auto-launch(기본 ON)는 패널에서 Claude Code 가 새로 시작될 때마다(세션 시작
감지) 다음을 세션당 1회 자동 적용합니다.
-
/rc주입 — 원격 제어(리모트 커넥션)를 켭니다. 화면에 이미Remote Control active가 보이면(재접속·재시작 복원 등) 건너뛰어 켜진 원격 제어를 도로 끄지 않습니다. -
권한모드
auto유도 — 첫 idle 에서 권한모드를auto(자동 수락)로 한 번 맞춥니다 (shift+tab폐루프).
claude-auto-mode(§11.5)가 idle 마다 상시 auto 로 강제하는 것과 달리, auto-launch
는 세션 시작 1회만 작동합니다 — 이후 사용자가 shift+tab 으로 바꾸면 다시 건드리지
않습니다. /rc 제출과 권한 shift+tab 은 입력 프레임을 갈라 한 묶음으로 섞이지 않게
보냅니다.
-
auto-launch off로 끄고auto-launch on으로 켭니다(기본 ON). 설정은opts.json에 영속됩니다.
위 자동화 기능들로 Claude Code 토큰 사용을 절약할 수 있습니다.
하단 바에 탭 목록·줌 상태·시계가 표시됩니다(상단 탭바가 보이면 하단 탭 목록은 생략될 수
있습니다). 다중 줄 상태줄도 설정으로 추가할 수 있습니다. 색은 Textual
textual-dark 팔레트가 기본이며 status-bg/status-fg 로 바꿉니다.
포맷은 status-left/status-right 로 지정합니다(#S 세션, #h 짧은 호스트, #H
호스트, #{pane_title}, %H:%M 등 strftime).
-
prefix t또는 하단 바 시계 클릭 → 시계 모드. 현재 패널을 큰 블록-숫자 시계로 덮습니다(뒤 출력은 흐리게 계속 보입니다).
- 하단 바 날짜 클릭 또는 명령
calendar-mode/cal→ 달력 오버레이. 패널이 충분히 크면 날짜가 블록 문자로 그려진 큰 달력이 되고, 오늘 날짜는 초록색으로 강조됩니다(공간이 좁으면 일반 격자 또는 날짜 문자열로 자동 폴백).
멱등 켜기/끄기 명령은 open-clock / close-clock / open-calendar / close-calendar
입니다.
하단 상태줄의 REC(캡처) · 토큰 · 서버 이름을 클릭하면 탭으로 구분된 단일 팝업이
열립니다 — 캡처 경로 · 계정별 사용량 합계 · 서버 연결상태/RTT 를 ←→ 로 오가며 볼 수
있습니다.
서버 탭에는 최근 60분 RTT 그래프가 함께 그려집니다. 세로 스케일은 관측 peak 에
자동으로 맞춰져 1ms 안팎의 낮은 지연도 막대로 보이고, 임계(degraded 기준)가 그래프
범위 안에 들면 그 높이에 점선 기준선이 표시됩니다. RTT 는 클라이언트가 측정하므로,
클라이언트가 떠 있지 않던 구간은 측정이 없어 바닥에 · 로 표시됩니다(그래프 이력은
재시작에도 유지되도록 영속됩니다).
-
prefix d또는 명령detach— 앱만 떼어냅니다. 셸과 실행 중 프로그램은 서버에서 계속 돌아갑니다. 터미널 창을 닫아도 마찬가지입니다. - 다시
python3 pytmux.py(또는pytmux) — 같은 세션에 attach 해서 이어서 작업할 수 있습니다.
pytmux # 서버 없으면 기동 후 attach, 있으면 attach
pytmux attach # 명시적 attach
pytmux ls # 탭/패널 요약 출력
pytmux kill-server # 서버와 모든 탭/셸 종료단일 세션 모델이라 세션 이름을 지정할 필요가 없습니다.
클라이언트 ↔ 서버 IPC 지연이 커지면 패널 외곽선을 빨간색으로 표시(degraded)하고, 개선되면 원복합니다.
고착되면 reconnect(또는 resync, 또는 워치독 자동)으로 실행 중 셸/Claude 를 죽이지
않고 IPC 만 다시 세워 반응성을 회복합니다.
다른 머신에서 도는 pytmux 서버의 탭들을 이 pytmux 의 탭바에 그대로 가져옵니다 (ssh 안에서 pytmux 를 또 띄우는 중첩 대신 — 페더레이션).
예를 들어 로컬 탭(1:main) 옆에 원격 서버의 탭이 2:⇄host:cmd 분홍 탭으로 병합되고,
그 원격 탭을 보는 동안 패널 외곽선까지 분홍으로 바뀌어 로컬과 한눈에 구분됩니다.
-
remote-attach <host>— 원격 서버의 열린 탭 전부가⇄host:이름모양의 분홍 탭으로 병합됩니다(여러 개면 여러 개). 클릭/alt+숫자로 진입하면 원격 화면·입력이 그대로 이어지고, 보는 동안 패널 외곽선도 분홍이라 로컬과 즉시 구분됩니다(네트워크 저하 빨강이 더 우선). 예:remote-attach user@host. -
원격에서
pytmux를 치면 자동 승격 — ssh 로 들어간 원격 셸에서pytmux를 실행하면, 중첩 거부 대신 바깥(로컬) pytmux 가 그 호스트를 자동으로remote-attach해 분홍 탭으로 띄웁니다(원격 명령은 위임 안내 후 종료).nest-auto-attach off로 끄면 종전처럼 거부 메시지가 나옵니다(기본 ON). -
remote-detach [host]— 그 원격(생략 시 전부)의 분홍 탭을 모두 닫습니다. 원격 서버와 셸은 그대로 살아 있고, 다시remote-attach하면 같은 탭 세트가 동일하게 복원됩니다. -
섞기 금지(로컬↔원격): 원격 탭엔 원격 패널만, 로컬 탭엔 로컬 패널만 둘 수
있습니다. 원격 탭을 보는 중 분할/패널닫기 등 탭 안 조작은 원격에 그대로 적용되지만,
로컬↔원격으로 패널/탭을 옮기는 조작(
join-pane·move-pane·탭 드래그 합치기· 재정렬)은 거부되고 상태줄에 안내가 표시됩니다. - 원격끼리는 머지 OK: 단, 같은 호스트의 두 원격 탭은 마우스로 끌어 한 탭의 두 패널로 합칠 수 있습니다(드래그 합치기 join). 이 조작은 원격 서버로 릴레이되어 그쪽에서 실제로 합쳐집니다(다른 호스트끼리는 불가).
- 전제는 키 인증 또는 ControlMaster 설정입니다.
pytmux 는 활발히 개발 중이라 서버/클라이언트 코드가 자주 바뀝니다. 보통이라면 코드를 새로 반영하려면 서버를 죽이고 다시 띄워야 하는데, 그러면 돌고 있던 셸·프로그램· 스크롤백이 모두 사라집니다. 작업 보존 재시작은 세션을 살린 채 코드만 새것으로 바꿔 줍니다.
-
restart-server— 서버만 제자리에서 re-exec 합니다. 열린 패널의 셸 · 실행 중 프로그램 · 스크롤백을 그대로 살린 채 서버 코드만 새 이미지로 교체합니다. 클라이언트는 자동으로 다시 붙습니다. 서버 측 코드(server.py/model.py/…)를 갱신할 때. -
restart-all(별칭full-restart/restart-client-server) — 서버 + 클라이언트 동시 재시작입니다. 서버는 위와 똑같이 세션을 보존한 채 코드만 교체하고, 클라이언트도 자기 자신을 새 코드로 relaunch(재실행)해 다시 attach 합니다. 즉 서버·클라 양쪽 코드를 한 번에 갱신하면서 작업은 잃지 않는 "전체 업그레이드" 입니다. 클라 측 코드(client.py/clientwidgets.py/…)까지 같이 갱신할 때. 명령 프롬프트뿐 아니라 외부 CLIpython3 pytmux.py cmd restart-all로도 트리거됩니다(연결된 클라가 재시작 통지를 보고 relaunch — 스크립트·헤드리스에서 클라 코드 픽스를 라이브 발효시킬 때). -
restart-check(별칭restart-dry-run) —restart-all을 실제로는 하지 않고 안전한지만 점검해 PASS/FAIL 팝업으로 알려 줍니다(부작용 없음). 서버 re-exec 지원 · 복원할 세션 존재 · 상태 직렬화 round-trip · 모든 패널의 master fd 보유 · 클라 relaunch 인자 해석을 확인하고, 실행 중 버전과 디스크 버전을 비교해 "재시작하면 새 코드가 로드된다" 는 점도 함께 보여 줍니다.
위 팝업의 "버전 차이"(실행 vs 디스크)는 위험 신호가 아니라 재시작 시 새 코드가 로드된다는 뜻입니다. 먼저
restart-check로 PASS 를 확인한 뒤restart-all을 실행하면 안심하고 전체 업그레이드를 할 수 있습니다.
restart-server/restart-all 은 실행 직전에 위 드라이런을 자동으로 한 번 돌립니다.
모든 항목이 PASS 면 곧바로 재시작하지만, 하나라도 FAIL 이면 그대로 강행하지 않고
어떤 점검이 실패했는지 보여 주며 "그래도 재시작할까요?" 를 다시 묻습니다. 작업을 잃을
수 있는 위험한 동작이라 기본 선택은 취소(붉은 강조)입니다. ←→ 로 이동 · Enter 확정 ·
y/n 단축 · Esc(=취소)로 닫습니다.
FAIL 항목(예:
패널 master fd 보유 (0/4))은 그 상태로 재시작하면 해당 셸·실행 중 프로그램이 보존되지 않을 수 있다는 경고입니다. 확신이 없으면 취소를 고른 뒤restart-check로 원인을 확인하세요.
~/.config/pytmux/config(또는 ~/.pytmux.conf, 또는 PYTMUX_CONFIG 환경변수)를
읽습니다. 탐색 순서는 인자 경로 → $PYTMUX_CONFIG → $XDG_CONFIG_HOME/pytmux/config
→ ~/.config/pytmux/config → ~/.pytmux.conf 입니다. 예시는
pytmux.conf.example 를 참고하세요.
직접 편집하지 않아도
settings화면(§17)에서 바꾼 config-scoped 설정은 이 파일의 해당set줄에 자동 기록됩니다(없으면 추가). 주석· 키 바인딩 등 손으로 쓴 내용은 그대로 보존됩니다.
# prefix 키 변경 (기본: Ctrl-b)
set prefix C-a
# 마우스 on/off
set mouse on
# 휠 스크롤백을 pytmux 가 처리(기본). 일부 터미널에서 스크롤백이 안 열릴 때 유지.
set alt-scroll on # off = 터미널 기본 동작에 맡김
# 붙여넣기 시 패널 테두리(박스드로잉) 제거(기본 ON, 일반적으로 유지)
set strip-box-drawing on # off = 정화 없이 클립보드 원문 그대로 붙여넣기
# 상단 탭바: always(기본)=탭 하나여도 표시 / auto=2개 이상일 때만
set tab-bar always
# 복사 모드 키 스타일: vi(기본) 또는 emacs
set mode-keys vi
# 새 탭/패널 시작 디렉토리: current(현재 패널)/home/<경로>
set default-path current
# 상태줄 색(미지정 시 textual-dark 테마)
# set status-bg green
# set status-fg black
# 상태줄 포맷(#S 세션, #h 짧은 호스트, #{pane_title}, strftime)
set status-left " [#S] "
set status-right " #{pane_title}#h %H:%M %Y-%m-%d "
# prefix 후 키 바인딩: bind <key> <command...>
bind | split-window -h
bind - split-window -v
bind r rename-tab
bind k kill-pane
# prefix 없이 바로 발동하는 root 바인딩: bind -n <key> <command...>
# (내장 키 ESC/`/F12/prefix/Ctrl+V 가 우선. 매칭된 키는 셸로 전달되지 않으니
# 셸/앱 키와 안 겹치는 F1~F11·M- 계열을 권장)
bind -n F2 new-window
bind -n M-Right next-tab런타임에 설정 파일을 고치지 않고도 바인딩을 바꾸려면 bind-key/unbind-key/list-keys
명령을 사용합니다(§17) — bind-key -n/unbind-key -n 이 root
테이블입니다.
명령 프롬프트(prefix :)나 외부 CLI(pytmux cmd <명령>)에서 사용합니다. 탭 명령은
tmux 의 윈도우 명령 이름과 별칭을 둘 다 받습니다.
💡 통합 설정 화면: 흩어진 설정을 외우지 않아도
settings(별칭config,preferences,prefs;prefix Enter메뉴의 "⚙ 설정…")로 한 화면에서 보고 바꿀 수 있습니다. 좌측 세로 카테고리 탭(표시·입력/키·동작·상태줄·Claude·고급)을 클릭하거나 Tab/Shift+Tab 으로 그 카테고리 위치로 점프하고, ↑↓ 이동 · ←→ 로 값 변경(켜짐/꺼짐· 선택지를 펼쳐 현재값 강조, 즉시 적용) · 문자열은 Enter 입력 · Claude·플러그인 전용 설정은 링크로 엽니다. config 파일에 영속되는 설정(마우스·prefix·흐리게·상태줄 등)은 바꾸면 사용자 config 파일에 자동 기록되어 재시작해도 유지됩니다.자세한 사용법과 카테고리별 설정 표는 Settings-Popup 페이지를 참고하세요.
| 명령 | 동작 |
|---|---|
split-window -h / splitw -h
|
좌우 분할 (-v = 상하) |
kill-pane / killp
|
현재 패널 삭제 |
resize-pane -Z |
줌 토글 |
swap-pane -t <n> |
n 번 패널과 교환 |
rotate-window |
윈도우 내 패널 회전 |
pane-border on|off |
단일 패널 테두리 표시 토글 |
| 명령 | 동작 |
|---|---|
new-tab / new-window / newt / neww
|
새 탭 |
kill-tab / kill-window
|
탭 삭제 |
rename-tab <name> / rename-window <name>
|
탭 이름변경 |
select-tab <n> / select-window <n> / selectt / selectw
|
n 번 탭 선택 |
next-tab / prev-tab
|
다음/이전 탭 |
move-tab -t <n> / move-tab-left|right|first|last
|
탭 이동 |
swap-tab -t <n> |
탭 교환 |
choose-tree / choose-tab
|
탭/패널 트리 선택기 |
ncd (별칭 nc) |
디렉토리 트리(NCD)로 이동 — §9.4 |
remote-attach <host> |
원격 pytmux 서버의 탭 전부를 분홍 탭으로 병합 — §14.1 |
remote-detach [host] |
그 원격(생략 시 전부)의 분홍 탭 모두 닫기(원격 서버는 유지) |
| 명령 | 동작 |
|---|---|
layout-save <name> |
현재 탭 레이아웃 저장 |
layout-load [name] |
저장 레이아웃을 현재 탭에 덮어쓰기(생략 시 선택기) |
layout-load-new <name> |
저장 레이아웃을 새 탭으로 열기 |
next-layout |
프리셋 레이아웃 순환 |
| 명령 | 동작 |
|---|---|
clock-mode |
현재 패널을 큰 블록 시계로 덮기(토글) |
calendar-mode / cal
|
이번 달 달력 오버레이 토글 |
open-clock / close-clock
|
시계 모드 멱등 켜기/끄기 |
open-calendar / close-calendar
|
달력 멱등 켜기/끄기 |
settings / config / preferences
|
통합 설정 화면(모든 설정을 한 곳에서, config 영속) |
ncd / nc
|
디렉토리 트리(루트→cwd 펼침·찾기·Enter cd) |
ime-indicator |
IME(한/영) 상태 배지 토글 — 활성 패널 커서 줄의 오른쪽 끝에 표시. macOS·Windows 는 한/영 키만 눌러도(입력 전) 즉시 반영 |
inactive-dim on|off |
한 탭에 패널이 둘 이상일 때 비활성 패널을 흐리게(활성 식별) 토글 |
inactive-dim-ratio [0~0.8] |
비활성 패널 흐리게 세기 조정(클수록 어두움, 기본 0.18; 인자 생략 시 현재 값 표시) |
| 명령 | 동작 |
|---|---|
paste-clipboard |
OS 클립보드(텍스트/이미지) 붙여넣기 (= Ctrl+V) |
strip-box-drawing on|off |
붙여넣기 시 패널 테두리(박스드로잉) 제거 토글(기본 ON) |
send-escape |
활성 패널에 ESC 전달 |
| 명령 | 동작 |
|---|---|
token-log / token-usage
|
토큰 사용량 팝업(기간·계정·세션 뷰 + 실측 한도) |
token-saver / claude-settings
|
Claude 보조 설정 팝업(자동재개·세션종료 토큰화면·오토모드·프롬프트 클리어·경고) |
usage-view |
사용 한도 막대 + 다음 리셋 카운트다운 화면 |
claude-usage / usage-panel
|
그림자 /usage 갱신 / 한도 막대 그래프 |
prompt-history / prompts / ph
|
Claude 프롬프트 히스토리 팝업·미리보기 |
model |
모델·컨텍스트 변경 팝업(/model 주입) |
claude-rules |
시작 규칙 편집(새 세션/clear 후 자동 주입) |
claude-auto-mode on|off |
idle 시 권한모드 자동 오토모드 전환 |
auto-launch on|off |
새 세션 시작 시 /rc(원격 제어)+권한 auto 1회 자동 적용(기본 ON) |
auto-retry on|off |
전송 에러 1분 뒤 계속 자동 주입(기본 ON) |
auto-resume on|off |
토큰 리밋 자동 재개 |
prompt-clear on|off |
응답 완료마다 진행상황 문서화 + /clear
|
auto-token-on-exit on|off |
세션 종료 시 토큰 사용량 화면 표시(기본 ON) |
| 명령 | 동작 |
|---|---|
bind-key <키> <명령> / unbind-key <키> / list-keys
|
런타임 키 바인딩 |
capture-output on|off |
패널 출력 캡처(진단) 토글 |
reconnect / resync
|
IPC 강제 재접속(degraded 회복, 서버 보존) |
remote-attach <host> / remote-detach
|
원격 pytmux 의 탭을 분홍 탭으로 어태치/해제 |
nest-auto-attach on|off |
원격에서 pytmux 실행 시 거부 대신 자동 remote-attach 승격(기본 ON) |
restart-server |
작업 보존 재시작(셸/PTY 유지, 서버 코드만 교체) |
restart-all / restart-check
|
세션유지 재시작 + 클라 relaunch / 그 드라이런 |
version |
클라/서버 버전·업타임 팝업 |
detach |
앱만 떼기(셸 유지) |
kill-server |
서버와 모든 탭/셸 종료 |
help / commands / ?
|
전체 명령 목록 |
prefix 기본값은 Ctrl-b 입니다 (설정 set prefix C-a 등으로 변경 가능).
| 키 | 동작 | 키 | 동작 |
|---|---|---|---|
prefix % |
좌우 분할 | prefix " |
상하 분할 |
prefix x |
패널 삭제(확인) | prefix z |
패널 줌 토글 |
prefix o |
다음 패널 | prefix ←↑↓→ |
패널 이동 |
prefix H/J/K/L |
패널 경계 이동 | prefix c |
새 탭 |
prefix , |
탭 이름변경 | prefix & |
탭 삭제(확인) |
prefix . |
탭 이동(인덱스) | prefix : |
명령 입력 |
prefix n / p
|
다음/이전 탭 | prefix 1-9 |
탭 선택(1번부터) |
prefix d |
detach(셸 유지) | prefix [ |
스크롤백 모드 |
prefix t |
시계 모드 | prefix l |
직전 탭 |
prefix Enter |
메뉴 열기 | prefix R |
토큰리밋 자동재개 토글 |
ESC |
명령 모드 | F12 |
명령 프롬프트 바로 열기 |
prefix F12 |
중첩 시 prefix 패스스루 토글 |
-
ESC명령 모드:←↑↓→패널 이동, 위 방향키로 탭바 포커스,hClaude 헤더 포커스,:명령 프롬프트. - 스크롤백 모드(
prefix [):↑/↓,PageUp/PageDown,g/G,q종료. - Shift 조합(
Shift+Enter/Shift+Tab/Shift+Escape)은 prefix 없이 활성 패널로 전달됩니다. - 한글 IME 가 켜져 있어도 단축키가 동작합니다(두벌식 자모를 QWERTY 키로 자동 변환).
앱 안에 들어가지 않고도 셸에서 서버를 제어할 수 있습니다.
pytmux # attach (없으면 기동)
pytmux attach # 실행 중 서버에 attach
pytmux ls # 탭/패널 요약
pytmux kill-server # 서버와 모든 탭/셸 종료
pytmux cmd new-tab # 외부에서 명령 실행
pytmux cmd split-window -h # (명령 프롬프트와 동일한 구문)
pytmux cmd restart-all # 서버+클라 전체 재시작(작업 보존, 클라 코드 갱신)
pytmux --socket PATH … # 사용할 소켓 경로 직접 지정프로그램 출력을 녹화한 뒤 텍스트 프레임으로 재생해 렌더링을 점검합니다.
# 옵션은 파일명 앞, 실행할 명령은 -- 뒤
python3 pytmux.py record --cols 120 cap.raw -- ls -C
python3 pytmux.py replay --cols 120 cap.raw --ruler # 텍스트로 덤프(+열 자)Q. 휠을 굴려도 스크롤백이 안 보입니다.
A. 일부 터미널(iTerm2 등)이 alt-screen 에서 휠을 화살표로 바꿉니다. set alt-scroll on
(기본) 으로 두면 pytmux 가 휠을 직접 처리합니다. 그래도 안 되면 prefix [ 로 스크롤백
모드에 들어가 키보드로 보세요.
Q. 패널 외곽선이 빨갛습니다.
A. 클라↔서버 IPC 지연이 크다는 표시(degraded)입니다. 보통 자동으로 회복되며, 고착되면
reconnect 를 실행하세요. 셸/Claude 는 죽지 않습니다(§14).
Q. 앱을 닫았는데 셸이 살아 있나요?
A. 그렇습니다. 서버가 PTY 를 보유하므로 detach/창 닫기로 셸은 죽지 않습니다. 다시
pytmux 하면 이어서 붙습니다. 정말 다 끝내려면 kill-server 를 쓰세요
(§13).
Q. prefix H/J/K/L(패널 크기)이 한글 입력 중엔 안 먹습니다.
A. 두벌식에서 시프트 구분이 안 되기 때문입니다. 마우스 경계 드래그를 쓰거나 영문 입력
상태에서 누르세요(§5.3).
Q. 중첩(ssh 안에서 또 pytmux)인데 prefix 가 충돌합니다.
A. prefix F12 로 prefix 패스스루를 토글해 안쪽 인스턴스로 prefix 를 흘려보내세요.
Q. 명령 이름이 기억나지 않습니다.
A. 명령 프롬프트에서 ? 또는 help 를 누르면 전체 목록을 방향키로 고를 수 있고,
타이핑하면 회색 고스트 자동완성이 뜹니다(§9.2).