claude-hud: Claude Code 실시간 모니터링 플러그인 완벽 가이드

claude-hud는 Claude Code 터미널 하단에 실시간 상태 정보를 표시하는 무료 플러그인입니다. 자동차 계기판처럼 컨텍스트 잔량, 실행 중인 도구, 에이전트 상태를 한눈에 보여줍니다.

Claude Code를 사용하다 보면 "지금 컨텍스트가 얼마나 남았지?", "이 에이전트가 뭘 하고 있는 거지?"라는 질문이 반복됩니다. claude-hud는 이 문제를 해결하기 위해 만들어진 Claude Code 전용 실시간 모니터링 플러그인으로, GitHub에서 11,500개 이상의 스타를 받으며 커뮤니티의 압도적 지지를 얻고 있습니다.

claude-hud란 무엇인가

claude-hud는 Claude Code 터미널 하단에 최대 4줄의 statusline을 표시하는 플러그인입니다. Jarrod Watts가 개발했으며, Claude Code의 네이티브 Statusline API를 활용합니다.

비유하자면 자동차 계기판과 같습니다. 운전 중에 연료 잔량(컨텍스트), 엔진 상태(도구 실행), 내비게이션 진행률(TODO)을 한눈에 확인하듯, 코딩 중에 Claude Code의 모든 상태를 실시간으로 파악할 수 있습니다.

4줄 상태바가 보여주는 정보

라인	표시 내용	상세
Line 1 (Session)	모델명, 프로젝트 경로, Git 브랜치	현재 세션의 기본 정보
Line 2 (Context)	컨텍스트 바 + Rate Limit	70% 미만 초록, 70-85% 노랑, 85% 이상 빨강
Line 3 (Tools)	현재 실행 중인 도구 목록	파일 읽기, 명령 실행 등 실시간 표시
Line 4 (Agents/TODOs)	서브에이전트 상태 + TODO 진행률	에이전트 팀 모니터링

특히 Line 2의 컨텍스트 바는 직관적인 색상 코드로 현재 상황을 즉시 알려줍니다. 초록색이면 여유, 노란색이면 주의, 빨간색이면 새 세션을 고려해야 할 때입니다.

왜 claude-hud가 필요한가

Claude Code의 가장 큰 불편함 중 하나는 상태 가시성의 부재입니다. 기본 인터페이스에서는 다음을 알기 어렵습니다.

컨텍스트 소진 시점: 대화가 길어지면 갑자기 응답 품질이 떨어지는데, 원인을 바로 파악하기 어렵습니다
도구 실행 상태: Claude가 파일을 읽고 있는지, 명령을 실행하고 있는지 보이지 않습니다
에이전트 진행률: 서브에이전트가 여러 개 돌아갈 때 각각의 상태를 추적하기 어렵습니다
Rate Limit 접근: API 속도 제한에 가까워지고 있는지 미리 알 수 없습니다

claude-hud는 이 모든 정보를 터미널 하단에 항상 표시합니다. tmux나 별도 모니터링 도구 없이, 플러그인 하나로 해결됩니다.

기술 아키텍처

claude-hud의 내부 구조를 이해하면 왜 가볍고 안정적인지 알 수 있습니다.

핵심 기술 스택

언어: TypeScript 5 (ES2022, NodeNext)
런타임: Node.js 18+ 또는 Bun
API: Claude Code 네이티브 Statusline API (v1.0.33+)
패턴: 서브프로세스 (데몬 없음)

동작 방식

claude-hud는 데몬(상주 프로세스)이 아닙니다. 약 300ms마다 호출/종료를 반복하는 서브프로세스 방식으로 동작합니다. 이 설계 덕분에 시스템 리소스를 거의 사용하지 않습니다.

데이터는 두 가지 경로로 수집됩니다.

stdin JSON: 모델명, 토큰 사용량, rate limit 정보
transcript JSONL: 도구 호출, 에이전트 활동 로그

소스 코드 구조

src/
├── index.ts          # 엔트리포인트
├── stdin.ts          # JSON 파서 (모델, 토큰, rate limit)
├── transcript.ts     # JSONL 파서 (도구/에이전트 활동)
├── config-reader.ts  # 설정 파일 로드
├── types.ts          # 타입 정의
└── render/           # 렌더링 모듈
    ├── session-line.ts
    ├── tools-line.ts
    ├── agents-line.ts
    ├── todos-line.ts
    └── colors.ts

설치 방법 (30초)

claude-hud 설치는 3줄이면 완료됩니다.

# 1. 마켓플레이스에서 플러그인 추가
/plugin marketplace add jarrodwatts/claude-hud

# 2. 플러그인 설치
/plugin install claude-hud

# 3. 초기 설정 실행
/claude-hud:setup

프리셋 선택

설치 시 3가지 프리셋 중 하나를 선택할 수 있습니다.

프리셋	표시 줄 수	표시 내용	추천 대상
Full	4줄	세션 + 컨텍스트 + 도구 + 에이전트	에이전트를 많이 사용하는 파워 유저
Essential	2줄	컨텍스트 + 도구	일반 개발자 (추천)
Minimal	1줄	컨텍스트만	미니멀한 터미널 선호

고급 설정

프리셋 이후 세부 설정은 ~/.claude/plugins/claude-hud/config.json에서 조정합니다.

{
  "preset": "full",
  "colors": {
    "context_safe": "green",
    "context_warning": "yellow",
    "context_danger": "red"
  },
  "thresholds": {
    "context_warning": 70,
    "context_danger": 85
  }
}

플랫폼별 참고사항

macOS/Linux: 별도 설정 없이 바로 사용 가능
Linux: /tmp가 별도 파일시스템인 경우 TMPDIR 환경변수 설정 필요
Windows: Node.js LTS 설치 필요 (winget install OpenJS.NodeJS.LTS)

제작자: Jarrod Watts

claude-hud를 만든 Jarrod Watts는 시드니에 기반을 둔 개발자 릴레이션(DevRel) 전문가입니다.

현직: Cube Labs Director of Developer Relations
전직: Polygon Labs (DevRel Lead), thirdweb (DevRel Engineer), Quantium (데이터 엔지니어)
학력: UTS 정보기술 학사 (Cooperative Scholarship, 2019)
경력: 7년 (Full-stack + Data + DevRel)

Web3 DevRel에서 AI 개발자 도구 생태계로 영역을 확장하며, claude-hud를 통해 Claude Code 플러그인 생태계에서 가장 높은 인지도를 확보했습니다.

커뮤니티 반응과 생태계 위치

claude-hud는 Claude Code 플러그인 중 가장 많은 관심을 받고 있습니다.

GitHub Stars: 11,500+ (2026년 3월 기준)
Forks: 488+
최근 커밋: 2026-03-23 (활발한 유지보수)
AlphaSignal AI 뉴스레터 (28만+ 구독자) 소개
awesome-claude-code 등재
Claude Plugin Hub, Trendshift 등재

커뮤니티에서 자주 언급되는 긍정적 반응은 다음과 같습니다.

"컨텍스트 바만으로도 플러그인 가치가 충분하다"
"Claude가 지금 뭘 하는지 투명하게 보여줘서 안심이 된다"
"설치가 3단계라 진입장벽이 없다"
"tmux 설정 없이 상태 모니터링이 가능하다"

경쟁 도구 비교

claude-hud 외에도 여러 statusline 도구가 있습니다.

도구	언어	GitHub Stars	핵심 차별점
claude-hud	TypeScript	~11,500	에이전트/TODO 추적, 3단계 설치, 최대 커뮤니티
CCometixLine	Rust	~1,300	고성능, TUI 기반 설정
claude-powerline	-	-	vim-style 테마 지원
ccstatusline	React/Ink	-	높은 커스터마이징
claudia-statusline	Rust	-	영구 통계, 클라우드 동기화

claude-hud의 가장 큰 차별점은 에이전트 모니터링과 TODO 추적 기능입니다. Agent Teams를 사용하는 환경에서는 이 기능이 특히 유용합니다. 설치 편의성(3단계)과 압도적인 커뮤니티 규모(11,500 vs 1,300)도 선택의 중요한 요소입니다.

최근 업데이트

claude-hud는 활발하게 유지보수되고 있으며, 최근 주요 변경사항은 다음과 같습니다.

Usage API 타임아웃 오버라이드 (CLAUDE_HUD_USAGE_TIMEOUT_MS 환경변수)
Windows 셋업 프로세스 수정
Bedrock 모델 라벨 정규화
프록시/OAuth 안정성 개선
토큰 갱신 시 사용량 데이터 유지

자주 묻는 질문 (FAQ)

Q: claude-hud를 설치하면 Claude Code 성능에 영향이 있나요? A: 거의 없습니다. 데몬이 아닌 서브프로세스 방식으로 동작하며, 약 300ms마다 호출/종료를 반복하기 때문에 리소스 사용이 최소화됩니다.

Q: 어떤 Claude Code 버전부터 지원하나요? A: Claude Code v1.0.33 이상에서 Statusline API를 지원합니다. 이 버전 미만이면 플러그인이 동작하지 않으니 먼저 업데이트하세요.

Q: 색상이나 표시 항목을 커스텀할 수 있나요? A: 네. ~/.claude/plugins/claude-hud/config.json 파일에서 색상, 임계값, 표시 요소를 세부적으로 조정할 수 있습니다.

Q: tmux나 다른 터미널 멀티플렉서와 충돌하나요? A: 충돌 없이 함께 사용할 수 있습니다. claude-hud는 Claude Code의 네이티브 API를 사용하므로 터미널 레벨의 도구와는 독립적으로 동작합니다.

Q: 무료인가요? A: 네, 완전 무료 오픈소스입니다. MIT 라이선스로 배포됩니다.

마무리: 누가 써야 하나

claude-hud는 Claude Code를 일상적으로 사용하는 모든 개발자에게 추천합니다. 특히 에이전트를 여러 개 동시에 운영하거나, 컨텍스트 한도를 자주 경험하는 파워 유저라면 필수 플러그인이라 할 수 있습니다.

설치 30초. 무료. GitHub 11,500+ 스타. 후회할 이유가 없습니다.

claude-hud GitHub 저장소에서 바로 시작해보세요.

claude-hud: Claude Code 실시간 모니터링 플러그인 완벽 가이드

claude-hud: Claude Code 실시간 모니터링 플러그인 완벽 가이드

claude-hud란 무엇인가

4줄 상태바가 보여주는 정보

왜 claude-hud가 필요한가

기술 아키텍처

핵심 기술 스택

동작 방식

소스 코드 구조

설치 방법 (30초)

프리셋 선택

고급 설정

플랫폼별 참고사항

제작자: Jarrod Watts

커뮤니티 반응과 생태계 위치

경쟁 도구 비교

최근 업데이트

자주 묻는 질문 (FAQ)

마무리: 누가 써야 하나

참고 자료

댓글 (0)

관련 글

댓글 (0)

관련 글