KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #ai #dsh-plugin #ai-agent #mcp #deepseek-harness #windows

claude-hud

★ 27,426 Open GitHub ↗

컨텍스트 사용량, 활성 도구, 실행 중인 에이전트 및 할 일(todo) 진행 상황을 시각적으로 보여주는 Claude Code 플러그인입니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Claude HUD

컨텍스트 사용량, 활성 도구, 실행 중인 에이전트 및 할 일 진행 상황을 보여주는 Claude Code 플러그인입니다. 입력창 하단에 항상 표시됩니다.

[![License](https://img.shields.io/github/license/jarrodwatts/claude-hud?v=2)](https://raw.githubusercontent.com/jarrodwatts/claude-hud/main/LICENSE)
[![Stars](https://img.shields.io/github/stars/jarrodwatts/claude-hud)](https://github.com/jarrodwatts/claude-hud/stargazers)

![Claude HUD in action](https://raw.githubusercontent.com/jarrodwatts/claude-hud/main/claude-hud-preview-5-2.png)

> 🌐 English | [中文文档](README.zh.md)

## 설치

Claude Code 인스턴스 내부에서 다음 명령어를 실행하세요:

**1단계: 마켓플레이스 추가**
```
/plugin marketplace add jarrodwatts/claude-hud
```

**2단계: 플러그인 설치**

<details>
<summary>⚠️ Linux 사용자: 설치 중 EXDEV 오류가 발생하는 경우 클릭하세요</summary>

이전 Claude Code 버전에서는 `/tmp`가 별도의 파일 시스템(tmpfs)인 경우 다음과 같은 오류와 함께 플러그인 설치가 실패할 수 있습니다:
```
EXDEV: cross-device link not permitted
```

이 [Claude Code 버그](https://github.com/anthropics/claude-code/issues/14799)는 현재 수정되었습니다. 이 오류가 발생한다면 먼저 Claude Code를 업데이트하세요. 업데이트할 수 없는 경우, 설치 전에 TMPDIR을 설정하세요:
```bash
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
```

그 후 해당 세션에서 아래 설치 명령어를 실행하세요.

</details>

```
/plugin install claude-hud
```

설치 후 플러그인을 다시 로드하세요 (재시작은 필요 없습니다):

```
/reload-plugins
```

<details>
<summary>터미널 사용을 선호하시나요?</summary>

1~2단계는 Claude Code CLI를 사용하여 세션 외부에서도 수행할 수 있습니다:
```bash
claude plugin marketplace add jarrodwatts/claude-hud
claude plugin install claude-hud@claude-hud
```
그 후 세션 내부에서 `/reload-plugins`를 실행하세요 (또는 새 세션을 시작하세요).

</details>

**3단계: 상태 표시줄 설정**
```
/claude-hud:setup
```

<details>
<summary>⚠️ Windows 사용자: 설정 중 JavaScript 런타임을 찾을 수 없다고 나오는 경우 클릭하세요</summary>

Windows에서는 Node.js LTS가 Claude HUD 설정의 지원 런타임입니다. JavaScript 런타임을 찾을 수 없다는 메시지가 나오면, 먼저 셸에 Node.js를 설치하세요:
```powershell
winget install OpenJS.NodeJS.LTS
```
그 후 셸을 재시작하고 `/claude-hud:setup`을 다시 실행하세요.

</details>

완료되었습니다! Claude Code는 설정을 자동으로 다시 로드하며, 다음 메시지를 보낸 후 HUD가 나타납니다 (재시작 필요 없음). 만약 나타나지 않는다면 Claude Code를 재시작하세요 (이전 버전의 경우 statusLine 변경 사항을 적용하려면 재시작이 필요합니다).

---

## Claude HUD란 무엇인가요?

Claude HUD는 Claude Code 세션에서 어떤 일이 일어나고 있는지 더 자세한 통찰력을 제공합니다.

| 표시 항목 | 중요한 이유 |
|--------------|----------------|
| **프로젝트 경로** | 현재 어떤 프로젝트에 있는지 확인 (디렉토리 레벨 1~3단계 설정 가능) |
| **컨텍스트 상태** | 컨텍스트 윈도우가 얼마나 찼는지 정확하게 파악하여 한계 도달 전 대비 가능 |
| **도구 활동** | Claude가 파일을 읽고, 수정하고, 검색하는 과정을 실시간으로 확인 |
| **에이전트 추적** | 어떤 서브에이전트가 실행 중이며 무엇을 하고 있는지 확인 |
| **할 일 진행 상황** | 작업 완료 상태를 실시간으로 추적 |

## 표시 내용

### 기본 설정 (2줄)
```
[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
```
- **첫 번째 줄** — 모델, 식별된 제공자 레이블 (예: `Bedrock`, `Vertex`), 프로젝트 경로, git 브랜치
- **두 번째 줄** — 컨텍스트 바 (초록 → 노랑 → 빨강) 및 사용량 제한(rate limits)

### 선택적 표시 줄 (`/claude-hud:configure`를 통해 활성화)
```
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← 도구 활동
◐ explore [haiku]: Finding auth code (2m 15s)    ← 에이전트 상태
▸ Fix authentication bug (2/5)                   ← 할 일 진행 상황
```

---

## 작동 원리

Claude HUD는 Claude Code의 네이티브 **statusline API**를 사용합니다. 별도의 창이나 tmux가 필요 없으며 모든 터미널에서 작동합니다.

```
Claude Code → stdin JSON → claude-hud → stdout → 터미널에 표시
           ↘ transcript JSONL (도구, 에이전트, 할 일)
```

**주요 특징:**
- Claude Code의 네이티브 토큰 데이터 사용 (추정치 아님)
- 최신 1M 컨텍스트 세션을 포함하여 Claude Code가 보고하는 컨텍스트 윈도우 크기에 따라 조정됨
- 트랜스크립트를 분석하여 도구/에이전트 활동 파악
- 매 상호작용 후(새 어시스턴트 메시지, `/compact`, 권한 변경, vim-mode 전환 등) 300ms 디바운싱 간격으로 다시 렌더링

---

## 설정

언제든지 HUD를 사용자 정의할 수 있습니다:

```
/claude-hud:configure
```

안내 절차를 통해 레이아웃, 언어 및 일반적인 표시 설정을 관리할 수 있습니다. 사용자 정의 색상이나 임계값 같은 고급 설정은 유지되지만, 이는 설정 파일을 직접 편집하여 설정해야 합니다:

- **최초 설정**: 프리셋(Full/Essential/Minimal) 선택, 레이블 언어 선택 후 개별 요소 세부 조정
- **언제든지 사용자 정의**: 항목 켜기/끄기, git 표시 스타일 조정, 레이아웃 변경 또는 레이블 언어 변경
- **저장 전 미리보기**: 변경 사항을 적용하기 전 HUD가 어떻게 보일지 정확히 확인

### 프리셋

| 프리셋 | 표시 항목 |
|--------|--------------|
| **Full** | 모든 항목 활성화 — 도구, 에이전트, 할 일, git, 사용량, 소요 시간 |
| **Essential** | 활동 줄 + git 상태, 최소한의 정보 clutter |
| **Minimal** | 핵심 정보만 — 모델 이름과 컨텍스트 바 |

프리셋을 선택한 후 개별 요소를 켜거나 끌 수 있습니다.

### 수동 설정

`~/.claude/plugins/claude-hud/config.json` 파일을 직접 편집하여 `colors.*`, `pathLevels`, `maxWidth`, 임계값 오버라이드, `display.timeFormat`, `display.promptCacheTtlSeconds` 등의 고급 설정을 변경할 수 있습니다. `/claude-hud:configure`를 실행해도 이러한 수동 설정은 유지되며 `language`, 레이아웃 및 일반 안내 설정만 변경할 수 있습니다.

간체 및 번체 중국어 HUD 레이블을 선택적으로 사용할 수 있습니다. `/claude-hud:configure`에서 중국어 로캘을 선택하거나 설정에서 `language`를 지정하지 않으면 기본값은 영어입니다. `zh` 별칭은 간체 중국어로, `zh-TW`는 번체 중국어로 매핑됩니다. 안내 설정은 표준 값인 `zh-Hans` 또는 `zh-Hant`를 기록합니다.

### 옵션

| 옵션 | 타입 | 기본값 | 설명 |
|--------|------|---------|-------------|
| `language` | `en` \| `zh` \| `zh-Hans` \| `zh-Hant` \| `zh-TW` | `en` | HUD 레이블 언어. 간체는 `zh` 또는 `zh-Hans`, 번체는 `zh-Hant` 또는 `zh-TW` 사용. |
| `lineLayout` | string | `expanded` | 레이아웃: `expanded` (여러 줄) 또는 `compact` (한 줄) |
| `pathLevels` | 1-3 \| `full` | 1 | 프로젝트 경로에 표시할 디렉토리 레벨, `full`은 전체 절대 경로 표시 |
| `maxWidth` | number \| `null` | `null` | 터미널 너비 감지가 완전히 실패했을 때만 사용되는 선택적 대체 너비 |
| `forceMaxWidth` | boolean | false | 터미널 너비 감지 값이 더 작더라도 `maxWidth`가 설정되어 있으면 항상 사용 |
| `elementOrder` | string[] | `["project","addedDirs","context","usage","promptCache","memory","environment","tools","skills","mcp","agents","todos","sessionTime"]` | 확장 모드 요소 순서. 제외된 항목은 표시되지 않습니다. |
| `projectLineOrder` | string[] | `[]` | 두 레이아웃 모두에서 첫 번째 줄 *내부* 세그먼트의 선택적 선행 순서. `model`은 제공자+모델+노력을 포함하며, `project`는 경로+추가 디렉토리+git을 하나의 세그먼트로 포함합니다. 예: `["project","model"]`은 프로젝트/git 블록을 모델 배지 앞에 배치합니다. |
| `display.mergeGroups` | string[][] | `[["context","usage"]]` | 확장 모드에서 인접할 때 한 줄을 공유해야 하는 그룹. `[]`로 설정하면 병합 줄 비활성화. |
| `gitStatus.enabled` | boolean | true | HUD에 git 브랜치 표시 |
| `gitStatus.showDirty` | boolean | true | 커밋되지 않은 변경 사항이 있을 때 `*` 표시 |
| `gitStatus.showAheadBehind` | boolean | false | 원격 대비 ahead/behind 상태를 `↑N ↓N`으로 표시 |
| `gitStatus.pushWarningThreshold` | number | 0 | 푸시되지 않은 커밋 수가 이 값 이상일 때 경고 색상으로 표시 (`0`은 비활성화) |
| `gitStatus.pushCriticalThreshold` | number | 0 | 푸시되지 않은 커밋 수가 이 값 이상일 때 심각 색상으로 표시 (`0`은 비활성화) |
| `gitStatus.showFileStats` | boolean | false | 파일 변경 횟수 `!M +A ✘D ?U` 표시 |
| `gitStatus.branchOverflow` | `truncate` \| `wrap` | `truncate` | 현재의 생략 동작 유지 또는 가능할 때 git 블록을 별도 줄로 줄바꿈 |
| `jjStatus.enabled` | boolean | false | jj (Jujutsu) 상태 표시 활성화. 활성화되고 `.jj` 디렉토리가 발견되면 해당 리포지토리에 대해 git 대신 jj를 사용합니다. |
| `jjStatus.showDirty` | boolean | true | 작업 복사본 커밋이 부모와 다를 때 `*` 표시 |
| `jjStatus.showConflicts` | boolean | true | 작업 복사본 커밋에 해결되지 않은 충돌이 있을 때 `!conflict` 마커 표시 |
| `display.showModel` | boolean | true | 모델 이름 `[Opus]` 표시 |
| `display.modelSource` | `stdin` \| `auto` \| `transcript` | `stdin` | 모델 이름의 소스 제어. `stdin`은 기본 동작이며 Claude Code가 보고하는 값을 사용합니다. `auto`는 트랜스크립트 모델을 통해 비-Claude 모델의 프록시 리디렉션을 감지합니다. `transcript`는 항상 API 응답의 모델을 사용합니다. |
| `display.showProvider` | boolean | false | 모델 이름 *앞에* 제공자 레이블 표시 (예: `[Bedrock \| Opus 4.6]`). 서로 다른 제공자가 동일한 이름의 모델을 제공하는 커스텀 프록시 사용 시 유용합니다. |
| `display.providerName` | string | `""` | `display.showProvider`와 함께 사용되는 명시적 제공자 레이블. 비어 있으면 자동 감지된 제공자 사용. |
| `display.showAddedDirs` | boolean | true | `/add-dir`로 추가된 추가 워크스페이스 디렉토리 표시 (예: `+sparkle +lib-foo`). 최대 5개까지 표시되며 기본 이름은 24자로 제한됩니다. |
| `display.addedDirsLayout` | `inline` \| `line` | `inline` | `inline`은 프로젝트 이름 옆에 `+name` 접두사로 표시, `line`은 별도의 `Added dirs: name1, name2` 줄에 표시. |
| `display.showContextBar` | boolean | true | 시각적 컨텍스트 바 `████░░░░░░` 표시 |
| `display.contextValue` | `percent` \| `tokens` \| `remaining` \| `both` | `percent` | 컨텍스트 표시 형식 (`45%`, `45k/200k`, 남은 양 `55%`, 또는 `45% (45k/200k)`) |
| `display.autoCompactWindow` | number \| `null` | `null` | 양수로 설정하면(예: `200000`), 전체 모델 컨텍스트 윈도우 대신 이 값으로 컨텍스트 퍼센트를 계산하여 `/context` 수치와 일치시킵니다. |
| `display.showConfigCounts` | boolean | false | CLAUDE.md, 규칙, MCP, 훅 개수 표시 |
| `display.showCost` | boolean | false | 사용 가능한 경우 Claude Code의 네이티브 `cost.total_cost_usd`를 사용하여 세션 비용 표시. 직접 Anthropic 세션의 경우 로컬 추정치로 대체. |
| `display.showRoutedCost` | boolean | false | 라우팅된 제공자(Bedrock/Vertex)의 비용도 표시. `showCost`가 켜져 있어야 합니다. |
| `display.showOutputStyle` | boolean | false | 설정 파일의 활성 Claude Code `outputStyle`을 `style: <name>`으로 표시 |
| `display.showDuration` | boolean | false | 세션 지속 시간 `⏱️ 5m` 표시 |
| `display.showSpeed` | boolean | false | 출력 토큰 속도 `out: 42.1 tok/s` 표시 |
| `display.showUsage` | boolean | true | 사용 가능한 경우 Claude 구독자 사용량 제한 표시 |
| `display.usageValue` | `percent` \| `remaining` | `percent` | 사용량 표시 형식 (`25%` 사용됨, 또는 `75%` 남음) |
| `display.usageBarEnabled` | boolean | true | 사용량을 텍스트 대신 시각적 바로 표시 |
| `display.usageCompact` | boolean | false | 사용량을 `5h: 25% (1h 30m)`와 같은 짧은 텍스트 형식으로 표시. `display.usageBarEnabled`보다 우선순위가 높음. |
| `display.showResetLabel` | boolean | true | 사용량 카운트다운 앞에 `resets in` 접두사 표시 |
| `display.timeFormat` | `relative` \| `absolute` \| `both` \| `elapsed` \| `elapsedAndAbsolute` | `relative` | 사용량 윈도우 시간 표시 방식: 카운트다운만 (`resets in 2h 30m`), 절대 시간 (`resets at 14:30`), 둘 다, 경과 퍼센트 (`53% elapsed`), 또는 경과 시간 + 절대 시간 |
| `display.sevenDayThreshold` | 0-100 | 80 | 7일 사용량이 임계값 이상일 때 표시 (0 = 항상 표시) |
| `display.externalUsagePath` | string | `""` | 로컬 사용량 스냅샷 파일의 선택적 절대 경로. |
| `display.externalUsageWritePath` | string | `""` | 다른 로컬 도구를 위해 ClaudeHUD가 공식 stdin `rate_limits`를 기록할 선택적 절대 `.json` 경로. |
| `display.externalUsageFreshnessMs` | number | `300000` | 외부 사용량 스냅샷을 무시하기 전까지의 최대 허용 기간 |
| `display.showTokenBreakdown` | boolean | true | 컨텍스트가 높을 때(85%+) 토큰 세부 정보 표시 |
| `display.showTools` | boolean | false | 도구 활동 줄 표시 |
| `display.showSkills` | boolean | false | `Skill` 도구 호출에서 감지된 활성 Skill 표시 |
| `display.showMcp` | boolean | false | `mcp__server__tool` 호출에서 감지된 활성 MCP 서버 표시 |
| `display.toolNameMaxLength` | number | `0` | 표시될 도구 이름의 최대 길이. `0`은 전체 이름 유지. |
| `display.toolsMaxVisible` | number | `4` | 도구 줄에 표시될 최대 완료 도구 수. `0`은 제한 없음. |
| `display.showAgents` | boolean | false | 에이전트 활동 줄 표시 |
| `display.showTodos` | boolean | false | 할 일 진행 상황 줄 표시 |
| `display.showSessionName` | boolean | false | `/rename`으로 설정한 세션 슬러그 또는 커스텀 제목 표시 |
| `display.showAuth` | boolean | false | 현재 로그인된 인증 방법(구독 플랜)을 첫 줄 끝에 세그먼트로 표시 (예: `Claude Max 20x`). |
| `display.showAuthUser` | boolean | false | 인증 방법 옆에 로그인된 계정 표시 |
| `display.authUserLength` | number | `8` | 계정 이름 표시 최대 글자 수. `0`은 전체 이름 표시. |
| `display.showAdvisor` | boolean | false | 프로젝트 줄에 Claude Code의 `/advisor`로 설정된 모델을 인라인 표시 (예: `Advisor: Opus 4.7`). |
| `display.advisorOverride` | string | `""` | 표시될 어드바이저 레이블의 선택적 수동 오버라이드. |
| `display.showSessionStartDate` | boolean | false | 트랜스크립트 세션 시작 타임스탬프 표시 |
| `display.showLastResponseAt` | boolean | false | 마지막 어시스턴트 응답이 작성된 후 경과 시간 표시 |
| `display.showCompactions` | boolean | false | 이번 세션에서 발생한 컨텍스트 압축(수동 `/compact` 또는 자동) 횟수 표시. |
| `display.showEffortLevel` | boolean | false | 모델 배지에 현재 추론 노력(reasoning effort) 수준 표시. |
| `display.showClaudeCodeVersion` | boolean | false | 설치된 Claude Code 버전 표시 (예: `CC v2.1.81`) |
| `display.showMemoryUsage` | boolean | false | 확장 레이아웃에서 대략적인 시스템 RAM 사용량 줄 표시 |
| `display.showPromptCache` | boolean | false | 트랜스크립트의 마지막 어시스턴트 응답 타임스탬프 기반으로 프롬프트 캐시 카운트다운 표시 |
| `display.promptCacheTtlSeconds` | number | `300` | 프롬프트 캐시 TTL(초). Pro는 기본값 유지, Max는 `3600` 설정. |
| `colors.context` | color value | `green` | 컨텍스트 바 및 컨텍스트 퍼센트의 기본 색상 |
| `colors.usage` | color value | `brightBlue` | 경고 임계값 미만일 때 사용량 바 및 퍼센트의 기본 색상 |
| `colors.warning` | color value | `yellow` | 컨텍스트 임계값 및 사용량 경고 텍스트의 경고 색상 |
| `colors.usageWarning` | color value | `brightMagenta` | 임계값에 근접한 사용량 바 및 퍼센트의 경고 색상 |
| `colors.critical` | color value | `red` | 한계 도달 상태 및 심각 임계값의 심각 색상 |
| `colors.model` | color value | `cyan` | `[Opus]`와 같은 모델 배지 색상 |
| `colors.project` | color value | `yellow` | 프로젝트 경로 색상 |
| `colors.git` | color value | `magenta` | `git:(` 및 `)`와 같은 git 래퍼 텍스트 색상 |
| `colors.gitBranch` | color value | `cyan` | git 브랜치 및 브랜치 상태 텍스트 색상 |
| `colors.label` | color value | `dim` | `Context`, `Usage`, 개수, 진행 텍스트 등의 레이블 및 보조 메타데이터 색상 |
| `colors.custom` | color value | `208` | 선택적 커스텀 줄의 색상 |
| `colors.barFilled` | string | `█` | 진행 바의 채워진 부분에 사용되는 문자 |
| `colors.barEmpty` | string | `░` | 진행 바의 빈 부분에 사용되는 문자 |

`colors.barFilled` 및 `colors.barEmpty`는 단일 가시적 글리프를 허용합니다. 제어 문자, 보이지 않는 형식 문자, 줄/단락 구분자 등은 거부됩니다. 이모지나 CJK와 같은 와이드 문자는 터미널에 따라 바 정렬에 영향을 줄 수 있습니다.

지원되는 색상 이름: `dim`, `red`, `green`, `yellow`, `magenta`, `cyan`, `brightBlue`, `brightMagenta`. 256색 숫자(`0-255`) 또는 헥사 코드(`#rrggbb`)도 사용할 수 있습니다.

`display.showMemoryUsage`는 완전한 선택 사항이며 `expanded` 레이아웃에서만 렌더링됩니다. 이는 로컬 머신의 대략적인 시스템 RAM 사용량을 보고하며, Claude Code 내부나 특정 프로세스의 정밀한 메모리 압력을 나타내지는 않습니다. OS 캐시와 버퍼가 사용 중인 메모리로 계산될 수 있어 실제 압력보다 높게 표시될 수 있습니다.

`display.showCost`는 완전한 선택 사항입니다. ClaudeHUD는 가능하면 Claude Code가 stdin으로 제공하는 네이티브 `cost.total_cost_usd` 필드를 우선 사용합니다. 직접 Anthropic 세션에서 해당 필드가 없거나 유효하지 않은 경우, 기존의 로컬 트랜스크립트 기반 추정치로 대체하여 비용 줄이 계속 작동하도록 합니다. 네이티브 필드는 세션의 첫 API 응답 전에는 없으므로, 그때까지 비용 표시가 숨겨질 수 있습니다. 또한 Bedrock 및 Vertex AI와 같은 라우팅된 제공자의 경우, 클라우드 제공자 청구 세션이 `$0.00`으로 보고되거나 필드를 생략할 수 있어 기본적으로 비용을 숨깁니다. 이러한 제공자의 비용을 보려면 `display.showRoutedCost: true`(`showCost`와 함께)를 설정하세요. 양수일 때는 네이티브 `cost.total_cost_usd`가 `Cost`로 표시되고, 그렇지 않으면 Anthropic 가격표 기반의 토큰 추정치 `Est.`로 표시됩니다.

`display.showPromptCache`는 완전한 선택 사항입니다. 활성화하면 ClaudeHUD는 로컬 트랜스크립트의 마지막 어시스턴트 응답 타임스탬프를 확인하여 프롬프트 캐시가 만료될 때까지의 실시간 카운트다운을 표시합니다. 기본 TTL은 5분(`300`초)입니다. Max 스타일의 1시간 윈도우를 원하시면 `display.promptCacheTtlSeconds`를 `3600`으로 설정하세요. 트랜스크립트에 아직 어시스턴트 타임스탬프가 없으면 캐시 요소는 숨겨집니다.

### 사용량 제한 (Usage Limits)

Claude Code가 stdin으로 구독자 `rate_limits` 데이터를 제공하는 경우 사용량 표시가 **기본적으로 활성화**됩니다. 이는 두 번째 줄의 컨텍스트 바 옆에 표시됩니다.

`display.usageValue`를 `remaining`으로 설정하면 사용된 양 대신 남은 할당량을 표시합니다. 경고 색상 및 7일 임계값 확인은 여전히 기본 사용 퍼센트를 사용합니다.

ClaudeHUD는 속도 제한 윈도우에 대해 공식 statusline stdin 페이로드를 선호합니다. `display.externalUsagePath`가 최신 로컬 사이드카 스냅샷을 가리키면, ClaudeHUD는 stdin 윈도우 옆에 `balance_label`을 추가할 수 있습니다. stdin `rate_limits`가 없는 경우, 동일한 스냅샷이 대체 사용량 윈도우를 제공할 수 있습니다.

대체 스냅샷 경로는 절대 경로여야 합니다. 스냅샷은 충분히 최신 상태여야 하며(`display.externalUsageFreshnessMs`), 유효한 `updated_at`과 `five_hour` 윈도우, `seven_day` 윈도우 또는 `balance_label`을 포함해야 합니다. `balance_label`은 선불 제공자 잔액을 위한 선택적 텍스트이며, 표시 전 트리밍, 길이 제한 및 새니타이징 처리를 거칩니다. 상대 경로, 잘못된 JSON, 오래된 파일 또는 잘못된 타임스탬프는 조용히 무시됩니다.

다른 도구를 위해 공식 stdin `rate_limits`를 로컬 스냅샷으로 기록하려면 `display.externalUsageWritePath`를 설정하세요. 경로는 절대 경로여야 하며 `.json`으로 끝나고 기존 디렉토리에 있어야 합니다.

무료/주간 전용 계정은 고스트 `5h: --` 자리 표시자 대신 주간 윈도우만 렌더링합니다.

7일 퍼센트는 `display.sevenDayThreshold`(기본 80%) 이상일 때 나타납니다:

```
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)
```

비활성화하려면 `display.showUsage`를 `false`로 설정하세요.

리셋 시간은 기본적으로 상대적 카운트다운을 사용합니다. 절대 시간을 원하시면 `display.timeFormat`을 `absolute`로, 둘 다 원하시면 `both`로, 각 사용량 윈도우의 진행 정도를 원하시면 `elapsed`로, 경과 진행도와 절대 리셋 시간을 모두 원하시면 `elapsedAndAbsolute`로 설정하세요. 이 설정은 현재 수동으로만 가능하며, `/claude-hud:configure`는 이 값을 편집하지 않고 그대로 유지합니다.

`(resets in 3h 17m)` 대신 `(3h 17m)`과 같이 더 짧은 사용량 카운트다운을 원하시면 `display.showResetLabel`을 `false`로 설정하세요.

`5h: 25% (1h 30m)`와 같이 더 짧은 사용량 전용 형식을 원하시면 `display.usageCompact`를 `true`로 설정하세요. 컴팩트 사용량은 `display.usageBarEnabled`보다 우선합니다.

### 보안 참고 사항

ClaudeHUD는 설계상 로컬에서만 작동합니다. 네트워크 요청을 보내지 않으며, 자격 증명을 스크래핑하거나 문서화되지 않은 Claude API를 호출하지 않습니다. stdin의 statusline JSON, Claude Code가 제공하는 현재 세션 트랜스크립트 경로, `~/.claude` 아래의 선택된 Claude 설정 파일, 현재 워크스페이스의 git 메타데이터만 읽습니다.

HUD 캐시 파일은 POSIX 파일 시스템에서 비공개 권한으로 `~/.claude/plugins/claude-hud` 아래에 작성됩니다. 캐시에는 컨텍스트 퍼센트, 토큰 카운터, 활동 이름 및 확인된 Claude Code 버전과 같은 파생 표시 메타데이터가 저장됩니다.

`--extra-cmd`는 HUD 프로세스 환경에 `CLAUDE_HUD_ALLOW_EXTRA_CMD=1` (또는 `true`, `yes`, `on`)이 있는 경우에만 활성화됩니다. 이 옵션은 임의 코드 실행와 같습니다. statusline 갱신 시 제공된 셸 명령어를 사용자 권한으로 실행합니다. 신뢰할 수 없는 소스에서 복사한 명령어를 사용하지 마세요.

**요구 사항:**
- Claude Code가 현재 세션의 stdin에 구독자 `rate_limits` 데이터를 포함해야 함
- API 키 전용 사용자에게는 제공되지 않음

**문제 해결:** 사용량이 표시되지 않는 경우:
- Claude 구독자 계정으로 로그인했는지 확인하세요 (API 키 아님)
- 설정에서 `display.showUsage`가 `false`로 설정되어 있지 않은지 확인하세요
- API 사용자는 사용량 표시가 나타나지 않습니다 (속도 제한이 아니라 토큰당 과금 방식이기 때문)
- AWS Bedrock 모델은 `Bedrock`이라고 표시되며 사용량 제한을 숨깁니다 (사용량은 AWS에서 관리됨)
- Bedrock 및 Vertex AI 모델은 기본적으로 비용 추정치를 숨깁니다 (청구 방식이 Anthropic 직접 결제와 다름). `display.showRoutedCost`로 활성화하세요.
- Claude Code는 세션의 첫 모델 응답 전까지 `rate_limits`를 비워둘 수 있습니다.
- 일부 Claude Code 빌드 및 구독 티어에서는 첫 응답 후에도 `rate_limits`가 누락될 수 있습니다.
- `display.externalUsagePath`를 설정한 경우, ClaudeHUD는 사용량을 숨기기 전에 해당 로컬 스냅샷을 먼저 시도합니다.
- ClaudeHUD는 절대 자격 증명 스크래핑이나 문서화되지 않은 API 호출로 대체하지 않습니다.

대체 스냅샷 예시:

```json
{
  "updated_at": "2026-04-20T12:00:00.000Z",
  "five_hour": {
    "used_percentage": 42,
    "resets_at": "2026-04-20T15:00:00.000Z"
  },
  "seven_day": {
    "used_percentage": 84,
    "resets_at": "2026-04-27T12:00:00.000Z"
  }
}
```

### 설정 예시

```json
{
  "language": "zh",
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "skills", "mcp", "context", "usage", "memory", "environment", "agents", "todos", "sessionTime"],
  "projectLineOrder": ["project", "model"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "jjStatus": {
    "enabled": true,
    "showDirty": true,
    "showConflicts": true
  },
  "display": {
    "showTools": true,
    "showSkills": true,
    "showMcp": true,
    "showAgents": true,
    "showTodos": true,
    "showConfigCounts": true,
    "showDuration": true,
    "showMemoryUsage": true
  },
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red",
    "model": "cyan",
    "project": "yellow",
    "git": "magenta",
    "gitBranch": "cyan",
    "label": "dim",
    "custom": "#FF6600"
  }
}
```

### 표시 예시

**1단계 (기본값):** `[Opus] │ my-project git:(main)`

**2단계:** `[Opus] │ apps/my-project git:(main)`

**3단계:** `[Opus] │ dev/apps/my-project git:(main)`

**Dirty 표시 포함:** `[Opus] │ my-project git:(main*)`

**Ahead/Behind 포함:** `[Opus] │ my-project git:(main ↑2 ↓1)`

**파일 통계 포함:** `[Opus] │ my-project git:(main* !3 +1 ?2)`
- `!` = 수정됨, `+` = 추가됨/스테이징됨, `✘` = 삭제됨, `?` = 추적되지 않음
- 0인 개수는 깔끔한 표시를 위해 생략됩니다.

### Jujutsu (jj) 지원

`jjStatus.enabled`를 `true`로 설정하여 활성화하세요. 작업 디렉토리(또는 그 상위)에서 실제 `.jj` 디렉토리가 발견되면, HUD는 git 대신 jj 네이티브 상태를 표시합니다. 두 가지는 호출당 상호 배타적이며, jj+git이 함께 있는 리포지토리에서도 마찬가지입니다. jj를 안전하게 쿼리할 수 없는 경우, 함께 있는 리포지토리는 기존 git 상태로 대체됩니다.

**북마크가 있는 경우:** `[Opus] │ my-project jj:(mybookmark)`

**익명 변경 사항 (`@`에 북마크 없음):** `[Opus] │ my-project jj:(wrulwzyw)`

**더티 작업 복사본:** `[Opus] │ my-project jj:(mybookmark*)`

**해결되지 않은 충돌:** `[Opus] │ my-project jj:(mybookmark !conflict)`

Ahead/behind 카운트와 파일별 변경 통계는 현재 버전에서 git 전용입니다. jj의 동등한 기능은 `remote_bookmarks()`에 대한 비용이 많이 드는 revset 쿼리가 필요하므로, jj 상태 가져오기를 단일 서브프로세스 호출로 유지하기 위해 제외되었습니다.

HUD는 프롬프트 안전, 읽기 전용 모드로 jj를 실행합니다: 페이저를 비활성화하고, 라이브 작업 복사본을 무시하며, 조정(reconciling) 없이 현재 작업을 읽습니다. 이를 통해 statusline 갱신 중에 파일 스냅샷을 찍거나 리포지토리 상태를 변경하는 것을 방지합니다. 결과적으로 더티 마커는 jj의 가장 최근 작업 복사본 스냅샷을 반영하며, 다른 jj 명령어가 새로운 변경 사항을 기록할 때까지 오래된 상태로 유지될 수 있습니다.

### 자동 새로고침

Claude Code는 상호작용(새 어시스턴트 메시지, `/compact` 완료, 권한 모드 변경 또는 vim-mode 전환) 후에만 statusline을 다시 실행합니다. 따라서 세션 지속 시간, 사용량 리셋 카운트다운, 프롬프트 캐시 카운트다운과 같은 시간 기반 정보는 메시지 사이에 멈춰 있게 됩니다. 이를 계속 업데이트하려면 `~/.claude/settings.json`의 `statusLine` 항목에 `refreshInterval`(초, 최소 1)을 추가하세요:

```json
{
  "statusLine": {
    "type": "command",
    "command": "...",
    "refreshInterval": 5
  }
}
```

`/claude-hud:setup` 과정에서 이 설정을 제안합니다. 매 새로고침마다 HUD 명령어가 다시 실행되므로 5초가 적당한 기본값입니다. 시각적으로 부드러운 카운트다운을 원하시면 1초를 사용하세요.

### HUD 일시적 비활성화

`CLAUDE_HUD_DISABLE` 환경 변수를 설정하여 HUD 없이 세션을 시작할 수 있습니다. `settings.json`에서 `statusLine` 항목을 제거할 필요가 없습니다:

```bash
CLAUDE_HUD_DISABLE=1 claude
```

설정하지 않거나 명시적으로 부정 값(`0`, `false`, `off`, `no`)을 설정하면 HUD가 활성화된 상태로 유지됩니다. 비활성화되면 HUD는 트랜스크립트를 읽거나 git을 실행하지 않고 즉시 종료되므로, 해당 세션의 statusline은 비어 있게 됩니다.

### 문제 해결

**설정이 적용되지 않나요?**
- JSON 구문 오류가 있는지 확인하세요: 잘못된 JSON은 조용히 기본값으로 되돌아갑니다.
- 유효한 값인지 확인하세요: `pathLevels`는 1, 2, 3 또는 `full`이어야 하며, `lineLayout`은 `expanded` 또는 `compact`, `maxWidth`는 양수여야 합니다.
- 설정을 삭제하고 `/claude-hud:configure`를 실행하여 다시 생성하세요.

**Git 상태가 표시되지 않나요?**
- git 리포지토리에 있는지 확인하세요.
- 설정에서 `gitStatus.enabled`가 `false`가 아닌지 확인하세요.

**jj 상태가 표시되지 않거나 jj 리포지토리에서 `git:(...)`이 보이나요?**
- 작업 디렉토리 또는 그 상위에 `.jj` 디렉토리가 있는지 확인하세요.
- 설정에서 `jjStatus.enabled`를 `true`로 설정하세요 (jj 지원은 선택 사항입니다).
- `jj` 바이너리가 설치되어 있고 `PATH`에 있는지 확인하세요.

**도구/스킬/MCP/에이전트/할 일 줄이 보이지 않나요?**
- 이 항목들은 기본적으로 숨겨져 있습니다. 설정에서 `showTools`, `showSkills`, `showMcp`, `showAgents`, `showTodos`를 통해 활성화하세요.
- 또한 표시할 활동이 있을 때만 나타납니다.

**설정 후 HUD가 나타나지 않나요?**
- 아무 메시지나 보내보세요. 설정은 자동으로 다시 로드되지만, statusline은 다음 상호작용 후에 렌더링됩니다.
- 여전히 나타나지 않는다면 Claude Code를 재시작하세요 (완전히 종료 후 `claude` 다시 실행). 이전 버전의 Claude Code는 statusLine 변경 사항을 적용하기 위해 재시작이 필요합니다.
- 환경 변수에 `CLAUDE_HUD_DISABLE`이 설정되어 있지 않은지 확인하세요 (예: 셸 프로필에서 export 됨). 이 변수는 설정 확인을 포함하여 HUD를 완전히 침묵시킵니다.

---

## 요구 사항

- Claude Code v1.0.80+
- macOS/Linux: Node.js 18+ 또는 Bun
- Windows: Node.js 18+

---

## 개발

```bash
git clone https://github.com/jarrodwatts/claude-hud
cd claude-hud
npm ci && npm run build
npm test
```

가이드라인은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참조하세요.

---

## 라이선스

MIT — [LICENSE](LICENSE) 참조

---

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=jarrodwatts/claude-hud&type=Date)](https://star-history.com/#jarrodwatts/claude-hud&Date)

claude-hud

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README