claude-ultimate-hud
English | 한국어
Claude Code를 위한 궁극의 상태 표시줄 플러그인 - claude-dashboard와 claude-hud의 장점을 결합했습니다.
기능
claude-dashboard에서 가져온 기능
- 🤖 모델 표시: 현재 모델 (Opus, Sonnet, Haiku)
- 📊 프로그레스 바: 컨텍스트 사용률 색상 표시 (초록 → 노랑 → 빨강)
- 📈 토큰 수: 현재/전체 토큰 (K/M 형식)
- ⏱️ Rate Limits: 5시간/7일 제한 및 리셋 카운트다운
claude-hud에서 가져온 기능
- 📁 프로젝트 정보: 디렉토리명 + Git 브랜치
- 📋 설정 개수: CLAUDE.md, rules, MCPs, hooks
- ⏱️ 세션 시간: 작업 시간
- 🔧 툴 활동: 실행 중/완료된 툴 및 횟수
- 🤖 에이전트 상태: 서브에이전트 진행 상황
- ✅ TODO 진행률: 현재 작업 및 완료율
v1.6.0 - Enterprise 플랜 지원
- 🏢 Enterprise 플랜 추가:
plan: "enterprise" 설정으로 Enterprise 사용자 지원
- 💰 비용($) 표시: Enterprise 플랜은 사용량을 메시지 횟수(%) 대신 달러($) 단위로 표시
- ⏱️ 5시간 rate limit 유지: Enterprise에서도 5시간 rate limit 및 리셋 카운트다운 표시
- 🌐 i18n 확장: 비용(Cost/비용) 라벨 한국어/영어 지원
v1.5.2 - Burn Rate 제거
- 🗑️ Burn rate 제거:
🔥 14K tok/min 표시 완전 삭제 — speed-tracker.ts 유틸리티, BURN_RATE_WINDOW_MS 상수, burnRate 필드 일괄 제거
- 📦 번들 경량화: 미사용 토큰 속도 추적 코드 및 캐시 파일(
claude-ultimate-hud-speed-cache.json) 제거
v1.5.1 - 코드 품질 & 버그 수정
- 🔧 공유 execFileAsync: git.ts, credentials.ts, i18n.ts의 중복
execFileAsync를 utils/exec.ts로 추출
- 🐛 서로게이트 페어 수정:
sliceVisible에서 이모지/보충 평면 문자 올바르게 처리 (str[i] → codePointAt + charLen)
- ⚡ O(n) ANSI 정규식:
sliceVisible에서 str.slice(i).match() → sticky regex (/y 플래그)로 O(n^2) 제거
- 🎯 Agent 도구 감지: transcript 파서가 'Task' (레거시)와 'Agent' (현재) 도구명 모두 감지
- 🏷️ omc-line → stats-line 이름 변경: OMC 명명 잔재 제거
- 🗑️ T/A/S 카운터 제거: stats 라인에서
T:35 A:0 S:0 표시 제거
- ⚙️ 기본 플랜 변경:
DEFAULT_CONFIG 기본값 max200 → max100
- ♻️ extractTarget 재사용: 수동 slice를 기존
truncate 유틸리티로 교체
v1.5.0 - API 안정성 & 확장 기능
- 🔒 User-Agent 수정:
claude-code/2.1로 변경하여 Anthropic API 429 방지
- 🔄 429 retry-after:
retry-after 헤더 읽고 ≤10초 시 1회 재시도, 실패 시 stale 캐시 반환
- ❄️ Negative caching: API 에러 시 30초 TTL 에러 캐시로 에러 폭풍 방지
- 🔐 Stampede prevention: 파일 기반 exclusive lock으로 동시 API 호출 방지
- 📊 네이티브 context % 우선:
stdin.used_percentage 있으면 우선 사용 (더 정확)
- ⏱️ 네이티브 세션 시간 우선:
stdin.total_duration_ms 있으면 우선 사용
- 🌿 Git 확장: dirty 마커(
*), ahead/behind(↑N ↓N), 3개 git 명령 병렬 실행
- 📝 Lines changed: 코드 변경량 표시 (
+42 -8)
- 🔍 Token breakdown: context ≥ 85% 시 토큰 상세 (
in: 150K, cache: 32K)
- 📋 TaskCreate/TaskUpdate: 신규 Claude Code 태스크 도구 지원
- 📏 터미널 너비 인식: ANSI 인식 문자열 자르기, CJK/이모지 2칸 계산
- ⚙️ 위젯 토글:
config.display로 개별 위젯 표시/숨김 설정
v1.4.0 - 코드 경량화 & 품질 개선
- 🗑️ OMC 코드 완전 제거: ralph/autopilot/ultrawork 상태 추적 삭제,
omc-state.ts 제거 (번들 39.8KB → 36.9KB, -7.3%)
- 🛡️ stdin 입력 검증: 필수 필드 누락 시
⚠️ stdin: missing fields 명확한 에러 출력
- 🔢 토큰 포맷 정밀도 개선: 950K 이상은 M 표기로 전환 (
999K → 1.0M)
- 🎯 색상 임계값 상수화: 매직넘버 50/80 →
COLOR_THRESHOLD_WARNING/DANGER로 통합
- 🧹 AUTOCOMPACT_BUFFER 제거: 값이 0인 무의미한 상수 삭제
- 🔍 디버그 트레이스 추가:
CLAUDE_HUD_DEBUG=1 시 cache hit/miss, keychain/file 소스 추적
- 🔒 strict perms 모드:
CLAUDE_HUD_STRICT_PERMS=1 시 insecure 파일 권한 거부
- 📦 API beta 헤더 상수화: 하드코딩 →
ANTHROPIC_BETA_HEADER
v1.3.1 - 60배 성능 개선
- 🔥 clearTimeout 버그 수정:
readStdin()의 setTimeout 핸들 미해제로 프로세스가 타이머 만료까지 2~5초 대기하던 핵심 버그 수정
- ⚡ config-counter 파일 캐시 (60초 TTL): 매 호출 15+ sync FS 호출 → 캐시 hit 시 1회 read
- ⚡ git branch 파일 캐시 (30초 TTL): 매 호출 child process spawn → 캐시 hit 시 1회 read
- 🔀 getTranslations 병렬화: 순차 대기 제거, Phase 2 I/O 블록으로 이동
- 📉 STDIN 타임아웃 단축: 5초 → 2초
v1.3.0 신규 기능
- ⚡ Transcript 증분 파싱: 파일 캐시 기반 증분 읽기로 세션이 길어져도 일정한 HUD 속도
- 🚀 API 캐시 TTL 5배 증가: 60초 → 300초로 API 블로킹 빈도 대폭 감소
- 🏗️ pre-built JS 사용: statusLine이
dist/index.js를 직접 실행하여 TS 컴파일 생략
- 🌐 i18n 확장: TODO 완료 메시지, Thinking 상태 한국어/영어 번역 지원
- 🐛 변수 충돌 수정: stats 렌더러의
t 변수 shadowing 버그 수정
추가 기능
출력 예시
🤖 Opus 4.6 │ ████░░░░░░ 18% │ 37K/200K │ 5시간: 12% (3시간59분) │ 7일: 전체 18% │ 소넷 1%
💭 사고 중 │ 🎯 skill:commit │ +156 -42
📁 my-project git:(main* ↑2) │ 2 CLAUDE.md │ 8 rules │ 6 MCPs │ 6 hooks │ ⏱️ 1h30m
◐ Read: file.ts │ ✓ Bash ×5 │ ✓ Edit ×3
◐ explore: 패턴 찾는 중... │ ✓ librarian (2s)
▸ 인증 플로우 구현 (2/5)
⚠️ 컨텍스트 85% - /compact 권장
고컨텍스트 시 토큰 상세:
🤖 Opus 4.6 │ █████████░ 91% │ 182K/200K │ (in: 150K, cache: 32K) │ 5시간: 49% (1시39분)
🔴 컨텍스트 91% - /compact 필요!
설치
플러그인 마켓플레이스에서 설치
/plugin marketplace add hadamyeedady12-dev/claude-ultimate-hud
/plugin install claude-ultimate-hud
/claude-ultimate-hud:setup
참고: 마켓플레이스 설치 경로는 ~/.claude/plugins/cache/claude-ultimate-hud/
수동 설치
git clone https://github.com/hadamyeedady12-dev/claude-ultimate-hud.git ~/.claude/plugins/claude-ultimate-hud
cd ~/.claude/plugins/claude-ultimate-hud
bun install && bun run build
그 다음 실행:
/claude-ultimate-hud:setup
설정
/claude-ultimate-hud:setup
실행하면 플랜을 선택하는 인터랙티브 메뉴가 표시됩니다: