claude-code-hud

한국어 | English

---

한국어

Claude Code로 작업할 때 토큰 사용량, git 상태, 파일 구조, 세션 히스토리를 IDE나 별도 툴 없이 터미널 하나에서 확인할 수 있는 HUD입니다.

사용법

터미널 두 개를 열고 같은 프로젝트 디렉토리에서 실행하면 됩니다.

터미널 A                         터미널 B
─────────────────────────────    ─────────────────────────────
cd ~/my-project                  cd ~/my-project
claude                           npx claude-code-hud
(Claude Code 작업 중...)          (HUD 실시간 표시)

HUD는 현재 디렉토리를 기준으로 토큰, git, 프로젝트 정보를 자동으로 인식합니다.

# tmux로 한 화면에서 split
cd ~/my-project
tmux split-window -h "npx claude-code-hud"

설치

# 방법1. 전역 설치 (권장)
> npm install -g claude-code-hud
> claude-hud

# 방법2. 설치 없이 바로 실행
> npx claude-code-hud

기능

1 TOKENS 탭

• 컨텍스트 윈도우 사용량 게이지 (OK / MID / WARN) — 사용량에 따라 헤더 색상 변경
• Anthropic API 기반 5h / 주간 사용률 — 1h 23m 형식으로 리셋까지 남은 시간 표시
• input / output / cache-read / cache-write 토큰 분류
• 세션 output 통계 (total / avg / peak)
• 오늘 사용량 — 자정 기준 input / output / cache / 비용 합산
• now — 현재 진행 중인 작업 (직접 입력한 마지막 프롬프트) 한 줄 표시

2 PROJECT 탭 — 인터랙티브 파일 브라우저

• 디렉토리 트리 (펼치기/접기)
• Git 변경 파일 색상 표시 — 수정(노란색 M) / 추가(초록 A) / 삭제(빨강 D)
• 파일 선택 시 소스 코드 뷰어 (split 패널)
• 패키지 의존성 트리
• API 엔드포인트 감지

▸ TREE                          │ ▸ SOURCE  src/index.ts
  ▼ src/            23f         │    1  import React from 'react'
    ▼ components/    8f         │    2  import { render } from 'ink'
      Header.tsx  M             │    3
    ▶ hooks/         4f         │    4  render(<App />)
  ▶ scripts/         6f         │    …  [j/k] scroll  [esc] close

3 GIT 탭

• 현재 브랜치, ahead/behind 카운트
• 변경 파일 목록 (MOD / ADD / DEL) + 실제 +/- 라인 수
• 파일별 diff 시각화
• 최근 커밋 히스토리
• 브랜치 전환 — b 키로 로컬 브랜치 목록 표시, 선택해서 바로 checkout

4 TIMELINE 탭

• 현재 세션에서 사용자가 입력한 메시지 히스토리
• 시간 + 내용 표시, 10개씩 j/k 스크롤

키보드 단축키

키	동작
1 2 3 4	탭 전환
j / k	스크롤 / 트리 이동
→ / Enter	디렉토리 펼치기 / 파일 열기
← / Esc	접기 / 소스 뷰어 닫기
b	브랜치 전환 (GIT 탭)
d	액센트 색상 변경 (blue → red → amber → green → pink)
r	수동 새로고침
q	종료

한글 키보드 모드에서도 동작합니다 — ㅓ/ㅏ (j/k), ㅇ (d), ㄱ (r), ㅂ (q), ㅠ (b)

요구사항

• Node.js 18+
• Claude Code 설치 및 로그인 (토큰 데이터 수집)
• Claude Pro / Max 플랜 권장 (5h / 주간 사용률 표시)
• Git (GIT 탭 사용 시)

플랫폼 지원

기능	macOS	Windows
기본 실행	✅	✅ Node.js 설치 후 npx
토큰 / Git / 파일 브라우저	✅	✅
5h / 주간 사용률	✅ Keychain 자동 인식	⚠️ ~/.claude/.credentials.json 폴백
터미널 렌더링	✅	✅ Windows Terminal 권장 (cmd.exe 깨짐)
한글 키보드	✅	⚠️ IME 방식 차이로 미지원 가능

Windows 권장 환경:

• Windows Terminal 사용
• WSL2 환경이면 macOS와 동일하게 동작

Windows에서 5h/wk 사용률이 안 보일 때:
Claude Code를 한 번 실행하면 ~/.claude/.credentials.json에 credentials이 저장됩니다. HUD는 이 파일을 자동으로 읽습니다.

---

English

A Terminal HUD (Heads-Up Display) for Claude Code — real-time token usage, git status, interactive project file browser, and session history. No IDE, no extra tabs. Just a second terminal window.

Usage

Open two terminals in the same project directory.

Terminal A                       Terminal B
─────────────────────────────    ─────────────────────────────
cd ~/my-project                  cd ~/my-project
claude                           npx claude-code-hud
(working with Claude Code)       (HUD live display)

# tmux split pane
cd ~/my-project
tmux split-window -h "npx claude-code-hud"

Installation

# Option 1. Global install (recommended)
> npm install -g claude-code-hud
> claude-hud

# Option 2. Run directly without install
> npx claude-code-hud

Features

1 TOKENS tab

• Context window gauge (OK / MID / WARN) — header border changes color with usage
• Real 5h / weekly usage from Anthropic OAuth API — not estimates. Reset time shown as 1h 23m
• Input / output / cache-read / cache-write breakdown
• Session output stats: total / avg / peak per hour
• Today's usage — input / output / cache / cost totals since midnight
• now line — last prompt you typed (not tool results)

2 PROJECT tab — interactive file browser

• Navigable directory tree with expand/collapse
• Git-changed files highlighted — modified (yellow M) / added (green A) / deleted (red D)
• Source file viewer in a split panel
• Package dependency tree from package.json
• API endpoint detection (GET / POST / PUT / DELETE / PATCH)

▸ TREE                          │ ▸ SOURCE  src/index.ts
  ▼ src/            23f         │    1  import React from 'react'
    ▼ components/    8f         │    2  import { render } from 'ink'
      Header.tsx  M             │    3
    ▶ hooks/         4f         │    4  render(<App />)
  ▶ scripts/         6f         │    …  [j/k] scroll  [esc] close

3 GIT tab

• Branch status, ahead/behind remote
• Changed file list (MOD / ADD / DEL) with real +N -N diff counts
• Per-file diff visualization
• Recent commit history
• Branch switcher — press b to list local branches and checkout instantly

4 TIMELINE tab

• User message history from the current Claude Code session
• Timestamped entries, 10 per page, j/k to scroll

Keyboard Shortcuts

Key	Action
1 2 3 4	Switch tabs
j / k	Scroll / move tree cursor
→ / Enter	Expand dir / open file
← / Esc	Collapse / close source viewer
b	Branch switcher (GIT tab)
d	Cycle accent color (blue → red → amber → green → pink)
r	Manual refresh
q	Quit

Korean keyboard layout supported — ㅓ/ㅏ (j/k), ㅇ (d), ㄱ (r), ㅂ (q), ㅠ (b)

Platform Support

Feature	macOS	Windows
Basic run	✅	✅ via npx with Node.js
Tokens / Git / File browser	✅	✅
5h / weekly usage %	✅ Keychain auto-detected	⚠️ Falls back to ~/.claude/.credentials.json
Terminal rendering	✅	✅ Windows Terminal recommended (cmd.exe may break)
Korean keyboard	✅	⚠️ May not work depending on IME

Windows recommendations:

• Use Windows Terminal for proper Unicode rendering
• WSL2 works identically to macOS

5h / weekly usage not showing on Windows?
Run claude once to authenticate — credentials are saved to ~/.claude/.credentials.json which the HUD reads automatically.

How it works

• Token data: Watches ~/.claude/projects/*/sessions/*.jsonl with chokidar — updates instantly on each Claude response
• Timeline: Reads the same JSONL files, filters type === "user" entries for message history
• Usage window: Calls api.anthropic.com/api/oauth/usage using local Claude credentials — cached 5 min
• Git: Polls every 3 seconds
• Project scan: One-time fast-glob scan on startup, r to rescan

---

MIT — letsgojh0810