Claude HUD: Claude Code의 블랙박스를 투명하게 만드는 플러그인

Claude HUD: Claude Code의 블랙박스를 투명하게 만드는 플러그인

"Claude가 일하는 건지, 멍 때리는 건지 모르겠다."

Claude Code로 복잡한 작업을 돌려본 개발자라면 공감할 겁니다. 긴 작업이 돌아가는 동안 터미널은 조용하고, 컨텍스트가 언제 소진될지, 에이전트가 루프에 빠진 건 아닌지 알 수가 없습니다.

Claude HUD는 이 답답함을 정면으로 해결한 오픈소스 플러그인입니다.

---

Claude HUD란?

Claude HUD는 Jarrod Watts가 개발한 Claude Code 플러그인으로, 터미널 입력창 바로 아래에 항상 보이는 실시간 상태바(HUD)를 추가합니다. 별도의 창이나 tmux 설정 없이 동작하는 것이 특징입니다.

---

HUD가 보여주는 것들

HUD는 아래 4가지 정보를 약 300ms 간격으로 실시간 갱신합니다.

항목	설명
컨텍스트 사용량	막대 바 + 퍼센티지, 색상(초록→노랑→빨강)으로 직관적 표시
도구 실행 상태	Read, Edit, Bash, Glob 등 실행 중/완료된 도구 집계
서브에이전트 현황	Task 호출로 생성된 하위 에이전트 이름, 작업 내용, 경과 시간
Todo 진행률	Claude 내부 작업 목록 완료 상황 실시간 시각화

실제 HUD 출력 예시

Session: 📁 my-project | [Opus 4.5] ████░░░░░░ 19% | 2 CLAUDE.md | 8 rules | 6 MCPs | 6 hooks | ⏱️ 1m
Tools:   ✓ TaskOutput ×2 | ✓ mcp_context7 ×1 | ✓ Glob ×1 | ✓ Skill ×1
Agents:  ✓ Explore: Explore home directory structure (5s)
Todos:   ✓ All todos complete (5/5)

---

사전 요구사항

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

---

설치 방법

Project scope vs User scope

Claude HUD는 팀 전체가 아닌 개인 개발 편의 도구이므로, User scope로 설치하는 것을 권장합니다.

Scope	저장 경로	Git 커밋 여부
User (권장)	~/.claude/	❌ 커밋되지 않음
Project	./.claude/	✅ 팀 전체에 적용

Project scope로 설치하면 .claude/settings.json에 기록되어 저장소에 커밋되고 팀원 모두에게 강제 적용됩니다. 개인 도구는 User scope로 설치해 저장소를 깔끔하게 유지하세요.

Claude Code 내부에서 설치 (권장)

Claude Code 터미널 안에서 아래 3개 명령어를 순서대로 실행합니다.

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

기본값이 User scope이므로 별도 플래그 없이 실행하면 ~/.claude/에 설치됩니다.

일반 쉘에서 scope 명시 설치

Claude Code 밖(일반 터미널)에서 --scope user를 명시할 수도 있습니다.

claude plugin install claude-hud@jarrodwatts-claude-hud --scope user

---

동작 원리

Claude Code → stdin JSON → claude-hud → stdout → 터미널 표시
           ↘ transcript JSONL (tools, agents, todos)

• Claude Code가 native statusline API로 세션 상태를 JSON 페이로드로 전달
• input_tokens + cache_creation_input_tokens + cache_read_input_tokens ÷ context_window_size로 컨텍스트 사용률 계산
• 세션 로그(transcript JSONL)를 라인 단위로 스트리밍해 tool_use 블록을 감지하고 tool_result와 매칭 → running / completed / error 상태 추적
• 파일 경로가 긴 경우 .../filename.ts 형태로 자동 truncation

---

기대 효과

• 컨텍스트 초과 사전 예방 — 색상 변화로 한계 도달 전에 인지
• 디버깅 효율 향상 — 멀티스텝 에이전트 워크플로우에서 어디서 문제가 생겼는지 즉시 파악
• 작업 투명성 확보 — 에이전트가 루프에 빠졌는지, 실제로 일하는지 눈으로 확인 가능

옵저버빌리티(Observability)는 서버와 파이프라인만의 것이 아닙니다. AI 에이전트에도 필요합니다.

---

참고 링크

• GitHub: jarrodwatts/claude-hud
• Claude Code 공식 문서: Discover Plugins

---

위 마크다운을 그대로 복사하시면 됩니다. 블로그 플랫폼(Tistory, Velog, Notion 등)에 따라 코드 블록 렌더링 방식이 다를 수 있으니, 미리보기로 한 번 확인하시는 걸 권장합니다.[1]

출처
[1] GitHub - jarrodwatts/claude-hud: A Claude Code plugin that shows ... https://github.com/jarrodwatts/claude-hud