상세 가이드

pytmux 사용 가이드

설치부터 패널·탭·마우스·메뉴·명령·Claude 연동·토큰·원격·운영·설정·플러그인까지, pytmux 의 모든 기능을 실제 화면 스크린샷과 함께 챕터별로 안내합니다. 각 페이지 아래에는 이전·다음 챕터로 이어지는 링크가 있습니다. 처음이라면 1. 시작 · 핵심 개념부터 차례로 읽으세요. 빠르게 둘러보려면 랜딩 페이지를 먼저 보세요.

🛠 최근 수정사항 · 2026-10-02 금요일 전체 변경 내역 →
  • 설정 설정 화면에서 바꾼 값과 프롬프트로 건 명령이 «적힌 그대로» 먹습니다. 설정 화면·설정 파일·명령 프롬프트가 같은 옵션을 서로 다르게 다루던 자리를 맞췄습니다(파이썬·GUI 클라이언트).
    • alt-scroll — :settings 에서 바꾸면 설정 파일에 적히는데 다음 시작 때 그 줄을 안 읽어 기본값으로 돌아왔습니다. 이제 남습니다.
    • net-rtt-threshold — 빨간 외곽선(응답 지연) 문턱을 설정 파일의 set net-rtt-threshold <초> 로 바꿀 수 있습니다(기본 0.4초 · 0.05~10). 느린 원격 링크에서 늘 빨갛다면 올립니다.
    • set-hook — 명령 프롬프트로 건 훅이 따옴표를 잃어 run-shell "notify.sh $PYTMUX_ACCOUNT" 가 첫 낱말만 돌았습니다. 이제 설정 파일의 hook 줄과 같은 명령으로 돕니다.
    • :set strip-box-drawing on|off 가 조용히 무시되던 것, layout-list 가 명령 목록·자동완성에 안 뜨던 것을 고쳤습니다.
    설정 화면이 파일에 쓰는 줄은 이제 전부 다음 시작 때 다시 읽히는지 시험이 하나씩 잽니다 — 14. 설정.
  • 토큰 토큰 사용량 판의 경고 빨강이 다시 읽힙니다. 패널 앱의 표준 색을 바로잡던 변경(8월)이 판 자체의 막대·사용률 글자까지 어둡게 만들어, 5시간 한도 97% 같은 경고 값이 판 바탕 위에서 거의 안 보였습니다(대비 1.4:1). 판의 의미색을 GUI 와 같은 색으로 고정해 경고 글자가 4.5:1 이상으로 읽힙니다. 패널 안 앱의 색은 그대로입니다. 토큰 판 스크린샷 3장(기간 · 세션 · 한도)을 다시 찍었습니다 — 9. 토큰 사용량.
  • Claude Claude Code 가 이제 스스로 하는 일 넷을 pytmux 에서 걷었습니다. Claude Code 는 사용량 한도가 풀리면 열린 세션을 스스로 이어 가고(2.1.234~), 대화형 세션을 auto 권한 모드로 시작합니다(2.1.284~). 시작 규칙·피드백 문구·원격 제어 자동 연결도 자기 설정으로 다룹니다. 겹친 채 두면 서로 방해합니다 — 예를 들어 pytmux 가 한도 리셋 시각에 대신 치던 continue 가 Claude Code 의 대기를 끊어 버립니다. 그래서 다음을 없앴고, 각각 대신 쓸 설정을 가이드에 적었습니다.
    • 토큰리밋 자동 재개(prefix R·상태줄 AR·auto-resume) → Claude Code 의 「Continue automatically at usage limit」(기본 켜짐)
    • auto-launch·claude-auto-mode → 기본 auto 모드 · "remoteControlAtStartup": true
    • claude-rules → SessionStart 훅(적어 두었던 규칙은 상태 디렉터리의 …claude-rules.retired.txt 로 한 번 보존됩니다)
    • claude-disable-feedback 플러그인 → "spinnerTipsEnabled": false · "feedbackSurveyRate": 0
    전송 오류 자동 재시도(auto-retry)는 그대로입니다 — Claude Code 는 재시도를 다 쓰면 대화형 턴을 끝내기 때문입니다. 파이썬·GUI 클라이언트 둘 다에 적용됩니다. 자세한 설정은 8. Claude Code 연동.
  • 토큰 토큰 사용량 판에서 Tab·←→ 로 탭을 오가고, [머신] 탭이 기기 이름을 씁니다. 지금까지는 판 안에서 다른 탭으로 가는 길이 클릭과 글자 바로 가기(p·l·o)뿐이었습니다. Tab 은 판을 닫아 버렸고 ←→ 도 세션·머신 탭에서는 판을 닫았습니다(GUI 는 두 키를 삼켰습니다).
    • Tab·Shift+Tab — 언제나 다음·이전 탭으로 옮기고 끝에서 감깁니다. 판은 닫히지 않습니다.
    • ←→ — 그 줄에 다른 뜻이 없을 때 이웃 탭입니다. 기간 트리의 펼침·접힘과 한도 탭 모델·컨텍스트 줄의 값 고르기는 그대로입니다.
    • [머신] 탭 · 요약줄 Σ 분해 · GUI 의 머신 판이 같은 이름을 씁니다 — 등록할 때 붙인 기기 이름(보통 호스트 이름)이고, 동기화 서버가 아직 이름을 내려 주지 않으면 셋 다 기기 id 앞 8자리입니다. 종전에는 같은 기기를 세 자리에서 12자 · 8자 · 32자 전체로 다르게 적었습니다.
    • GUI 판은 탭을 옮겨도 높이가 그대로입니다 — 내용이 짧은 탭으로 가면 판이 줄어들던 것을 고쳤습니다.
    파이썬·GUI 클라이언트가 같은 규칙을 씁니다. 자세한 것은 9. 토큰 사용량.
  • 블록 위로 굴리면 패널 첫 줄에 지금 보는 출력의 명령이 붙고, 블록 요약 판이 파이썬 클라이언트에도 생겼습니다. 긴 출력 한가운데서 「이게 무슨 명령의 출력이었지」를 찾으러 다시 위로 굴릴 필요가 없습니다.
    • 스티키 프롬프트 바 — 굴린 패널 첫 줄에 ▲ 명령 띠가 붙고(Claude 패널이면 그 답을 끌어낸 프롬프트), 띠를 누르면 그 프롬프트 줄로 건너뜁니다. 파이썬·GUI 클라이언트에 같은 날 들어갔고, 어느 줄에 띠를 세울지는 한 벌의 규칙을 같은 사례 표로 맞대어 잽니다.
    • 블록 요약 판(summary) — 활성 패널의 블록을 결과 표식(ok·err 등) · 명령 · 작업 디렉토리로 한 판에 보여 줍니다. GUI 에만 있던 판입니다.
    • 그 맞대기가 기존 결함을 하나 잡았습니다 — 파이썬 클라이언트에서 블록을 고르면 다음 명령의 프롬프트 줄까지 한 줄이 딸려 강조·복사되던 것을 고쳤습니다.
    • (저녁에 고침) 파이썬 클라이언트에서 띠의 명령 글자가 파일 경로처럼 보이면 그 글자를 눌렀을 때 스크롤 대신 경로가 복사되던 것 — 이제 띠는 어디를 눌러도 그 프롬프트로 가고, 띠 글자에는 경로 밑줄도 긋지 않습니다(GUI 와 같은 순서).
    셸 블록은 셸 통합 설정이 있어야 생깁니다 — blocks 플러그인.
  • GUI GUI 의 스크롤바를 끌 수 있고, RTT 그래프가 실제 값으로 그려지며, 알림 이력 판이 정본처럼 움직입니다.
    • 스크롤바 — 보이기만 하던 오른쪽 막대를 잡아 끌어 스크롤하고, 막대 바깥 트랙을 누르면 그 비율 자리로 건너뜁니다.
    • RTT 그래프 — 글자 칸을 8단계로 칠하던 막대를 실제 값에 비례하는 픽셀 막대로 바꿨습니다. 임계는 점선, 측정이 없던 구간은 바닥의 점입니다.
    • 알림 이력 판 — 커서로 고르고 Enter 로 전문을 펼치고 c 로 복사합니다. 꼬리줄 안내도 「아무 키나 닫기」에서 실제 키(↑↓ · Enter · c · Esc)로 바꿨습니다.
    • 상태 판의 PageUp·PageDown 이 정본처럼 5줄씩 움직입니다.
    이로써 두 클라이언트가 다르게 구는 자리를 적어 두는 목록(갈림 대장)의 「할 일」이 0 이 됐습니다 — 남은 갈림은 터미널이 못 주는 키 · 픽셀 그림 · OS 창 통합뿐입니다. GUI 클라이언트 소개.
  • 표시 :set ambiguous-width 가 언제나 서버까지 맞추고, ESC[3J 가 스크롤백도 비웁니다.
    • 모호폭(한글 환경에서 폭이 애매한 글자) 설정은 클라이언트와 서버가 따로 들고 있는데, 둘이 어긋난 채로 클라이언트 값과 같은 값을 고르면 서버에 아무것도 알리지 않았습니다 — 「바꿨는데 화면이 그대로다」로만 보였습니다. 이제 이 명령은 언제나 둘을 그 값으로 맞춥니다(파이썬 클라이언트).
    • /clear 류 명령은 화면 지우기(ESC[2J)와 함께 스크롤백 지우기(ESC[3J)를 보내는데, pytmux 가 뒤엣것을 앞엣것과 똑같이 다뤄 화면은 비었는데 위로 굴리면 옛 대화가 그대로 나왔습니다. 이제 xterm·tmux 처럼 스크롤백까지 비웁니다. 화면 격자는 서버가 관리하므로 파이썬·GUI 클라이언트 둘 다에 적용됩니다.
  • 문서 가이드·플러그인 페이지·위키를 지금 코드와 다시 맞추고(새벽·오후 두 차례), 스크린샷을 다시 찍어 내용이 달라진 것을 갈아 끼우고 새 그림을 더했습니다.
    • 새벽 갱신 — 위에서 걷은 기능을 소개하던 문장을 정리하고, 8장에 남은 Claude 보조 기능을 모은 「설정 팝업과 그 밖의 도움」 절을 새로 넣었습니다.
      • 사실과 달랐던 것 — 공유 격자 크기 window-size 의 기본은 latest, Windows 마우스 이동 전달은 기본 on 입니다. 2장은 없어진 --native 대신 pytmux-gui 를 안내합니다.
      • 14장에 설정 파일의 set 줄이 실제로 읽는 옵션 목록을 적고, 파일에 적어도 읽히지 않는 옵션에는 (런타임) 표시를 달았습니다. 7장의 훅 예시는 따옴표가 지켜지는 설정 파일의 hook 줄로 바꾸고, ESC 모드 표에 c·f·b·Shift+ESC·` 를 더했습니다.
      • 플러그인 페이지는 명령 표를 실제 명령 목록과 맞췄고(claude-usage·claude-auto-yes·claude-auto-redraw 등), 블록 고르기 키 · 녹화 로그 경로 · 한/영 배지 자리(커서 줄 오른쪽 끝)를 바로잡았습니다.
      • 스크린샷은 45장을 새로 찍어 6장만 교체했습니다 — 첫 실행 · 메뉴 2장 · 명령 목록 · Claude 설정 팝업 · 설정 팝업에서 걷은 기능의 항목이 빠졌습니다. 나머지는 박혀 있는 시계·날짜만 달랐습니다.
    • 오후 갱신 — 위의 토큰·블록·GUI 변화를 가이드와 위키 매뉴얼에 옮겼습니다.
      • 9장에 탭 이동 키와 머신 이름을, blocks 플러그인 페이지에 스티키 프롬프트 바 · 요약 판 · 결과 표식 표를, 5장에 스티키 바 안내를 더했습니다. GUI 소개에는 「최근에 맞춘 것」 절을 새로 냈습니다.
      • 위키 매뉴얼은 토큰 판 탭 표가 없어진 탭(계정 · 대사)과 옛 키를 아직 싣고 있어 지금 탭과 키로 고쳤고, 스티키 프롬프트 바 · 블록 요약 판 절과 블록 명령 표를 더했습니다.
      • 스크린샷은 토큰 판 꼬리줄에 Tab 안내가 붙어 2장(기간 · 세션)을 교체했고, 스티키 프롬프트 바 · 블록 요약 판(파이썬 클라이언트)과 GUI 의 스티키 바 컷을 새로 넣었습니다.

챕터 한눈에

아래 카드에서 원하는 주제로 바로 갈 수 있습니다. 각 챕터는 해당 기능을 빠짐없이 다룹니다.

01시작 · 핵심 개념탭 → 윈도우 → 패널 계층, 셸 영속, 제어하는 세 가지 방법. 02설치의존성 설치, 실행, pytmux 명령 등록, SSH 자동 attach. 03패널 다루기분할·포커스 이동·크기 조절·줌·swap·rotate·레이아웃·삭제. 04탭 · 윈도우생성·전환·이름·재정렬·고정(핀)·닫기, 상태표시줄. 05스크롤백 · 복사휠 스크롤백, 검색, vi/emacs 키, 복사·붙여넣기. 06마우스로 제어드래그 복사, 클릭·우클릭·휠·경계선·배지 클릭 총정리. 07메뉴 · 명령 프롬프트계층형 메뉴, 명령 프롬프트, 전체 명령 목록, 키 재바인딩. 08Claude Code 연동상태 아이콘·권한모드·전송 에러 재시도·프롬프트 이력·화면 안정성. 09토큰 사용량기간·세션·한도·경고·/usage·시나리오 사용량 팝업. 10여러 머신 토큰 동기화공식 서버(또는 자기호스팅)로 여러 컴퓨터의 사용량을 합칩니다 — 아이디 없는 패스키, 코드 한 줄 등록. 11원격 페더레이션ssh 너머 서버 attach, 분홍 탭, 머지·detach·핀, 다중홉(via), keepalive. 12재시작 · 회복작업 보존 재시작, 네트워크 응답성 표시와 재접속. 13도구 · 위젯시계·달력·ncd 트리·IME 배지·RTT 그래프·캡처·Perforce·작성창. 14설정 파일pytmux.conf 옵션 전체, :settings 팝업, 한/영 전환. 15플러그인delete-to-disable 구조, 플러그인 관리 팝업 :plugins.