Claude Code 플러그인: claude-hud 소개

Claude의 코드 플러그인으로, 현재 컨텍스트 사용량, 속도 제한(rate limits), 활성 도구(tools), 실행 중인 에이전트(agents), 할 일(todo) 진행 상황 등을 입력창 아래에 항상 표시해 줍니다.

🌐 English | 中文 문서

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

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/reload-plugins
...

/claude-hud:setup

이 명령어는 상태 표시줄을 HUD(Head-Up Display)로 지정합니다. Claude Code가 자체적으로 설정을 다시 로드하므로, HUD가 즉시 나타납니다. 사용자 정의를 하려면 Claude에게 요청하거나 /claude-hud:configure를 실행하세요.

.터미널 환경을 선호하시나요?

claude plugin marketplace add jarrodwatts/claude-hud
claude plugin install claude-hud@claude-hud

그런 다음 /reload-plugins를 실행하고 세션 내부에서 /claude-hud:setup을 실행하세요.

Windows: setup 시 JavaScript 런타임이 없다는 메시지가 표시되는 경우

Node.js LTS 버전을 설치(winget install OpenJS.NodeJS.LTS)하고, 셸을 재시작한 다음 /claude-hud:setup을 다시 실행하세요.

기본 설정은 두 줄입니다:

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (resets in 1h 30m)

첫 번째 줄: 모델(model) 및 감지된 제공업체 레이블(Bedrock, Vertex, MiniMax 등).

선택적 라인: /claude-hud:configure로 활성화하는 라인들:

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 ← tools
◐ explore [haiku]: Finding auth code (2m 15s) ← agents
▸ Fix authentication bug (2/5) ← todos

Claude HUD는 상태 표시줄 명령어입니다. Claude Code는 이 명령어를 stdin의 세션 데이터(모델, 컨텍스트 창, 비용, 속도 제한, 프롬프트 캐시)와 함께 실행하고 출력되는 내용을 보여줍니다. 도구(tools), 에이전트(agents), 할 일(todos) 라인과 같은 일부 선택적 요소들은 세션 기록을 읽습니다. 별도의 창이나 tmux가 필요 없으며 모든 터미널에서 작동합니다.

/claude-hud:configure

이 안내 흐름은 레이아웃, 활동 라인, 세션 정보, 사용량, git, 언어 및 사용자 정의 라인을 다룹니다. 저장하기 전에 변경 사항을 미리 보여주고, 질문하지 않은 모든 설정은 유지합니다.

나머지 모든 것은 ~/.claude/plugins/claude-hud/config.json (또는 $CLAUDE_CONFIG_DIR 아래)에 저장됩니다.

)

여러 개의 CLAUDE_CONFIG_DIR가 하나의 plugins/ 디렉터리를 공유하는 경우, 각 디렉터리별 설정을 $CLAUDE_CONFIG_DIR/claude-hud.json에 넣으세요.
이는 동일한 형태를 사용하며 변경해야 하는 키만 필요하고, 공유된 설정 위에 계층적으로 적용됩니다:

{ "display": { "customLine": "Work Team" } }

레이블은 영어(기본값), 간체 중국어 (zh-Hans, 별칭 zh), 그리고 번체 중국어 (zh-Hant, 별칭 zh-TW)에서 사용할 수 있습니다.

예시: ["project","model"]은 모델 배지 앞에 프로젝트/git 블록을 배치합니다. |
display.mergeGroups |
string[][] | (["context","usage"]]) | 인접할 때 한 줄을 공유해야 하는 확장 모드 그룹입니다. []로 설정하면 병합된 줄 기능을 비활성화합니다. |
display.rightAlign |
string[] | [] |
병합된 행의 첫 번째 요소부터 오른쪽 정렬 접미사를 시작하며, elementOrder를 유지하고 공백으로 간격을 채웁니다. 앵커가 실제로 한 줄로 렌더링되는 display.mergeGroups 그룹 내에 있어야 합니다. 터미널 너비가 알려지지 않았거나, 앵커가 첫 번째이거나, 패딩할 공간이 없는 경우에는 무시됩니다. 예시: ["context"]를 사용하고 ["project","context","usage"] 그룹을 사용하면 프로젝트/git은 왼쪽에 유지되고 context + usage는 오른쪽에 고정됩니다. |
gitStatus.enabled |
boolean | true | HUD에 git 브랜치 표시 여부 |
gitStatus.showDirty |
boolean | true | 커밋되지 않은 변경사항에 대해 * 표시 여부 |
gitStatus.showAheadBehind |
boolean | false | 원격 대비 앞/뒤 차이(↑N ↓N) 표시 여부 |
gitStatus.pushWarningThreshold |
number | 0 | 푸시되지 않은 커밋 수가 이 임계값(0) 이상일 때, 앞차이 개수를 경고 색상으로 지정합니다 (0은 비활성화). |
gitStatus.pushCriticalThreshold |
number | 0 | 푸시되지 않은 커밋 수가 이 임계값(0) 이상일 때, 앞차이 개수를 심각한 색상으로 지정합니다 (0은 비활성화). |
gitStatus.showFileStats |
boolean | false | 파일 변경 카운트(!M +A ✘D ?U) 표시 여부 |
gitStatus.showWorktree |
boolean | false | 연결된 git 작업 트리에서 브랜치 뒤에 이름 표시 여부, 예: git:(feat/x) ⎇ feat-x |
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.showProject |
boolean | true | 프로젝트 경로 표시
display.modelSource |
stdin | auto | transcript |
stdin |
모델 이름이 가져오는 출처를 제어합니다. stdin은 기본 동작을 유지하며 항상 Claude Code가 보고하는 것을 사용합니다. auto는 트랜스크립트 모델만 비(非)Claude 모델에 사용하여 프록시 리다이렉션 감지 기능을 활성화합니다. transcript는 항상 API 응답의 모델을 사용합니다. 트랜스크립트 모델 값은 터미널에서 안전하게 처리되며 80자로 제한됩니다 |
display.modelFormat |
full | compact | short |
full |
compact는 (1M context)와 같은 컨텍스트 창 접미사를 제거합니다. short도 선행하는 Claude 를 제거합니다 |
display.modelOverride |
string | "" |
모델 이름 대신 표시할 텍스트 (최대 80자)
display.showProvider |
boolean | false | 모델 이름 앞에 제공업체 레이블을 표시합니다. 예: [Bedrock | Opus 4.6] . 사용자 지정 프록시가 서로 다른 제공업체의 동일한 이름을 가진 모델을 서비스할 때 유용합니다. 비활성화되면, 자동 감지된 제공업체가 이전처럼 모델 뒤에 붙습니다 |
display.providerName |
string | "" |
display.showProvider와 함께 사용되는 명시적인 제공업체 레이블입니다. 예: 자동 감지가 불가능한 사용자 지정 프록시의 경우. 비어 있으면 자동 감지된 제공업체(Bedrock/Vertex/MiniMax/Enterprise)로 대체됩니다; 40자로 제한됨 |
display.showAddedDirs |
boolean | true | /add-dir에서 오는 추가 작업 공간 디렉터리 표시 (예: +sparkle +lib-foo ); 빈 배열은 아무것도 렌더링하지 않습니다.

두 레이아웃 모두에서 최대 5개의 디렉터리만 렌더링합니다 (초과분은 +N more로 표시). 또한, 파일 이름(basename)은 …와 함께 24자로 잘립니다.|
display.addedDirsLayout |
inline | line |
inline은 디렉터리를 프로젝트 이름 옆에 +name 접두사로 배치하고; line은 별도의 Added dirs: name1, name2 줄(접두사 없음, 쉼표 구분)에 렌더링합니다.|
display.showContextBar |
boolean | true | 시각적 컨텍스트 바 ████░░░░░░ 표시|
display.contextValue |
percent | tokens | remaining | both |
percent |
컨텍스트 표시 형식 (45%, 45k/200k, 55% remaining, 또는 45% (45k/200k))|
display.autoCompactWindow |
number | null |
null |
200000와 같은 양수로 설정하면, 전체 모델 컨텍스트 창 대신 이 자동 압축 창을 기준으로 컨텍스트 백분율을 계산하여 /context 수치와 일치시킵니다. 기본 전체 창 동작을 유지하려면 비워두거나 null로 둡니다.|
display.showConfigCounts |
boolean | false | CLAUDE.md, rules, MCPs, hooks 개수 표시|
display.environmentThreshold |
number | 0 | 설정 카운트의 합계가 이 숫자에 도달할 때까지 숨깁니다 (0 = 항상 표시)|
display.showCost |
boolean | false | 세션 비용(Claude Code에서 보고하는 cost.total_cost_usd) 표시|
display.showRoutedCost |
boolean | false | 또한 Bedrock 및 Vertex 세션의 비용도 표시합니다. 이는 showCost가 숨기는데, 해당 세션은 클라우드 제공업체를 통해 청구되기 때문입니다. showCost 필요|
display.showDailyCost |
boolean | false | 오늘 세션 전반에 걸친 누적 지출을 Today $12.34로 표시합니다. 이는 기본 cost.total_cost_usd에서 플러그인 데이터 디렉터리의 작은 일별 장부에 축적된 것입니다. 현지 자정(midnight)에 재설정됩니다. showCost와 독립적|
display.showWeeklyCost |

display.showOutputStyle |
boolean | false | 현재 출력 스타일을 style: <name> 형식으로 표시합니다 |
display.showDuration |
boolean | false | 세션이 실행된 시간을 표시합니다 (예: ⏱️ 5m) |
display.showSpeed |
boolean | false | 최신 응답의 출력 속도를 표시합니다 (out: 42.1 tok/s) |
display.showUsage |