Claude Code Plugins
pytmux 패널 안에서 돌아가는 Claude Code 세션을 감시·보조·절감하는 플러그인 묶음을 한곳에 모은 개요 페이지입니다. 각 플러그인은 독립 디렉토리(pytmuxlib/plugins/<name>/)로 존재하며, 디렉토리를 통째로 지우면 그 기능이 조용히 사라집니다(delete-to-disable) — 코어는 플러그인을 직접 import 하지 않고 레지스트리 훅으로만 닿기 때문입니다. 지우지 않고 끄려면 :plugins(플러그인 관리 팝업)에서 토글하면 됩니다.
pytmux의 Claude Code 관련 기능은 한 가지 원칙을 공유합니다:
사용자의 사용 습관을 크게 바꾸지 않는 범위 안에서, 토큰 과사용을 "결정론적(deterministic)"으로 완화한다.
즉 사용자는 평소처럼 Claude Code를 쓰고, pytmux는 명시적이고 예측 가능한 규칙으로만 낭비를 줄입니다. 현재 제공되는 모든 자동 개입은 규칙이 분명해 동작이 재현 가능(reproducible) 합니다:
-
토큰 사용량 가시화 — 상태줄 배지·토큰 로그·
/usage실측 한도 대시보드로 "지금 얼마나 쓰고 있는지"를 항상 보이게. - 임계값 기반 자동 개입(token-saver) — 잔량/사용률이 정해 둔 % 임계를 넘을 때만, 그것도 응답 완료 경계에서 1회 개입.
-
컨텍스트 한도 도달 시 자동
/compact— 하드스톱·잔량 부족 같은 명시적 신호에만 반응. - 자동 세션 재개·권한 모드·시작 규칙 주입 — 모두 트리거와 결과가 1:1로 정의된 규칙.
이 결정론적 성격 덕분에 모든 자동 액션은 기본 OFF 또는 안전 기본값이며, 무장된 액션은 카운트다운(⏳)을 보여 주고 사용자가 입력하면 즉시 취소됩니다 — 즉 예측 가능하고 되돌릴 수 있습니다.
⚠️ 아래는 계획/로드맵입니다. 현재 출시된 기능은 위에서 설명한 대로 전부 결정론적입니다.
결정론적 규칙은 "어떤 조건에서 무엇을 한다"가 분명한 만큼, 미묘한 낭비 패턴(예: 같은 작업을 무거운 모델로 반복, 컨텍스트를 비효율적으로 채우는 습관)까지는 잡기 어렵습니다. 다음 단계로, 고정 임계 규칙의 한계를 넘어 비결정론적(non-deterministic) 방법으로 토큰 과사용을 억제하는 방향을 검토하고 있습니다:
- 휴리스틱 판단 — 단일 임계가 아니라 여러 신호(턴 길이·반복도·컨텍스트 채움 속도)를 종합한 추정.
- 적응형 개입 — 사용자/세션의 실제 사용 패턴에 맞춰 개입 강도·시점을 조정.
- 학습 기반 권고 — 과거 사용 이력을 바탕으로 "더 가벼운 모델/정리 시점"을 제안.
현재는 비결정론적 개입의 위험(오탐·예측 불가능성)을 신중히 평가하는 단계이며, 도입 시에도 알림·권고 우선 → 자동 개입은 옵트인이라는 결정론 시대의 안전 원칙을 그대로 유지할 계획입니다.
가장 큰 플러그인입니다. Claude 패널 화면을 읽어 상태(idle/busy/limit)·토큰 사용량·5h 한도 근접도·컨텍스트 여유를 실시간 추적하고, 상태줄 좌하단에 모델 배지·컨텍스트%·5h 사용률%·계정을 표기합니다. 임계 도달 시 ⚠ 경고·⏳ 자동액션 카운트다운·💡 모델 힌트 배지가 함께 뜹니다.
주요 기능
-
모니터링 — 숨은
/usage스크랩으로 실측 세션·주간 한도를 가져와 근사 분모를 대체. -
보조 자동화(옵트인, 결정론적) — 토큰 리밋 자동 재개, 전송 에러 자동 재시도, idle 시 권한모드 자동 전환, 프롬프트 단위 정리(완료마다 doc+
/clear), 세션 종료 시 토큰 화면. -
표시·팝업 — 토큰 로그(
token-log), 사용 한도 막대(usage-panel), 모델 변경(model), 시작 규칙 편집(claude-rules). -
알림만 — 장기 턴·반복 루프 경고(
⚠).
상태줄 토큰 영역을 클릭하면 토큰 사용량 팝업이 열립니다. 노트북 탭으로 기간(시/일/주/월)·계정·세션·한도 뷰를 한 번에 한 차원씩 보여 줍니다.
시간 뷰는 각 시각의 5h 한도 누적%를 계단식 가로 막대로 그립니다.
한도 뷰는 /usage 실측 한도 막대와 다음 리셋까지의 카운트다운을 보여 줍니다.
claude-usage(별칭 usage)는 사용자에게 안 보이는 숨은 세션을 잠깐 띄워 /usage 패널을 읽어 세션(5h)·주간 한도 %와 리셋 시각을 실측합니다.
토큰 리밋에 걸리면 출력의 해제 시각을 읽어 그때 자동으로 재개 메시지를 입력합니다(패널별 AR 배지).
Claude가 그리는 권한모드 footer를 클릭하면 auto/default/plan 선택 팝업이 열립니다.
claude-rules로 시작 규칙을 편집해 두면 새 세션이나 /clear 직후 첫 프롬프트에 자동 주입됩니다.
/rc 슬래시 명령으로 켜지는 원격 제어는 화면 표시를 클릭해 정보 팝업에서 [r]로 토글합니다. auto-launch(기본 ON)는 새 세션 시작마다 /rc 주입과 권한모드 auto 유도를 세션당 1회 적용합니다.
![원격 제어 팝업 — [r]로 /rc 토글](images/25-remote-control.svg)
주요 명령: token-saver · token-log · usage-panel · claude-usage · model · claude-rules. 토글: auto-resume · auto-retry(기본 on) · auto-token-on-exit(기본 on) · claude-auto-mode · auto-launch(기본 on) · prompt-clear.
→ 심층 개발 가이드: Dev-Guide-claude-code
Claude API 사용량 한도와 다음 리셋까지 남은 시간을 한 화면에 크게 보여 줍니다. claude-code가 숨은 /usage 스크랩으로 status에 실어 둔 데이터를 재사용하므로 추가 네트워크 호출·의존성이 없습니다. 세션 5h·주 전체·주 Sonnet 막대와 가장 이른 리셋의 카운트다운(대형 시계 폰트)을 그립니다.
사용법 — usage-view(별칭 token-viewer·usage-clock)에 popup(중앙 모달, 기본)·tab(풀스크린)·pane(활성 패널 오버레이) 인자를 줍니다. 화면 안에서 [u] 갱신·[t] 팝업↔탭·[a] pane 오버레이·Esc/q 닫기. claude-code가 없거나 아직 실측 전이면 "한도 데이터 없음" 안내만 표시합니다(하드 참조 없음).
→ 심층 개발 가이드: Dev-Guide-claude-token-usage-view
Claude 패널에 입력한 프롬프트들을 시간순으로 기록하고 미리보기·검색·점프합니다. 평소엔 아무것도 그리지 않고, 필요할 때만 transient하게 나타납니다(제거된 단일행 스티키 헤더를 대체).
세 가지 표면
- 추적 — Enter 제출 시 한 항목으로 확정·영속(멀티라인도 한 항목, 제어 시퀀스·연속 중복 제외, 패널당 최근 200개).
-
transient 미리보기 —
:명령으로prompt-history를 작성하는 동안만 대상 패널 외곽선 위에 직전 프롬프트를 1~3행 오버레이. - 팝업·점프 — 팝업에서 ↑↓로 이전 프롬프트를 고르고 Enter로 그 프롬프트가 입력됐던 스크롤백 위치로 점프(텍스트 검색 기반, 코어 무수정).
사용법 — prompt-history(별칭 prompts·ph)로 팝업, prompt-history-lines <1-3>(별칭 ph-lines)로 미리보기 행수 설정(영속). 팝업 안에서 ↑↓/Home/End/PgUp/PgDn 선택 · Enter 점프 · +/- 행수 조정 · Esc 닫기.
→ 심층 개발 가이드: Dev-Guide-claude-prompt-history
이 머신의 Claude Code 세션 목록을 보여 주고, 하나를 골라 Enter하면 새 탭을 열어 그 세션을 리줌합니다. 세션 파일은 서버 측에 있으므로 열거·리줌을 서버에서 수행해 remote-attach 안전성과 새 탭 패널 id 경쟁을 회피합니다. 셸로 주입하는 세션 id는 위생 검사(영숫자/.-_만 허용)를 거쳐 셸 인젝션을 막습니다.
사용법 — claude-resume(별칭 claude-sessions·cr). 피커에서 ↑↓ 탐색 · Enter 새 탭에서 리줌 · Esc 닫기. 선택한 세션의 원래 디렉토리에서 새 탭이 열리고 claude --resume <id>가 주입됩니다.
→ 심층 개발 가이드: Dev-Guide-claude-resume
Claude Code의 피드백 권유 표면 두 가지를 폭을 유지한 채 공백으로 덮어 화면에서 가립니다:
- 시작 팁 "Tip: Use /feedback to help us improve!"
- 세션 종료 평가 배너 "How is Claude doing this session? (optional)" + 평가 옵션 줄
코어는 render 행을 클라 전송 직전에 server_filter_rows 훅으로만 이 플러그인에 흘려 보내므로, 플러그인이 없으면 행은 변형 없이 지나갑니다(no-op). 평가 배너는 세션이 끝나는 순간 떠 현재 실행 신호가 이미 떨어질 수 있어, 디바운스된 Claude 신호로 그 전이 창을 덮습니다. 표시만 가리고 키는 주입하지 않습니다(단일 Esc가 작동 중인 턴을 interrupt할 수 있어 폐기).
옵션 없음 — 끄려면 디렉토리 삭제 또는 :plugins에서 토글하면 두 문구가 다시 보일 뿐입니다.
→ 심층 개발 가이드: Dev-Guide-claude-disable-feedback
모든 항목은 결정론적 규칙이며, 사용자의 평소 사용 흐름을 끊지 않도록 설계됐습니다.
이전의 토큰 과사용 자동 완화(실측 한도 게이트·컨텍스트 자동 정리/
auto-compact·auto-doc-clear·하드스톱 자동/compact·예산 계획 유도·모델 과선택 힌트)는 제거됐습니다. 토큰 추적·표시는 그대로 유지되고, 자동화는 아래의 옵트인 보조 동작만 남습니다.
| 기능 | 결정론적 규칙(트리거 → 동작) | 습관 영향 최소화 방식 |
|---|---|---|
| 사용량 가시화 | 화면 스크랩 → 상태줄 배지·토큰 로그·/usage 한도 막대 |
표시만, 어떤 입력도 가로채지 않음 |
토큰 리밋 자동 재개(auto-resume) |
출력의 해제 시각 도달 → 재개 메시지 입력 | 패널별 옵트인, AR 배지로 가시화 |
전송 에러 자동 재시도(auto-retry, 기본 on) |
전송 에러 감지 → 재시도 | 사용자 의도 메시지만 재전송 |
권한모드 자동 전환(claude-auto-mode) |
idle 진입 → 권한모드 auto
|
bypass는 명시 의도라 건드리지 않음 |
프롬프트 단위 정리(prompt-clear) |
응답 완료 경계 → 진행상황 문서화 + /clear
|
옵트인, 완료 경계에서만 |
시작 규칙 주입(claude-rules) |
새 세션//clear 직후 첫 프롬프트 → 규칙 주입 |
사용자가 직접 작성한 규칙만 |
무장 액션 카운트다운(⏳) |
토큰리밋 자동재개 대기 → 남은 초 표시 | 사용자 입력 시 즉시 취소 |
장기 턴·반복 루프 경고(⚠) |
한 턴이 길거나 동일 출력 반복 → 경고 배지 | 알림만, 자동 개입 없음 |
아직 구현 전입니다. 위 표의 기능은 전부 결정론적입니다.
위의 고정 임계·1:1 규칙으로는 포착이 어려운 낭비 패턴을 다루기 위해, 다음을 검토합니다:
- 휴리스틱 종합 판단 — 단일 % 임계 대신 턴 길이·반복도·컨텍스트 채움 속도 등 다중 신호를 합쳐 "낭비 가능성"을 추정.
- 적응형 개입 시점 — 세션/사용자별 실제 패턴에 맞춰 개입 강도와 타이밍을 조정.
- 학습 기반 권고 — 누적 사용 이력으로 더 가벼운 모델·정리 시점을 제안.
설계 우선순위는 그대로입니다: 권고·알림 우선, 자동 개입은 옵트인, 모든 개입은 가시적이고 취소 가능. 비결정론적 판단이 들어오더라도 사용자의 통제권을 줄이지 않는 선에서만 도입합니다.
- Plugin-System — 플러그인 레지스트리·훅 계약·delete-to-disable 구조
- User-Manual — 전체 사용자 매뉴얼(§11 Claude Code 연동 포함)
- Project-Overview — pytmux 프로젝트 개요