Claude HUD: Claude Code를 위한 실시간 상태 표시줄(Statusline) 플러그인

9bow · 1월 14, 2026, 9:30오전

Claude HUD 소개

Claude HUD는 Anthropic의 CLI 도구인 Claude Code 환경에서 실행되는 실시간 상태 표시줄(Statusline) 플러그인입니다. 터미널 하단에 항상 표시되며, 현재 AI 세션의 상태를 직관적으로 시각화해 줍니다.

최근 Claude Code와 같은 에이전트형 CLI 도구가 등장하면서, 개발자들은 터미널을 떠나지 않고 코딩 작업을 AI에게 위임하는 경우가 늘고 있습니다. 하지만 긴 세션을 유지하다 보면 컨텍스트 윈도우(기억 용량)가 얼마나 찼는지, 에이전트가 무한 루프에 빠진 것은 아닌지 파악해야 할 필요성이 커졌습니다. Claude HUD는 이러한 개발자의 니즈를 충족시키는 모니터링 도구입니다.

Claude HUD는 개발자가 터미널에서 AI 에이전트와 협업할 때 발생하는 "블랙박스" 문제를 해결합니다. 보통 AI에게 작업을 시키면 처리 중이라는 메시지만 뜨고 구체적으로 어떤 파일을 읽고 있는지, 토큰은 얼마나 썼는지 알기 어렵습니다. Claude HUD는 이러한 정보를 실시간으로 렌더링하여 투명성을 제공합니다.

Claude HUD 구조

Claude Code → stdin JSON → claude-hud → stdout → displayed in your terminal
           ↘ transcript JSONL (tools, agents, todos)

Claude HUD는 단순한 텍스트 출력이 아니라, Claude Code의 데이터 스트림을 가로채 분석하는 방식으로 작동합니다.

Input Stream: Claude Code로부터 JSON 형태의 데이터(모델 정보, 토큰 사용량 등)를 stdin으로 받습니다.
Transcript Parsing: 세션의 기록이 담긴 JSONL(Transcript) 파일을 실시간으로 파싱하여 도구 사용 내역, 에이전트 활동, Todo 항목을 추출합니다.
Rendering: 수집된 데이터를 바탕으로 터미널 제어 문자를 포함한 텍스트를 생성하여 stdout으로 내보내면, Claude Code가 이를 화면 하단에 렌더링합니다.
Tech Stack: TypeScript로 작성되었으며, Node.js 환경에서 동작합니다.

Claude HUD 제공 정보

Claude HUD는 터미널 하단에 여러 줄의 정보를 표시합니다. 각 줄은 세션의 특정 측면을 모니터링하며, 구체적인 구성 요소는 다음과 같습니다:

세션 정보 (Session Info)

가장 윗줄은 현재 AI 모델과 프로젝트 환경의 전반적인 상태를 요약하여 보여줍니다:

[Opus | Pro] █████░░░░░ 45% | my-project git:(main) | 2 CLAUDE.md | 5h: 25% | ⏱️ 5m

모델(Model): 현재 사용 중인 AI 모델을 가장 먼저 표시합니다. (예: Opus, Sonnet 등)
요금제Plan): 사용자의 구독 등급을 표시합니다. (예: Pro, Max, Team). 사용량 제한 기능이 활성화된 경우에만 보입니다.
컨텍스트 바(Context Bar): 현재 세션의 컨텍스트 윈도우(기억 용량) 사용량을 시각적인 게이지로 보여줍니다. 사용량이 늘어날수록 색상이 변합니다 (초록 → 노랑 → 빨강). 이 바가 빨간색에 가까워지면 /compact 명령어로 대화 내용을 정리해야 할 시점임을 알 수 있습니다.
프로젝트 경로(Project Path): 현재 작업 중인 디렉토리 경로를 표시합니다. 기본값은 1단계 깊이만 보여주지만, 설정에 따라 1~3단계까지 표시할 수 있습니다.
현재 브랜치(Git Branch): 현재 체크아웃된 Git 브랜치 이름을 표시합니다 (설정으로 끄고 켤 수 있음).
설정 파일 수(Config Counts): 현재 로드된 CLAUDE.md 파일, 규칙(Rules), MCP(Model Context Protocol) 서버, 훅(Hooks) 등의 개수를 요약해서 보여줍니다.
사용량 제한(Usage Limits): 5시간 동안의 메시지 전송량 제한(Rate Limit) 대비 현재 사용률을 퍼센트(%)로 표시합니다. (Pro/Max/Team 플랜 전용 옵트인 기능)
경과 시간(Duration): 현재 세션이 시작된 후 경과한 시간을 실시간으로 보여줍니다.

도구 활동 (Tool Activity)

Claude가 수행한 기술적인 작업 내역을 추적합니다. 아래 예시와 같이 도구 활동이 표시됩니다:

✓ TaskOutput ×2 | ✓ mcp_context7 ×1 | ✓ Glob ×1 | ✓ Skill ×1

Running Tools (실행 중): 현재 실행 중인 도구는 회전하는 스피너 아이콘과 함께 타겟 파일명이 표시되어, 멈춘 것이 아니라 작업 중임을 알려줍니다.
Completed Tools (완료됨): 이미 완료된 작업은 도구 유형별로 집계됩니다. 화면을 어지럽히지 않도록 동일한 도구 사용은 ×2, ×3과 같이 숫자로 묶어서 간결하게 보여줍니다.

에이전트 상태 (Agent Status)

메인 Claude 에이전트가 특정 작업을 위해 호출한 하위 에이전트(Sub-agent)의 활동을 보여줍니다:

✓ Explore: Explore home directory structure (5s)
✓ open-source-librarian: Research React hooks patterns (2s)

에이전트 종류 및 작업(Agent Type & Task): 현재 실행 중인 에이전트의 이름(예: Explore, open-source-librarian)과 해당 에이전트가 현재 수행 중인 구체적인 작업 내용을 텍스트로 표시합니다.
진행 시간(Elapsed Time): 각 에이전트가 해당 작업을 수행하는 데 걸린 시간(초 단위)을 보여주어, 특정 작업이 비정상적으로 오래 걸리는지 파악할 수 있습니다.

할 일 진행도 (Todo Progress)

Claude에게 맡긴 작업 목록(Todo)의 진행 상황을 보여줍니다:

✓ All todos complete (5/5)

현재 작업(Current Task): 현재 진행 중인 할 일 항목이나 전체 완료 상태를 텍스트로 표시합니다.
진행 개수(Progress Counter): 전체 할 일 개수 대비 완료된 개수를 (완료/전체) 형태로 표시하여 작업의 진척도를 직관적으로 알 수 있습니다.

Claude HUD 설치 및 사용 방법

Claude HUD 플러그인은 Claude Code (v1.0.80 이상)가 설치된 환경에서 작동합니다. Claude Code 세션 내부에서 다음 명령어들을 순차적으로 입력하여 설치합니다.

마켓플레이스 추가

먼저 플러그인 소스를 마켓플레이스에 등록합니다:

/plugin marketplace add jarrodwatts/claude-hud

플러그인 설치

등록된 소스에서 플러그인을 설치합니다:

/plugin install claude-hud

설정 초기화

설치 후 설정을 적용하면 즉시 하단에 HUD가 나타납니다. 재시작할 필요가 없습니다:

/claude-hud:setup

라이선스

Claude HUD 프로젝트는 MIT License로 공개 및 배포 되고 있습니다.

Claude HUD 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~