Claude Code 상태 표시 플러그인 설치법

Claude HUD

Claude Code 플러그인으로, 무엇이 일어나고 있는지 보여줍니다: 컨텍스트 사용량, 속도 제한, 활성 도구, 실행 중인 에이전트, 할 일 진행 상황을 입력창 아래에 항상 표시합니다.

🌐 English | 中文文档

설치

Claude Code 안에서 다음을 실행합니다:

1234/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/reload-plugins
/claude-hud:setup

/claude-hud:setup은 상태 표시줄을 HUD로 연결합니다. 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을 다시 실행하세요.

업데이트: Claude Code는 기본적으로 서드파티 플러그인을 자동 업데이트하지 않습니다. 이를 켜려면 /plugin을 실행하고 Marketplaces를 연 다음 claude-hud를 선택하고 Enable auto-update를 고르세요. 해당 옵션이 없거나 업데이트가 오지 않으면, 터미널에서 수동으로 업데이트하세요:

claude plugin marketplace update claude-hud
claude plugin update claude-hud@claude-hud

그다음 열려 있는 어떤 세션에서든 /reload-plugins를 실행합니다. setup을 다시 실행할 필요는 없습니다.

표시되는 내용

기본값은 두 줄입니다:

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

• 1행: 모델, 감지된 경우 공급자 레이블(Bedrock, Vertex, MiniMax), 프로젝트 경로, git 브랜치.
• 2행: 사용 중인 컨텍스트(채워질수록 초록색, 그다음 노란색, 그다음 빨간색)과 구독자 속도 제한.

선택 사항인 줄은 /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으로 전달해 이를 실행하고(모델, 컨텍스트 창, 비용, 속도 제한, 프롬프트 캐시), 출력된 내용을 표시합니다. 도구, 에이전트, todo 줄 같은 일부 선택 요소는 세션 대화 기록도 읽습니다. 별도의 창이나 tmux가 필요 없으며 어떤 터미널에서도 작동합니다.

설정

/claude-hud:configure

가이드형 흐름에서는 레이아웃, 활동 줄, 세션 정보, 사용량, git, 언어, 사용자 지정 줄을 다룹니다. 변경 사항을 저장하기 전에 미리 보여 주며, 묻지 않은 설정은 그대로 유지합니다.

그 밖의 모든 설정은 ~/.claude/plugins/claude-hud/config.json(또는 $CLAUDE_CONFIG_DIR 아래)에 있습니다. 잘못된 값은 기본값으로 되돌아갑니다.

여러 CLAUDE_CONFIG_DIRs가 하나의 plugins/ 디렉터리를 공유하는 경우, 디렉터리별 설정은 $CLAUDE_CONFIG_DIR/claude-hud.json에 넣으세요. 같은 형식을 사용하며, 변경하는 키만 필요하고, 공용 설정 위에 겹쳐 적용됩니다:

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

레이블은 영어(기본값), 간체 중국어(zh-Hans, 별칭 zh), 번체 중국어(zh-Hant, 별칭 zh-TW)로 제공됩니다.

옵션

색상은 이름(dim, red, green, yellow, magenta, cyan, brightBlue, brightMagenta), 256색 번호(0-255), 또는 hex(#rrggbb)를 사용할 수 있습니다. colors.barFilled와 colors.barEmpty는 하나의 보이는 문자만 받습니다. 이모지 같은 넓은 문자는 일부 터미널에서 막대 정렬에 영향을 줄 수 있습니다.

사용량 제한

사용량은 Claude Code가 구독자 rate_limits를 보낼 때마다 표시되며, 이는 세션의 첫 응답 이후입니다. API 키, Bedrock, Vertex 세션에는 구독자 제한이 없으므로 표시되지 않습니다. 7일 창은 display.sevenDayThreshold를 지나면 표시됩니다:

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (resets in 1h 30m) | Weekly █████████░ 85% (resets in 1d)

display.usagePace를 사용하면, 보충되는 속도보다 더 빠르게 사용 중인 창은 호박색(90% 이상으로 끝날 것으로 예상됨) 또는 빨간색(먼저 소진될 것으로 예상됨)으로 바뀌고 ▲가 붙습니다. 사용량이 10% 미만인 창은 중립 상태를 유지합니다.

외부 스냅샷. display.externalUsagePath는 로컬 JSON 파일을 읽습니다. stdin에 항목이 없을 때 그 창들을 채우며, balance_label 또는 model_scoped 창(예: 모델별 주간 할당량)은 stdin의 값에 더해집니다. 파일은 절대 경로여야 하며 display.externalUsageFreshnessMs보다 더 최신이어야 합니다:

1234567{
  "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" },
  "balance_label": "$12.50",
  "model_scoped": [{ "display_name": "Fable", "utilization": 89, "resets_at": "2026-04-27T11:00:00Z" }]
}

display.externalUsageWritePath는 반대로 동작합니다. stdin의 속도 제한을 기존 디렉터리 안의 비공개 .json 파일에 기록해 다른 도구가 읽을 수 있게 합니다.

비용

display.showCost는 Claude Code 자체의 세션 비용을 표시하며, 목록 가격 또는 modelPricing 표를 기준으로 계산됩니다. Bedrock과 Vertex는 클라우드 제공업체를 통해 청구되므로, display.showRoutedCost도 설정되어 있지 않으면 비용이 숨겨집니다.

display.showDailyCost는 여러 세션에 걸친 오늘의 지출을 표시합니다(Today $12.34). 이 값은 플러그인 데이터 디렉터리의 작은 원장에 저장되며, 현지 자정에 초기화되고, 이를 처음 확인한 렌더링 시점부터 세션으로 계산됩니다. display.showWeeklyCost는 7일 할당량 창의 시작 시점부터 같은 원장을 사용하므로, 구독자 세션이 필요합니다.

프롬프트 캐시

display.showPromptCache는 주 대화의 프롬프트 캐시가 차갑게 식는 시점을 보여줍니다. 예: Cache ⏱ until 14:30 또는 expired. 상태 줄은 턴 사이에 다시 그려지지 않기 때문에 카운트다운 대신 시각을 표시합니다. 캐시가 소진되는 시점이 바로 그때이며, 렌더가 얼마나 오래되었든 시각은 여전히 정확합니다. display.showCacheHitRate는 캐시에서 읽은 입력 토큰의 비율을 보여줍니다.

Jujutsu (jj)

.jj 저장소가 있는 디렉터리에서 git 대신 jj 상태를 표시하려면 jjStatus.enabled를 true로 설정하여 jj:(mybookmark*) 또는 jj:(wrulwzyw !conflict) 같은 형식을 표시합니다. HUD는 작업 복사본을 스냅샷하지 않고 jj를 읽기 전용으로 실행하므로, 더티 표시는 jj의 마지막 스냅샷을 반영합니다. 앞섬/뒤처짐 및 파일 통계는 git 전용입니다.

예시

12345678910111213{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "gitStatus": { "showAheadBehind": true, "showFileStats": true },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showCost": true
  },
  "colors": { "context": "cyan", "custom": "#FF6600" }
}

자동 새로고침

Claude Code는 각 메시지 후, /compact 후, 권한 또는 vim 모드가 변경될 때, 속도 제한이 초기화될 때, 그리고 프롬프트 캐시가 만료될 때 상태 줄을 다시 실행합니다. 세션이 유휴 상태일 때 카운트다운과 지속 시간을 계속 흐르게 하려면 ~/.claude/settings.json의 statusLine 항목에 refreshInterval(초)을 추가하세요.

세션에서 끄기

CLAUDE_HUD_DISABLE=1 claude

0, false, off, no 이외의 값은 settings.json을 건드리지 않고 해당 세션에서 HUD를 비웁니다.

보안

Claude HUD는 로컬 전용입니다. 네트워크 요청을 하지 않고, 자격 증명을 읽지 않으며, 문서화되지 않은 API도 호출하지 않습니다. Claude Code의 stdin, 세션 대화 기록, Claude 설정 파일, 그리고 현재 디렉터리의 git 또는 jj 메타데이터를 읽습니다. 유일한 쓰기 작업은 ~/.claude/plugins/claude-hud 아래에 있는 작은 상태 파일들(출력 속도와 비용 원장)이며, 권한은 비공개입니다.

--extra-cmd는 새로고침할 때마다 셸 명령을 실행하고 그 출력을 첫 번째 줄에 표시합니다. HUD 환경에 CLAUDE_HUD_ALLOW_EXTRA_CMD=1이 설정된 경우가 아니면 무시됩니다. 이를 임의 코드 실행으로 간주하고, 신뢰할 수 없는 출처의 명령은 절대 사용하지 마세요.

문제 해결

HUD가 나타나지 않음. 상호작용 후에 상태 줄이 렌더링되므로 메시지를 보내세요. 셸에 CLAUDE_HUD_DISABLE가 설정되어 있지 않은지도 확인하세요. Node 또는 Bun 경로가 바뀌었다면, 예를 들어 nvm이나 mise 업그레이드 후에는 /claude-hud:setup을 다시 실행하세요.

설정이 적용되지 않음. JSON에 구문 오류가 있는지 확인하세요. 잘못된 파일은 기본값으로 대체됩니다. 값이 범위 안에 있는지도 확인하세요. 옵션 표에 해당 값이 나와 있습니다.

사용량이 보이지 않음. 사용량은 Claude 구독자 로그인이 필요하며 첫 응답 후에 나타납니다. display.showUsage를 확인하세요.

git 또는 jj 상태가 보이지 않음. 저장소 안에 있는지, 그리고 gitStatus.enabled(또는 PATH에 jj가 있을 때의 jjStatus.enabled)가 켜져 있는지 확인하세요.

활동 줄이 보이지 않음. 도구, 에이전트, 할 일, 스킬, MCP 줄은 기본적으로 꺼져 있으며, 활동이 있을 때만 표시됩니다.

요구 사항

• Claude Code v2.1.260 이상
• macOS 또는 Linux: Node.js 18+ 또는 Bun
• Windows: Node.js 18+

개발

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

CONTRIBUTING.md를 참조하세요.

라이선스

MIT. LICENSE를 참조하세요.

Star History

출처

• 원문: https://github.com/jarrodwatts/claude-hud (2026-10-22 · github.com)