컨텍스트 미터: Claude Code 컨텍스트 사용량 상태 표시줄

컨텍스트 미터는 Claude Code 컨텍스트 사용량 상태 표시줄 모드입니다. 상태 표시줄에 ctx 42% · 5h 23% · 7d 61.5% · $1.20처럼 간결한 한 줄을 표시합니다. 이는 컨텍스트 창이 얼마나 찼는지, (구독 요금제라면) 5시간 및 7일 요금제 창을 얼마나 사용했는지, 그리고 지금까지 세션 비용이 얼마인지를 나타냅니다. 컨텍스트가 80퍼센트에 도달하면 토스트로 한 번 경고하므로, Claude가 앞부분의 세부 내용을 잃기 시작하기 전에 /compact나 /clear를 실행할 수 있습니다.

핵심은 더 이상 짐작하지 않아도 된다는 점입니다. 긴 작업이 남은 공간에 들어갈지 알기 위해 /cost나 /context를 실행할 필요가 없고, 경고가 충분히 일찍 오기 때문에 원하는 시점에 직접 컴팩션할 수 있습니다. Claude Code 2.1.287 이상이 필요합니다.

녹화 영상에서는 모드를 불러온 상태로 세션을 시작합니다. 첫 답변 전까지 상태 표시줄에는 ctx –가 표시되고, 턴이 끝나면 컨텍스트 퍼센트, 요금제 창 사용량, 비용이 채워집니다.

설치 블록의 방법 중 하나를 선택하십시오. 따로 설정할 것은 없습니다. 기본값만으로 계정이 제공하는 모든 정보가 표시됩니다.

이 모드는 훅 세 개와 갱신 함수 하나로 이루어져 있습니다. hooks/register.ts의 코드는 다음과 같습니다.

async function refresh($: EngineInterface, meter: Meter): Promise<void> {
  // No `breakdown`: the status-line figures alone, which cost no request.
  const usage = await $.session.usage()
  $.ui.status(formatMeter(usage, meter))
  const percent = contextPercent(usage)
  const step = warnStep(percent, meter.warnAtPercent, meter.warned)
  meter.warned = step.warned
  if (step.toast) {
    $.ui.toast(`Context is ${percent}% full. Consider /compact or /clear soon.`)
  }
}

$.session.usage()는 컨텍스트 토큰과 창 크기, 요금제 사용 한도, 비용을 반환합니다. breakdown 없이 호출하면 Claude Code가 이미 가지고 있는 숫자만 읽으므로, 미터를 아무리 자주 실행해도 비용이 들지 않습니다. hooks/format.ts의 formatMeter는 표시할 텍스트를 만들며, 엔진에 없는 수치는 0으로 출력하지 않고 생략합니다. warnStep은 이미 경고했는지를 기억하므로 토스트는 기준을 넘을 때마다 한 번만 나타납니다. 컴팩션으로 컨텍스트가 다시 기준 아래로 내려가면 다시 경고할 수 있습니다.

refresh는 session.start(여기서 $.clock.every 타이머도 시작함), 메인 루프 턴에 한정된 turn.complete, 그리고 session.compact에서 호출됩니다. session.compact는 컴팩션을 취소할 수 있으므로, 이 훅은 먼저 next(e)를 기다리고 next가 확정한 결과를 그대로 돌려주는 .catch를 갖추고 있습니다. 미터가 컴팩션을 멈추는 일은 결코 없습니다.

다음 옵션은 /config에서 설정할 수 있습니다. format: verbose로 설정하면 Context 42% (84k/200k) · 5-hour 23% · 7-day 61.5% · Cost $1.20처럼 줄을 풀어서 표시합니다. 레이블은 hooks/format.ts의 LIMIT_LABELS 테이블에 있으므로 5h나 7d의 이름을 바꾸려면 그곳을 수정하십시오. 경고 문구는 refresh 안의 템플릿 문자열입니다.

이 모드의 배지는 UI 변경 하나뿐입니다. 모드는 상태 표시줄에 쓰고 토스트를 표시합니다. 명령을 실행하지 않고, 파일을 읽거나 쓰지 않으며, 네트워크를 사용하지 않고, 프롬프트를 읽지 않으며, 모델을 호출하지도 않습니다. 그래서 설치할 수 있는 모드 중 가장 안전한 축에 속하며, 처음 써 보기에도 좋은 모드입니다.

끄려면 /plugin disable cm-context-meter를 실행하십시오. 모든 모드를 끈 상태로 세션을 시작하려면 claude --safe-mode를 사용하십시오.

macOS 터미널에서 Claude Code 2.1.291로 테스트했습니다. 미터가 나타나지 않는다면 다음을 확인하십시오.

• claude --version을 확인하십시오. 모드를 사용하려면 2.1.287 이상이 필요합니다.
• /plugin의 Installed 탭에서 모드가 활성화되어 있는지 확인하십시오.
• 셸에서 설치했다면 이미 열려 있던 세션에서 /reload-plugins를 실행하십시오.
• 다른 모드나 사용자 지정 상태 표시줄 명령이 같은 줄을 함께 쓸 수 있습니다. 다른 상태 표시 모드를 잠시 꺼서 텍스트가 밀려나고 있는지 확인하십시오.
• API 키 사용 시 요금제 수치가 없는 것은 정상 동작입니다.

비용 수치는 /cost가 합산하는 것과 같은 세션 추정치이며, 청구서 금액이 아닙니다.