Claude Code를 쓰고 있다면, 지금 무슨 일이 일어나고 있는지 보이시나요?
Claude Code는 강력한 AI 코딩 도구이지만, 기본 터미널 환경은 텍스트 중심이라 내부에서 어떤 일이 진행 중인지 직관적으로 파악하기 어렵다는 한계가 있습니다.
이런 아쉬움을 해결해주는 플러그인이 바로 Claude HUD입니다.
이번 글에서는 Claude HUD가 무엇인지, 어떤 정보를 시각적으로 보여주는지, 그리고 어떻게 설치하고 활용할 수 있는지를 중심으로 정리해보겠습니다.
Claude HUD란 무엇인가?
Claude HUD는 Claude Code의 실행 상태를 실시간으로 시각화해주는 플러그인입니다.
Jarrod Watts가 개발한 이 플러그인은 기존의 밋밋한 터미널 환경에 **항상 보이는 시각적 레이어(HUD)**를 추가합니다.
입력창 아래에 항상 표시되며, 별도의 창이나 tmux 설정 없이 바로 동작하는 것이 특징입니다.
공식 설명 그대로 요약하면 다음과 같습니다.
“Claude HUD shows what's happening — context usage, active tools, running agents, and todo progress.”
즉, Claude Code 내부에서 일어나는 주요 활동을 한눈에 볼 수 있게 만들어주는 도구입니다.
Claude HUD의 핵심 특징
1. 컨텍스트(Context) 사용량 시각화
Claude HUD의 가장 인상적인 기능은 세션의 남은 컨텍스트 용량을 시각적으로 보여준다는 점입니다.
- 현재 컨텍스트 사용량을 막대 바로 표시
- 색상 변화로 상태를 직관적으로 파악
- 초록 → 노랑 → 빨강
- “아직 여유가 있는지”, “곧 한계에 도달하는지”를 즉시 확인 가능
컨텍스트 초과로 작업이 끊기는 상황을 사전에 예방할 수 있습니다.
2. 도구(Tools) 실행 상태 실시간 확인
Claude Code가 내부적으로 사용하는 도구들의 실행 상황도 HUD에서 바로 확인할 수 있습니다.
- 파일 읽기, 편집, 검색 등 도구 실행 상태 표시
- 실행 중인 도구는 스피너와 함께 표시
- 완료된 도구는 유형별로 집계
예를 들어, Claude가 어떤 파일을 읽고 있는지, 어떤 작업이 이미 끝났는지를 실시간으로 파악할 수 있습니다.
3. 서브 에이전트(Subagent) 모니터링
Claude HUD는 실행 중인 서브 에이전트 정보도 함께 보여줍니다.
- 어떤 에이전트가 실행 중인지
- 무엇을 작업하고 있는지
- 작업에 소요된 시간
예시:
- Explore: Explore home directory structure (5s)
- open-source-librarian: Research React hooks patterns (2s)
복잡한 작업을 여러 에이전트가 분담하는 상황에서 현재 진행 상태를 이해하는 데 큰 도움이 됩니다.
4. Todo 진행 상황 추적
Claude HUD는 Todo 기반 작업의 진행률도 표시합니다.
- 완료 여부
- 전체 대비 진행률 (예: 5/5)
- 모든 작업이 끝났는지 즉시 확인 가능
긴 작업 흐름에서도 현재 어디까지 왔는지를 놓치지 않게 해줍니다.
HUD에 표시되는 정보 구성 살펴보기
Claude HUD는 여러 줄로 구성된 상태 정보를 제공합니다.
Session Info 예시
[Opus 4.5] ████░░░░░░ 19% | 2 CLAUDE.md | 8 rules | 6 MCPs | 6 hooks | ⏱️ 1m
이 정보로 알 수 있는 내용은 다음과 같습니다.
- 현재 사용 중인 모델
- 컨텍스트 사용률
- 로드된 설정 수 (rules, MCPs, hooks)
- 세션 실행 시간
Tool Activity 예시
✓ TaskOutput ×2 | ✓ mcp_context7 ×1 | ✓ Glob ×1 | ✓ Skill ×1
- 완료된 도구들이 유형별로 집계되어 표시
- 실행 중일 경우 스피너로 상태 표현
Agent Status 예시
✓ Explore: Explore home directory structure (5s)
✓ open-source-librarian: Research React hooks patterns (2s)
- 에이전트 이름
- 수행 중인 작업
- 경과 시간
Todo Progress 예시
✓ All todos complete (5/5)
- 전체 작업 완료 여부를 즉시 확인 가능
Claude HUD는 어떻게 동작할까?
Claude HUD는 Claude Code의 native statusline API를 활용합니다.
동작 구조는 다음과 같습니다.
Claude Code → stdin JSON → claude-hud → stdout → 터미널 표시
↘ transcript JSONL (tools, agents, todos)
주요 동작 방식은 다음과 같습니다.
- Claude Code가 제공하는 실제 토큰 데이터 사용
- 실행 로그(transcript)를 파싱해 도구/에이전트 상태 분석
- 약 300ms 주기로 HUD 업데이트
- 별도 창 없이 터미널에서 바로 표시
사용을 위한 요구 사항
Claude HUD를 사용하기 위해 필요한 환경은 다음과 같습니다.
- Claude Code v1.0.80 이상
- Node.js 18 이상 또는 Bun
Claude HUD가 주는 의미와 기대 효과
Claude HUD는 단순한 시각적 장식이 아니라, Claude Code의 내부 동작을 투명하게 보여주는 도구입니다.
- 컨텍스트 관리 실패를 예방하고
- 도구 및 에이전트 실행 흐름을 이해하며
- 작업 진행 상황을 실시간으로 파악할 수 있습니다.
Claude Code를 더 깊이 활용하고 있다면,
“지금 Claude가 무엇을 하고 있는지”를 알고 싶은 순간이 반드시 옵니다.
Claude HUD는 바로 그 궁금증을 해결해주는 플러그인이라고 볼 수 있습니다.
https://github.com/jarrodwatts/claude-hud
GitHub - jarrodwatts/claude-hud: A Claude Code plugin that shows what's happening - context usage, active tools, running agents,
A Claude Code plugin that shows what's happening - context usage, active tools, running agents, and todo progress - jarrodwatts/claude-hud
github.com
'인공지능' 카테고리의 다른 글
| Adala란 무엇인가? 자율 학습 기반 데이터 라벨링 에이전트 프레임워크 완전 정리 (0) | 2026.01.04 |
|---|---|
| Oh My OpenCode란 무엇인가? - 에이전트 시대를 여는 AI 개발 오케스트레이션 플랫폼 정리 (0) | 2026.01.04 |
| 알리바바가 전면 공개한 멀티 에이전트 프레임워크, AgentScope란 무엇인가? (0) | 2026.01.04 |
| GraphRAG란 무엇인가? DIGIMON 프로젝트로 이해하는 그래프 기반 RAG 구조와 활용 방법 (0) | 2026.01.03 |
| 대규모 언어 모델 학습에서 하이퍼파라미터 튜닝 비용을 줄이는 방법 - Complete(d)P가 제안하는 확장된 하이퍼파라미터 전이 전략 (0) | 2026.01.03 |
