Claude HUD: Claude Code 세션을 한눈에 보는 상태 표시줄

Claude Code를 쓸 때 궁금한 것들

Claude Code로 작업하다 보면 이런 생각이 든다:

• 컨텍스트를 얼마나 썼지? 곧 한계에 도달하나?
• 지금 무슨 도구를 실행 중이지? 파일을 읽고 있나, 편집 중인가?
• 서브에이전트가 돌고 있는데 얼마나 걸리고 있지?
• 할 일 목록에서 몇 번째까지 끝났지?

이 정보들을 터미널 하단에 항상 보여주는 플러그인이 Claude HUD다. GitHub Stars 18.7k로 Claude Code 플러그인 중 가장 인기가 많다.

뭘 보여주는가

Claude HUD는 터미널 입력창 바로 아래에 상태 표시줄을 추가한다.

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

기본 표시 항목

선택 표시 항목

설정으로 켤 수 있는 추가 정보:

도구 활동

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2

지금 Claude가 어떤 파일을 편집 중인지, 몇 번 읽기/검색을 했는지 실시간으로 보인다.

에이전트 상태

◐ explore [haiku]: Finding auth code (2m 15s)

서브에이전트가 돌고 있을 때 어떤 에이전트가 뭘 하고 있는지, 얼마나 걸렸는지 표시.

할 일 진행률

▸ Fix authentication bug (2/5)

TaskCreate로 만든 할 일 목록의 진행 상황.

왜 유용한가

1. 컨텍스트 관리

Claude Code는 대화가 길어지면 컨텍스트 윈도우가 차오른다. 가득 차면 이전 내용이 압축되면서 맥락을 잃을 수 있다. Context 바를 보면서 적절한 시점에 새 대화를 시작할 수 있다.

2. 대기 시간 활용

Claude가 뭘 하고 있는지 보이면, 기다릴지 다른 일을 할지 판단할 수 있다. “에이전트가 탐색 중이니 2분은 걸리겠군” 같은 판단이 가능해진다.

3. 사용량 추적

구독 사용자라면 주간 사용량 한도가 있다. Usage 바를 보면서 속도를 조절할 수 있다. 80% 이상이면 경고 표시도 된다.

설치

Claude Code 안에서 3줄이면 된다:

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/claude-hud:setup

setup에서 프리셋을 선택할 수 있다:

설치 후 Claude Code를 재시작하면 적용된다.

설정 커스터마이징

~/.claude/plugins/claude-hud/config.json에서 세부 조정이 가능하다:

{
  "language": "en",
  "lineLayout": "expanded",
  "pathLevels": 1,
  "gitStatus": { "enabled": true },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": false,
    "showMemoryUsage": false,
    "showCost": false
  }
}

레이아웃

• expanded: 여러 줄로 펼쳐서 표시 (정보 밀도 높음)
• compact: 한 줄로 압축 (화면 절약)

경로 깊이

pathLevels: 1 → my-project
pathLevels: 2 → apps/my-project
pathLevels: 3 → dev/apps/my-project

색상

named color(dim, red, green 등), 256-color 번호(0-255), hex 값(#rrggbb) 모두 지원한다.

동작 원리

Claude HUD는 Claude Code의 statusline API를 사용한다.

• Claude Code가 약 300ms 간격으로 세션 데이터를 JSON으로 전달
• HUD가 이를 파싱해서 컨텍스트 사용량, 토큰 속도 등을 계산
• transcript JSONL 파일을 읽어 도구 사용, 에이전트, 할 일 상태를 추출
• 포맷팅된 텍스트를 터미널 하단에 출력

별도 창이나 tmux 없이, Claude Code 터미널 자체에 통합된다.

요구사항

• Claude Code v1.0.80 이상
• Node.js 18+ 또는 Bun

마치며

Claude Code를 많이 쓸수록 “지금 뭘 하고 있는지"가 중요해진다. 특히 서브에이전트를 여러 개 띄우거나, 긴 작업을 시킬 때 HUD가 있으면 체감이 크게 다르다.

설치에 1분, 설정에 1분이면 되니까 한번 써보는 걸 추천한다.

GitHub: jarrodwatts/claude-hud