Claude HUD: Claude Code에서 지금 무슨 일이 일어나는지 실시간으로 보는 플러그인

Claude Code를 쓰다 보면 이런 게 궁금합니다:

• “지금 컨텍스트가 얼마나 찼지?”
• “어떤 툴이 돌고 있지?”
• “서브에이전트가 뭐 하고 있지?”
• “할 일이 얼마나 남았지?”

Claude HUD는 이 모든 걸 항상 보이는 곳에 보여줍니다 — 입력창 아래에.

4,405개 이상의 스타를 받은 이 플러그인은 Claude Code의 “blind spots”를 해결합니다. 무슨 일이 일어나고 있는지 알려주지 않는 문제를 말이죠.

탄생 배경: “지금 뭐 하는 거야?”

Claude Code는 강력합니다. 하지만 사용자 경험에는 한 가지 큰 간극이 있습니다 — 가시성.

모델이 생각할 때, 우리는 기다립니다. 파일을 읽고 있을까요? 에이전트를 실행했나요? 컨텍스트가 얼마나 남았나요?

이 질문들에 대한 답을 얻으려면 보통 추측하거나, 로그를 뒤져야 했습니다.

jarrodwatts는 이 문제를 상태 표시줄(statusline) 로 해결했습니다. Claude Code의 네이티브 API를 활용해, 입력창 바로 아래에 실시간 정보를 표시하는 플러그인을 만들었습니다.

Claude HUD가 보여주는 것들

1. 프로젝트 경로

어떤 프로젝트에 있는지 한눈에 확인합니다. 디렉토리 레벨은 1~3단계까지 설정 가능합니다.

1 level:  [Opus] │ my-project git:(main)
2 levels: [Opus] │ apps/my-project git:(main)
3 levels: [Opus] │ dev/apps/my-project git:(main)

2. 컨텍스트 건강 상태

컨텍스트 윈도우가 얼마나 찼는지 정확히 알 수 있습니다. 시각적인 바(████░░░░░░)로 표시되어, 너무 늦기 전에 세션을 새로 시작할지 결정할 수 있습니다.

Context █████░░░░░ 45%

3. 툴 활동

Claude가 읽고, 편집하고, 검색하는 파일을 실시간으로 확인합니다.

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

4. 에이전트 추적

어떤 서브에이전트가 돌고 있는지, 무엇을 하고 있는지 보여줍니다.

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

5. Todo 진행률

작업 완료를 실시간으로 추적합니다.

▸ Fix authentication bug (2/5)

6. Usage 표시 (Pro/Max/Team)

사용량 제한을 한눈에 파악할 수 있습니다. 7일 사용량은 80% 이상일 때만 표시됩니다.

Usage ██░░░░░░░░ 25% (1h 30m / 5h)

실제 화면 예시

Claude HUD가 활성화되면 입력창 아래에 이런 정보가 표시됩니다:

[Opus | Max] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2    ← Tools activity
◐ explore [haiku]: Finding auth code (2m 15s) ← Agent status
▸ Fix authentication bug (2/5)              ← Todo progress

• 첫 번째 줄: 모델 이름, 프로젝트 경로, git 상태
• 두 번째 줄: 컨텍스트 사용량, API 사용량
• 세 번째 줄: 툴 활동 (읽기/편집/검색)
• 네 번째 줄: 서브에이전트 상태
• 다섯 번째 줄: Todo 진행률

설치 방법

Step 1: 마켓플레이스 추가

/plugin marketplace add jarrodwatts/claude-hud

Step 2: 플러그인 설치

/plugin install claude-hud

Linux 사용자 주의사항:

일부 Linux 시스템에서는 임시 디렉토리 문제가 발생할 수 있습니다. 다음과 같이 실행하세요:

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

Step 3: 상태 표시줄 설정

/claude-hud:setup

이제 Claude Code를 재시작하면 상태 표시줄이 나타납니다.

설정 옵션

대화형 설정

/claude-hud:configure

프리셋

설정 파일로 직접 수정

~/.claude/plugins/claude-hud/config.json에서 세부 설정을 변경할 수 있습니다.

주요 설정 옵션

Git 상태 표시 예시

1 level:       [Opus] │ my-project git:(main)
2 levels:      [Opus] │ apps/my-project git:(main)
3 levels:      [Opus] │ dev/apps/my-project git:(main)
With dirty:    [Opus] │ my-project git:(main*)
With ahead/behind: [Opus] │ my-project git:(main ↑2 ↓1)
With file stats:    [Opus] │ my-project git:(main* !3 +1 ?2)

아키텍처: 가볍고 네이티브

Claude HUD는 Claude Code의 네이티브 statusline API를 사용합니다.

• 별도 창 없음
• tmux 필요 없음
• 모든 터미널에서 작동
• stdin JSON → claude-hud → stdout 파이프라인
• transcript JSONL 파싱으로 툴/에이전트/todo 추적
• 약 300ms마다 업데이트

내부적으로는 transcript JSONL 파일을 파싱해서 툴 호출, 에이전트 실행, todo 상태를 추적합니다. 가볍고 빠릅니다.

요구사항

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

트러블슈팅

설정이 적용 안 됨

• JSON 구문 오류가 있는지 확인하세요
• 유효한 값인지 확인하세요
• config.json을 삭제하고 /claude-hud:configure를 다시 실행하세요

Git 상태 누락

• 현재 디렉토리가 git 저장소인지 확인하세요
• gitStatus.enabled가 false가 아닌지 확인하세요

툴/에이전트/todo 라인 누락

• 기본적으로 숨겨져 있습니다 — showTools, showAgents, showTodos를 활성화하세요
• 활동이 있을 때만 표시됩니다

마치며: “보이는 것은 제어할 수 있다”

Claude HUD는 단순한 플러그인이 아닙니다. Claude Code를 사용하는 방식을 바꿉니다.

컨텍스트가 얼마나 찼는지 알면, 세션을 언제 새로 시작할지 결정할 수 있습니다. 어떤 툴이 실행 중인지 알면, 작업 진행 상황을 파악할 수 있습니다. 서브에이전트가 뭘 하는지 알면, 병렬 작업을 더 잘 조율할 수 있습니다.

**“지금 뭐 하고 있지?”**라는 질문에 더 이상 추측으로 답할 필요가 없습니다. Claude HUD가 대답해 줍니다.

🔗 관련 정보

• GitHub: https://github.com/jarrodwatts/claude-hud
• Claude Code Docs: https://docs.anthropic.com/en/docs/claude-code
• npm: https://www.npmjs.com/package/claude-hud