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

claude-hud는 Claude Code 터미널 하단에 실시간 상태 정보를 표시하는 무료 오픈소스 플러그인입니다. GitHub 11,500+ 스타를 기록하며 Claude Code 플러그인 생태계에서 가장 높은 인지도를 확보하고 있습니다.

claude-hud란 무엇인가

Claude Code를 사용하면서 "지금 컨텍스트가 얼마나 남았지?", "이 에이전트가 뭘 하고 있는 거지?"라는 질문을 반복하게 됩니다. claude-hud는 이 문제를 해결하기 위해 만들어진 플러그인으로, 자동차 계기판처럼 코딩 중에 Claude Code의 모든 상태를 실시간으로 파악할 수 있게 해줍니다.

터미널 하단에 최대 4줄의 statusline을 표시합니다:

왜 claude-hud가 필요한가

Claude Code 기본 인터페이스에서는 다음을 알기 어렵습니다:

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

claude-hud는 tmux나 별도 모니터링 도구 없이 이 모든 정보를 터미널 하단에 항상 표시합니다.

기술 아키텍처 분석

핵심 기술 스택

Language: TypeScript 5 (ES2022, NodeNext)
Runtime: Node.js 18+ 또는 Bun
API: Claude Code 네이티브 Statusline API (v1.0.33+)
Pattern: 서브프로세스 (~300ms poll/exit cycle, 데몬 아님)

동작 방식

claude-hud의 가장 큰 기술적 특징은 데몬이 아닌 서브프로세스 방식이라는 점입니다. 약 300ms마다 호출/종료를 반복하여 시스템 리소스를 최소화합니다.

데이터 수집은 두 경로로 이루어집니다:

1. stdin JSON: 모델명, 토큰 사용량, rate limit 정보
2. 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    # TODO 진행률
    └── colors.ts        # 색상 유틸리티

설치 방법 (30초, 3줄)

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

# 2. 설치
/plugin install claude-hud

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

프리셋 비교

고급 설정

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

설정 파일: ~/.claude/plugins/claude-hud/config.json

경쟁 도구 벤치마크

claude-hud의 킬러 차별점: 에이전트 모니터링 + TODO 추적 + 압도적 커뮤니티

제작자와 커뮤니티

Jarrod Watts

• 현직: Cube Labs Director of Developer Relations (시드니)
• 전직: Polygon Labs DevRel Lead, thirdweb DevRel Engineer
• 경력: 7년 (Full-stack + Data + DevRel)

커뮤니티 반응

• AlphaSignal AI 뉴스레터 (28만+ 구독자) 소개
• awesome-claude-code 등재
• Claude Plugin Hub, Trendshift 등재
• 최근 커밋: 2026-03-23 (활발한 유지보수)

자주 묻는 질문 (FAQ)

Q: 성능에 영향이 있나요? 서브프로세스 방식이라 거의 없습니다. 300ms마다 호출/종료 반복으로 리소스 최소화.

Q: 어떤 버전부터 지원하나요? Claude Code v1.0.33+ (Statusline API 지원 버전).

Q: 커스텀 가능한가요? ~/.claude/plugins/claude-hud/config.json에서 색상, 임계값, 표시 항목 모두 조정 가능.

Q: tmux와 충돌하나요? 아니요. Claude Code 네이티브 API 사용으로 터미널 도구와 독립 동작.

결론

GitHub 11,500+ 스타. 무료 오픈소스(MIT). 설치 30초. Claude Code를 매일 사용하는 개발자라면 필수 플러그인입니다.

GitHub Repository | Documentation

참고 자료

• claude-hud GitHub
• claude-hud Docs (Mintlify)
• AlphaSignal AI Newsletter
• awesome-claude-code
• Jarrod Watts Twitter/X