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


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

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

## claude-hud란 무엇인가

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

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

| 라인 | 표시 내용 | 상세 |
|------|----------|------|
| Line 1 (Session) | 모델명, 프로젝트 경로, Git 브랜치 | 현재 세션 기본 정보 |
| Line 2 (Context) | 컨텍스트 바 + Rate Limit | 초록(0-69%) / 노랑(70-84%) / 빨강(85%+) |
| Line 3 (Tools) | 실행 중인 도구 목록 | Read, Bash, Write 등 실시간 표시 |
| Line 4 (Agents) | 서브에이전트 + TODO 진행률 | running/waiting/done + N/M |

## 왜 claude-hud가 필요한가

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

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

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

## 기술 아키텍처 분석

### 핵심 기술 스택

```text
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**: 도구 호출, 에이전트 활동 로그

### 소스 코드 구조

```text
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줄)

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

# 2. 설치
/plugin install claude-hud

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

### 프리셋 비교

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

### 고급 설정

```json
{
  "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`

## 경쟁 도구 벤치마크

| 도구 | 언어 | GitHub Stars | 에이전트 추적 | TODO 추적 | 설치 난이도 |
|------|------|-------------|-------------|----------|-----------|
| **claude-hud** | TypeScript | **11,500+** | O | O | 3단계 (30초) |
| CCometixLine | Rust | 1,300 | X | X | TUI 설정 필요 |
| claude-powerline | - | - | X | X | vim-style |
| ccstatusline | React/Ink | - | X | X | 높은 커스터마이징 |
| claudia-statusline | Rust | - | X | O | 클라우드 동기화 |

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](https://github.com/jarrodwatts/claude-hud) | [Documentation](https://docs.claude-hud.dev)

## 참고 자료

- [claude-hud GitHub](https://github.com/jarrodwatts/claude-hud)
- [claude-hud Docs (Mintlify)](https://docs.claude-hud.dev)
- [AlphaSignal AI Newsletter](https://alphasignal.ai)
- [awesome-claude-code](https://github.com/langgptai/awesome-claude-code)
- [Jarrod Watts Twitter/X](https://x.com/jarrodwattsdev)