Claude Code statusLine에서 '5시간 사용량 잔여'를 항상 표시하는 방법 (전달되는 JSON을 모두 분석해봤습니다)

Claude Code를 사용하면서 이런 경험 없으신가요?

• 어느새 5시간 사용량을 다 써서 작업이 멈춘 적
• 컨텍스트가 얼마나 채워졌는지, 압축될 때까지 알 수 없는 경우
• 주간 할당량이 얼마나 남았는지,
  /usage을 열기 전까지는 모르는 경우

5시간 사용량, 컨텍스트 사용률, 주간 사용량을 statusLine을 설정하면 입력창 아래에 항상 표시할 수 있습니다. 이 글에서는 statusLine 명령어에 전달되는 JSON의 내용을 일괄적으로 살펴본 후, 다음과 같은 한 줄을 출력하는 스크립트를 만들 것입니다.

Opus 5.5 | ctx 37% | 5h 42% (남은 시간 1시간 23분) | 주간 18% (남은 일수 3일) | $1.23

statusLine이란?

~/.claude/settings.json에 원하는 명령어를 작성해 두면, Claude Code가 대화 진행에 맞춰 해당 명령어를 실행하고 표준 출력을 입력창 아래에 보여주는 시스템입니다.

{
"statusLine": {
"type": "command",
...
}

핵심은 명령어의 표준 입력으로 현재 세션 정보가 JSON 형태로 전달된다는 것입니다. 이를 읽어서 표시하고 싶은 내용을 조합합니다.

먼저, 전달되는 JSON을 살펴보기

무엇이 오는지 아는 가장 빠른 방법은 그대로 파일에 저장하는 것입니다. tee를 이용해 JSON을 저장하면서 일단 모델 이름만 표시해 보겠습니다.

{
"statusLine": {
"type": "command",
...
}

이렇게 하면, ~/.claude/statusline-last.json에 최신 JSON이 남습니다. 이 tee 명령어는 나중에 자신만의 스크립트를 만들어도, tee ~/.claude/statusline-last.json | ~/.claude/statusline.sh처럼 남겨두면 표시가 이상할 때 확인하는 데 사용할 수 있습니다.

실제로 전달된 내용(Claude Code 2.1.289)은 다음과 같았습니다 (경로는 생략했습니다).

{
"session_id": "2c9a6c71-...",
"transcript_path": "/Users/you/.claude/projects/-Users-you-work/2c9a6c71-....jsonl",
...

생각보다 내용이 많이 들어있습니다.

유용하게 쓸 수 있는 항목들

사용량 한도(rate_limits) 읽는 법

가장 좋은 것은 rate_limits입니다.

used_percentage: 사용한 비율 (0~100). 소수점일 수도 있습니다 -
resets_at: 할당량이 돌아오는 시각. UNIX 시간의 초입니다 (JavaScript에서 사용할 경우 1000배 하여 밀리초로 변환).

/usage을 열지 않아도, 대화가 진행될 때마다 최신 값이 전달됩니다. 다만, 전달된 JSON에 rate_limits

전체 컨텍스트 사용량

context_window.used_percentage를 그대로 출력하는 것이 가장 간편합니다. 토큰 수가 필요할 때는 current_usage의 세 가지 값을 더하면 됩니다.

input_tokens + cache_creation_input_tokens + cache_read_input_tokens

input_tokens만 사용하면 캐시에서 읽은 분량이 포함되지 않아 계속 작은 숫자로 표시되니 주의해야 합니다.

스크립트 만들기

jq는 한 번에 한 줄을 만듭니다 (jq는 macOS 15 이상에서는 기본으로 설치되어 있습니다. 없다면 brew install jq를 사용하세요).

#!/bin/bash
# Claude Code가 표준 입력으로 전달하는 JSON에서, 한 줄의 표시를 만듦
jq -r '
...'

chmod +x ~/.claude/statusline.sh

rate_limits가 없을 때는 // empty로 해당 항목 전체를 제거하기 때문에, join의 결과에 불필요한 구분자가 남지 않습니다.

작동 전 확인해 보기

앞서 tee로 남겨둔 JSON을 파이프하면, Claude Code를 실행하지 않아도 표시 여부를 확인할 수 있습니다.

~/.claude/statusline.sh < ~/.claude/statusline-last.json

Opus 5.5 | ctx 37% | 5h 42%(남은 시간 1시간 23분) | 주 18%(남은 일수 3일) | $1.23

rate_limits가 없는 JSON의 경우, 다음과 같이 됩니다.

Opus 5.5 | ctx 0% | $0

색상 입히기

statusLine은 ANSI 색상을 지원합니다. 예를 들어 5시간 사용량이 80%를 초과했을 때 빨간색으로 하려면, limit을 다음과 같이 수정하면 됩니다.

def limit($key; $label):
.rate_limits[$key] // empty
| (if .used_percentage >= 80 then "" else "" end)
...

주의할 점

• 무거운 처리는 피하기: 대화가 진행될 때마다 실행됩니다. git status를 매번 호출하는 같은 종류의 처리는 큰 리포지토리에서는 느려지기 쉽습니다.
• 프로젝트 정보: 다만, 이용 한도처럼 '자신의 계정'에 대한 정보는 사용자의 설정(.claude/settings.json)에도 적을 수 있는 ~/.claude/settings.json에 두는 것이 자연스럽습니다.
• JavaScript의 resets_at은 초 단위의 Date에 그대로 전달하면 1970년이 됩니다.

보너스: 이 JSON으로 앱을 만들고 있습니다

Claude Code의 작업 과정을 옆에서 보고 확인할 수 있는 macOS 앱 'tanacode'를 만들고 있습니다. 모델, 컨텍스트 사용률, 이용 한도 게이지는 바로 이 statusLine의 JSON에서 가져옵니다.

제가 하는 일은 이 기사의 tee와 거의 같습니다.

• 앱이 실행되는 Claude Code에만,
  --settings로 statusLine을 추가합니다 (~/.claude/settings.json은 수정하지 않습니다) - 그 statusLine은 전달된 JSON을 세션별 파일에 기록하기만 합니다
• 사용자가 직접 statusLine을 설정했다면,
  tee "$FILE" | <사용자 명령어>의 형태로, 같은 JSON을 그쪽에도 전달합니다 (평소 표시 방식 그대로)

# 앱이 --settings로 추가하는 statusLine 명령어(사용자의 statusLine이 있을 때)
tee "$TANACODE_STATUS_FILE" | ~/.claude/statusline.sh

--settings로 전달된 statusLine은 해당 세션에서만 유효합니다. 사용자의 설정 파일에 손을 대지 않고 Claude Code의 정보를 받을 수 있어 편리합니다. transcript_path

따라서, /clear로 대화 로그가 새로워져도 추적할 수 있습니다.

브라우저에서 작동하는 데모도 있으니, 괜찮으시면 한번 사용해 보세요.

맺음말

5시간 잔여 시간이 항상 보이는 것만으로도 '무거운 작업은 시간 제한이 돌아온 후에'와 같은 판단을 내리기 쉬워집니다.

토론