Claude HUD: AI 에이전트의 블랙박스를 투명하게 만든 플러그인

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

Claude Code로 복잡한 태스크를 돌려본 분이라면 공감하실 겁니다. 긴 작업이 돌아가는 동안 터미널은 조용하고, 컨텍스트가 언제 터질지, 에이전트가 루프에 빠진 건 아닌지 알 길이 없죠.

이 답답함을 정면으로 해결한 오픈소스 플러그인을 직접 써보고 공유합니다.

Claude HUD가 보여주는 것들

터미널 하단에 게임 스타일 상태바를 띄워주는 플러그인입니다. 네 가지를 실시간으로 추적합니다.

• 컨텍스트 사용량 - 시각적 바 + 퍼센티지로 세션의 컨텍스트 윈도우 소비량을 실시간 표시
• 실행 중인 도구 - Read, Edit, Bash 등 현재 어떤 도구가 작동 중인지 모니터링
• 서브에이전트 현황 - Task 호출로 생성된 하위 에이전트(Opus 4.5, Sonnet 등) 추적
• Todo 진행률 - Claude 내부 작업 목록의 완료 상황 시각화

기술적으로 어떻게 작동하나

상태바 뒤에서 무슨 일이 벌어지는지 궁금하신 분들을 위해 간단히 정리했습니다.

stdin 입력 처리

Claude Code가 JSON 페이로드로 세션 상태를 직접 전달합니다. 플러그인은 input_tokens, cache_creation_input_tokens, cache_read_input_tokens를 합산한 뒤 context_window_size로 나눠 사용률을 계산합니다.

트랜스크립트 파싱

세션 로그를 라인 단위 스트림으로 처리합니다. tool_use 블록을 감지하고 tool_result 항목과 매칭해서 각 도구의 상태를 running, completed, error로 추적합니다.

파일 경로 표시

파일 경로 표시도 꽤 영리하게 처리됩니다.

• Read, Write, Edit 도구 호출에서 file_path를 추출해 작업 중인 파일 표시
• 긴 경로는 .../filename.ts 형태로 자동 truncation
• 약 300ms 간격 갱신으로 거의 실시간 반영

개발자들이 열광하는 이유

커뮤니티 반응이 뜨거운 이유는 명확합니다. AI 에이전트 작업의 핵심 페인포인트를 정확히 겨냥했기 때문입니다.

• 불투명함 해소 - 긴 태스크가 막혀있는지, 루프 도는지, 컨텍스트 한계인지 알 수 없던 답답함을 해결
• 3줄 설치 - 복잡한 설정 없이 바로 적용 가능
• 디버깅 효율 극대화 - 멀티스텝 에이전트 워크플로우에서 어디서 문제가 생겼는지 즉시 파악 가능
• 시각적 피드백 - 게임 스타일 상태바가 vibe-coding 문화와 맞물려 AI 개발을 더 인터랙티브하게 만듦

커뮤니티에서 많은 공감을 얻은 댓글이 있었습니다. “드디어 Claude가 일하는지 멍 때리는지 알 수 있다.”

설치 방법

3줄이면 끝입니다.

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

GitHub: jarrodwatts/claude-hud

왜 중요한가

Claude Code를 자주 쓰시는 분이라면 한번 설치해보시길 추천합니다. 세션이 언제 터질지 모르는 불안감 없이 작업할 수 있고, 무엇보다 Claude가 지금 뭘 하고 있는지 눈으로 확인할 수 있다는 게 생각보다 큰 안정감을 줍니다.

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