Claude Hud
Claude Code 세션을 위한 터미널 HUD
Claude HUD — 터미널에서 실시간으로 세션 상태 확인
기간2026.03 ~ 2026.04
역할기획 · 구현 · 배포
플랫폼macOS · Windows
개요
Claude Code를 쓰면서 "지금 토큰이 얼마나 남았지?", "어떤 파일 건드렸더라?" 같은 질문을 반복하게 된다. 매번 다른 창이나 명령어로 확인하는 게 번거로워서 직접 만들었다.
Claude HUD는 Claude Code 세션 상태를 터미널 하나에서 확인할 수 있는 TUI 도구다. TOKENS / PROJECT / GIT / TIMELINE 4개 탭으로 구성되어 있고, Ink(React for CLI) 기반으로 구현했다.
특히 TOKENS 탭은 Anthropic API를 직접 호출해 실제 5h 플랜 사용률을 보여준다. 세션 파일을 실시간으로 watch해 응답이 올 때마다 즉시 업데이트되므로, Claude Code를 켜두고 옆에 띄워놓으면 사용량을 계속 확인할 수 있다.
역할 및 기여
Core Features
- chokidar로 ~/.claude/projects/*/sessions/*.jsonl 실시간 파싱 — 추정치 없이 Claude Code 실제 토큰 소비량 직접 집계
- Anthropic OAuth API 직접 호출로 5h 플랜 사용률 조회 — 클라이언트 추산이 아닌 서버 원본 데이터 표시
- API 응답 5분 캐시 + 리셋 타이머 추적으로 과다 호출 없이 최신 상태 유지
- package.json bin 필드 + prepublishOnly 빌드 훅으로 npm 패키징, npx 즉시 실행 가능한 배포 구성
User Experience
- npx claude-code-hud로 글로벌 설치 없이 즉시 실행
- macOS Keychain 자동 인식 + credentials.json 폴백으로 인증 설정 없이 동작
- 한글 키보드 레이아웃(ㅓ/ㅏ, ㅂ, ㅇ 등) 단축키 매핑 — 한국어 입력 상태에서도 탭 전환 가능
- d 키로 accent 색상 5종 전환, r 키로 수동 새로고침 등 인터랙션 커스터마이징
Result
2,800+
npm 누적 다운로드
배포 1개월 내 달성
224
주간 최대 다운로드
커뮤니티 공유 후 단일 주 기록
2 OS
크로스플랫폼
macOS · Windows 지원
Issues
기술 스택
Language
TypeScriptNode.js 18+
Framework
Ink (React for CLI)chokidarfast-glob
Integration
Claude CodeAnthropic APIGit