Claude Code HUD 개발기
들어가며
Claude Code를 매일 쓰다 보면 반복적으로 불편한 순간이 있다.
- 토큰이 얼마나 남았는지 확인하려고 다른 창을 열어야 한다
- Git 상태 보려고 별도 터미널 탭으로 이동한다
- 프로젝트 구조가 궁금하면 IDE를 따로 킨다
터미널 안에서 Claude Code와 대화하는 중인데 정보를 보러 계속 터미널 밖을 나가야 한다. 이게 흐름이 생각보다 많이 끊긴다.
이런 모든 것들을 터미널 하나만 양쪽에 키고 볼 수 있으면 좋을거라 생각했다. 개인적으로 터미널은 ghostty를 사용하고 있다.
npx claude-code-hud
How to use
터미널 두 개를 같은 프로젝트 디렉토리에서 열면 된다.
터미널 A 터미널 B
───────────────────────────── ─────────────────────────────
cd ~/my-project cd ~/my-project
claude npx claude-code-hud
(Claude Code 작업 중...) (HUD 실시간 표시)
tmux를 쓴다면 한 화면에서 split해서 쓸 수 있다.
tmux split-window -h "npx claude-code-hud"
탭 구성
4개 탭으로 구성된다. 키보드 1 2 3 4로 전환한다.
1. TOKENS
컨텍스트 윈도우 상태를 실시간으로 보여준다.
- 사용량 게이지 (OK / MID / WARN) — 사용량에 따라 헤더 색상이 바뀐다
- Anthropic API 기반 5시간 / 주간 사용률 — 추정치가 아닌 실제 수치. 리셋까지 남은 시간도 표시
- input / output / cache-read / cache-write 토큰 분류
- 오늘 자정 기준 input / output / cache / 비용 합산
now— 현재 진행 중인 작업, 마지막으로 입력한 프롬프트 한 줄 표시
2. PROJECT
인터랙티브 파일 브라우저다.
▸ 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
- 디렉토리 트리 펼치기/접기
- Git 변경 파일 색상 표시 — 수정(노란색 M) / 추가(초록 A) / 삭제(빨강 D)
- 파일 선택 시 소스 코드 뷰어 (split 패널)
- 패키지 의존성 트리, API 엔드포인트 자동 감지
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)
기술 선택
Ink — React for CLI
터미널 UI 라이브러리를 고를 때 선택지가 몇 개 있었다. blessed, blessed-contrib... 근데 전부 API가 옛날 방식이고 컴포넌트 재사용이 불편하다.
Ink는 다르다. JSX를 쓴다. useState, useEffect를 그대로 쓴다. <Box flexDirection="column">이 flexbox처럼 동작한다. React를 아는 사람이면 거의 그대로 쓸 수 있다.
// 이게 진짜 터미널에 렌더링된다
<Box flexDirection="column" borderStyle="round" borderColor={theme.border}>
<Text color={theme.brand} bold>TOKENS</Text>
<Text color={theme.dim}>{fmtNum(inputTokens)} input</Text>
</Box>
세밀한 커서 제어나 마우스 이벤트는 못 하지만, 대시보드 용도로는 충분하다.
토큰 데이터 수집
Claude Code는 세션 데이터를 ~/.claude/projects/<hash>/sessions/ 아래에 JSONL 파일로 저장한다. 한 줄이 하나의 이벤트다.
{"type":"assistant","message":{"usage":{"input_tokens":4821,"output_tokens":312,"cache_read_input_tokens":38291}}}
이걸 파싱해서 컨텍스트 윈도우 사용량을 계산한다. chokidar로 파일 변경을 감시하면 실시간으로 업데이트된다.
멀티 세션 처리가 까다로웠다. 여러 프로젝트에서 동시에 Claude Code를 쓰면 세션 파일이 여러 개 생긴다. 현재 작업 디렉토리에 해당하는 세션만 필터링해야 했다.
Git 정보
simple-git 라이브러리로 브랜치, 변경 파일, 최근 커밋을 가져온다. 초기엔 동기적으로 읽었더니 입력 반응이 느려지는 문제가 있었다. git status가 대형 레포에서 1-2초 걸리는 경우가 있어 event loop를 블로킹했다.
// 블로킹 문제 발생
const status = git.statusSync(); // ❌
// 비동기로 전환
const status = await git.status(); // ✅
전부 비동기로 바꾸고 3초 폴링으로 전환해서 해결했다.
프로젝트 트리 스캔
fast-glob으로 파일을 스캔한다. 큰 프로젝트는 수만 개 파일이 있어서 처음엔 초기 렌더링이 느렸다. Progressive scan 패턴으로 해결했다.
// 1단계: depth-2 빠른 스캔 → 즉시 표시
const quickTree = await scanDepth(cwd, 2);
setTree(quickTree);
// 2단계: 백그라운드 풀 스캔
scanFull(cwd).then(fullTree => setTree(fullTree));
만들면서 막혔던 것들
Alternate Screen Buffer
처음엔 그냥 stdout에 그렸더니 스크롤이 밀려나갔다. vim이나 htop처럼 터미널을 완전히 점령하는 게 필요했다.
// 진입할 때
process.stdout.write('\x1b[?1049h\x1b[2J\x1b[H');
// 종료할 때
process.stdout.write('\x1b[?1049l');
1049h가 alternate screen buffer 진입, 1049l이 원래로 복귀다. SIGINT, SIGTERM도 잡아서 강제 종료해도 터미널이 깨지지 않게 처리했다.
한국어 키보드 입력
한글 IME가 활성화된 상태에서 q를 누르면 ㅂ이 들어와서 종료가 안 됐다. Ink의 useInput에서 받는 키값을 한글 자모 배열에 매핑해서 처리했다.
const KOREAN_MAP: Record<string, string> = {
'ㅂ': 'q', 'ㅈ': 'w', 'ㄷ': 'e',
'ㅇ': 'd', 'ㄱ': 'j', 'ㅎ': 'k',
};
useInput((input) => {
const key = KOREAN_MAP[input] ?? input;
if (key === 'q') { /* 종료 */ }
});
세션 전환 flicker
Claude Code에서 다른 프로젝트로 이동하면 세션이 바뀌면서 토큰 수치가 0으로 갔다가 다시 올라오는 현상이 있었다. debounce를 2초로 잡아서 세션 전환이 확정된 후에 상태를 업데이트하도록 해결했다.
설치
# 전역 설치 (권장)
npm install -g claude-code-hud
claude-hud
# 설치 없이 바로 실행
npx claude-code-hud
다음으로
앞으로 추가하고 싶은 것들:
- 토큰 예측 — 현재 속도로 컨텍스트가 언제 찰지 예측
- 비용 알림 — 세션 비용이 임계값 넘으면 경고
- 프로젝트 anatomy 자동 생성 — 파일별 한 줄 요약 export
- 최적화 모델 추천 - 작업별로 최적화된(토큰 최적화) 모델을 추천