claude-hud 가이드

Claude Code 터미널 하단에 모델명, 컨텍스트 사용량, API 사용량을 한눈에 보여주는 claude-hud 플러그인의 설치부터 설정, 트러블슈팅까지 전부 다룹니다.

이렇게 몇 % 썼는지 나오게하는 것.

클로드 코드 쓰다보면 항상 컨텍스트 얼마나 남았지? 지금까지 얼마나 대화했지?
claudh-hud만 있으면 언제 압축될지 모르는 채로 떨지 않아도 됨

---

claude-hud가 뭔데?

Claude Code를 쓰다 보면 이런 궁금증이 생긴다

• “지금 어떤 모델 쓰고 있지? Opus? Sonnet?”
• “컨텍스트 얼마나 썼지? 곧 압축되나?”
• “이번 주 API 사용량 얼마나 남았지?”

claude-hud는 이 정보들을 터미널 입력창 아래에 실시간으로 보여주는 플러그인이다.

[Opus 4.6 | Max] ████░░░░░░ 23% | 1% (4h 8m / 5h) | ⏱️ <1m
your/folder
2 MCPs

한 줄에 모델명, 플랜, 컨텍스트 바, 5시간/7일 사용량, 세션 시간까지 전부 보인다.

GitHub: https://github.com/jarrodwatts/claude-hud

---

설치하기

Step 1: 플러그인 설치

Claude Code 터미널에서:

/plugin install claude-hud

설치 후 Claude Code를 재시작한다.

Step 2: HUD 셋업

/claude-hud:setup

이 명령어가 자동으로:

1. 플러그인 경로를 찾고
2. 런타임(bun 또는 node)을 감지하고
3. ~/.claude/settings.json에 statusLine 설정을 추가한다

직접 설정하는 경우

/claude-hud:setup이 안 되면 수동으로 ~/.claude/settings.json에 추가:

bun 사용 시:

{
  "statusLine": {
    "type": "command",
    "command": "bash -c '\"/path/to/bun\" \"$(ls -td ~/.claude/plugins/cache/claude-hud/claude-hud/*/ 2>/dev/null | head -1)src/index.ts\"'"
  }
}

node 사용 시:

{
  "statusLine": {
    "type": "command",
    "command": "bash -c '\"/path/to/node\" \"$(ls -td ~/.claude/plugins/cache/claude-hud/claude-hud/*/ 2>/dev/null | head -1)dist/index.js\"'"
  }
}

Tip: bun은 TypeScript를 네이티브로 실행하므로 src/index.ts를, node는 컴파일된 dist/index.js를 사용한다. bun이 시작 속도도 더 빠르다.

런타임 경로 확인:

command -v bun   # bun 경로
command -v node  # node 경로

잘 되죠?

---