Usage Meter: 프롬프트 위에 표시되는 Claude Code 사용량 한도 미터

Usage Meter는 Hamza Zafar(hamzafer)가 만든 커뮤니티 모드로, 그의 claude-code-mods 컬렉션에 속해 있습니다. 이 Claude Code 사용량 한도 미터는 Claude Code 프롬프트 위에 한 줄을 그려 플랜의 사용량 한도(rate limit) 창과 세션 비용을 보여 줍니다. 예를 들면 ⏱ 5h █▆▁▁▁ 34% · resets 2h10 · 7d ███▁▁ 61% · $0.42 session과 같습니다.

각 창은 블록 문자로 된 다섯 칸짜리 막대를 받으므로, 부분 칸이 블록 단위보다 더 세밀한 단계를 보여 줍니다. 막대와 퍼센트는 75% 미만에서 초록색, 75%부터 노란색, 90%부터 빨간색입니다. 첫 번째 창(보통 5시간 창)은 항상 초기화 시점을 보여 줍니다. 7일 창이나 지출 한도 같은 나머지 창은 사용량이 높아졌을 때만 초기화 시각을 표시합니다. 카운트다운은 1분마다 갱신됩니다. 초기화 시각이 지난 창은 Claude Code가 새 수치를 보고할 때까지 숨겨지므로, 오래된 100%를 보게 되는 일은 없습니다.

창이 90%를 넘으면 초기화 주기당 한 번 토스트로 경고합니다. 예를 들면 5h usage limit at 92%, resets in 1h05입니다. 터미널이 좁으면 먼저 보조 창을, 그다음 비용을 줄에서 빼므로 주 창은 항상 들어갑니다. 구독이 없는 경우(API 키 세션)에는 플랜 창이 없으므로 비용만 표시됩니다.

이미 저희의 컨텍스트 미터를 쓰고 있다면 겹치는 부분은 5시간·7일 수치와 비용입니다. 컨텍스트 미터는 이를 상태 표시줄에 텍스트로 쓰고 컨텍스트 창 사용률을 더합니다. Usage Meter는 이를 프롬프트 위에 막대로 그리고 실시간 카운트다운을 붙이며, 컨텍스트는 다루지 않습니다. 작성자의 README에 따르면 Claude Code 2.1.287 이상이 필요합니다.

녹화 영상에서는 모드를 불러온 채 Claude Code를 시작하고 짧은 프롬프트를 보낸 뒤, 턴이 끝난 후 프롬프트 위의 줄을 보여 줍니다. 5시간·7일 플랜 창이 퍼센트와 함께 작은 막대로 표시되고, 5시간 창이 초기화될 때까지 남은 시간과 세션 비용이 나옵니다. 데모 계정이 Claude 구독으로 로그인되어 있으므로 플랜 막대가 나타납니다.

설치 블록의 방법 중 아무것이나 사용하십시오. 모두 작성자 자신의 마켓플레이스에서 바로 설치합니다. 따로 설정할 것은 없습니다.

hooks/register.tsx에서 수치를 읽는 두 훅은 다음과 같습니다.

on('session.start', async ($, e, next) => {
  const result = await next(e)
  // Moves the reset countdown on while a window has a reset time.
  timer?.cancel()
  timer = $.clock.every(TICK_MS, () => { /* bumps the tick atom */ })
  const usage = await $.session.usage().catch(() => null)
  if (usage) await take($, usage.rateLimits, usage.cost?.usd).catch(() => {})
  return result
})

on('session.measure', async ($, e, next) => {
  const result = await next(e)
  await take($, e.rateLimits, e.cost?.usd).catch(() => {})
  return result
})

take는 유한한 퍼센트 값을 가진 창만 남겨 호스트가 보관하는 $.state 아톰에 저장하고 warn을 호출합니다. warn은 90% 이상이면서 현재 초기화 주기에 아직 경고하지 않은 창에 대해 토스트를 띄웁니다. 초기화 시각이 30분 넘게 뒤로 밀리면 새 주기로 간주합니다. AbovePrompt의 ui.render 훅은 스냅샷과, 60초 타이머가 올리는 tick 아톰을 읽으므로 새 수치가 없어도 카운트다운이 다시 그려집니다. 순수 함수 build, fit, bar, colorFor, countdown이 각 구간을 만들며, 작성자의 테스트가 이를 검증합니다.

/config에 옵션이 없고 슬래시 명령도 없습니다. 세부 사항은 register.tsx 맨 위의 상수가 정합니다. CELLS(막대 너비, 5), TICK_MS(카운트다운 갱신, 60초), WARN_AT(토스트 임계값, 90), 그리고 창 이름을 정하는 LABELS(5h, 7d, spend)입니다.

저희는 실행하기 전에 플러그인이 실행할 수 있는 모든 파일을 읽었습니다. hooks/hooks.json, hooks/register.tsx, 타입 선언, 테스트입니다. package.json, 설치 스크립트, 번들된 코드는 없습니다.

UI 변경은 프롬프트 위의 줄과 90% 토스트에 해당합니다. 모드는 Claude Code가 이미 추적하는 사용량 수치를 $.session.usage와 session.measure 이벤트로 읽고 $.state에 보관합니다. 명령을 실행하거나, 파일을 읽고 쓰거나, 네트워크를 사용하거나, 환경 변수를 읽거나, 모델을 호출하지 않습니다. claude plugin validate는 오류나 경고를 보고하지 않았고, 작성자의 테스트 11개가 Claude Code 2.1.291에서 모두 통과했습니다.

macOS에서 Claude Code 2.1.291로 확인했습니다(validate와 테스트). 줄이 나타나지 않으면 다음을 확인하십시오.

• claude --version이 2.1.287 이상인지 확인하십시오.
• Claude 구독을 사용 중인지 확인하십시오. API 키를 쓰면 비용만, 그것도 $0.00을 넘은 뒤에만 표시됩니다.
• 첫 모델 응답 전에는 Claude Code에 사용량 수치가 없을 수 있습니다. 프롬프트를 하나 보내면 줄이 채워집니다.
• 입력창 위에 설문이 열려 있을 수 있습니다. 설문이 닫히면 줄이 돌아옵니다.