Claude Code를 사용하면서 "앞으로 얼마나 더 쓸 수 있는지", "지금 토큰을 얼마나 쓰고 있는지"가 보이지 않으면, 작업 도중에 갑자기 제한에 걸려 손을 멈추게 된다. 사용량·잔량을 확인하는 방법과 터미널 하단에 상시 표시하는 방법(스테이터스 라인 + ccusage)을 정리한다.

사용량에는 성격이 다른 3가지 레이어가 있으며, 사용하는 도구도 나뉜다.

순서대로 살펴보자.

/context

— 현재 대화의 무게를 확인

1. 입력창에 /context를 입력하면, 현재 세션이 컨텍스트 윈도우 (Context Window)를 얼마나 사용하고 있는지가 내역과 함께 표시된다. 시스템 프롬프트 (System Prompt)・CLAUDE.md・도구 정의 (Tool Definition)・대화 이력 (Conversation History) 등이 각각 어느 정도를 차지하고 있는지 알 수 있다.

위의 예시에서는 1M의 컨텍스트에 대해 115.6k (12%)를 사용 중이며, 그 대부분(90.3k)이 대화 이력 (Messages)이다. 대화가 길어지면 이 부분이 부풀어 오르므로, 무거워지면 다음 조치를 취한다.

• 대화가 길어져 무겁거나 응답이 느리다고 느껴지면 우선 이것을 확인
• 내용이 많아졌다면 /compact (요약하여 압축)를 하거나, 흐름이 끊기는 시점이라면 /clear를 실행
• 컨텍스트가 클수록 1회 상호작용 시의 소비도 늘어나므로, 자주 확인하는 습관을 들이면 제한에 걸리기 어려워진다

/usage

— 플랜의 잔량과 리셋 시각을 확인

2. /usage는 플랜 사용 상황을 표시한다. Claude Code의 이용 제한은 '5시간 세션 프레임'과 '주간 프레임'의 2층 구조로 되어 있으며, 이 화면에 각각의 게이지와 다음 리셋 일시가 나타난다.

• "앞으로 몇 시간 더 쓸 수 있는지", "주간 프레임은 언제 회복되는지"를 여기서 알 수 있다 (위의 예시에서는 5시간 프레임이 49%, 주간 프레임이 44%)
• 제한이 리셋되는 타이밍이 불분명할 때는 우선 이 두 가지 게이지를 보고 어느 쪽 이야기인지 구분한다
• What's contributing to your limits usage? 칸이 은근히 유용하다. "이 단말기의 로컬 세션으로부터의 개산"이지만, 84% of your usage came from subagent-heavy sessions (서브 에이전트의 다용이 소비를 밀어 올리고 있음), 72% of your usage was at >150k context (큰 컨텍스트는 1회당 비용이 높음)와 같이, 무엇이 소비를 부풀리고 있는지를 짚어준다. 서브 에이전트에 저렴한 모델을 할당하거나, 수시로 /compact를 하는 등의 대책 지침이 된다.

참고로 /cost는 세션의 토큰량과 비용을 표시하지만, Pro / Max 등의 구독 서비스에서는 비용이 과금으로 직결되지 않으므로 (사용량은 구독에 포함됨) 참고치 정도로만 보는 것이 좋다. 잔량 관리는 /usage를 사용한다.

ccusage

— 일/주/월별 토큰과 비용을 집계

3. ccusage는 Claude Code의 로컬 로그 (~/.claude/projects/**/*.jsonl)를 읽어서, 토큰 소비와 비용을 집계·시각화하는 외부 CLI이다. GitHub에서 1.4만 스타를 넘어 실질적인 데파크토 (De facto) 표준이 되었다. 설치 없이 바로 실행할 수 있다.

npx ccusage@latest # 일별 집계 (기본값)
npx ccusage@latest weekly # 주별
npx ccusage@latest monthly # 월별
...

비용은 토큰 수 × 모델 단가로 산출한 추정치이므로, 구독 이용 시에는 "얼마나 소비하고 있는가"의 기준으로 본다. "지난주에 얼마나 사용했는지"를 되돌아보는 데 편리하다.

또한 ccusage는 로컬의 .jsonl을 읽을 뿐, 외부로 아무것도 전송하지 않는다. 반대로 말하면 로그가 없는 환경 (다른 머신이나 Web 버전)에서는 집계할 수 없으며, 어디까지나 "해당 머신에서의 Claude Code 이용" 집계라는 점은 유의해 두자.

4. 상시 표시하기 — 스테이터스 라인(Status Line)에 Ctx / 5h / Wk 표시

이 부분이 가장 실용적이다. 터미널 하단의 스테이터스 라인(Status Line)에 잔량을 상시 표시한다. 이 글도 바로 이 기능을 띄워놓은 상태로 작성하고 있으며, 실제 표시 모습은 다음과 같다:

Opus 4.8 | nova-workspace | main | Ctx 83% | 5h 61% (1h58m) | Wk 45% (월 17:00)

위와 같은 구성으로, 왼쪽부터 모델 / 작업 디렉토리 / git 브랜치 / 컨텍스트 잔량(Ctx) / 5시간 한도(사용률과 남은 시간) / 주간 한도(사용률과 리셋 시각) 순서다. 제한과 관련된 세 가지 요소(Ctx·5h·Wk)와 리셋까지 남은 시간이 항상 눈에 들어오기 때문에, 굳이 /usage 명령어를 입력하지 않아도 잔량을 알 수 있다.

원리: statusLine 명령에 JSON이 전달됨

Claude Code의 statusLine에 「명령어」를 지정하면, 해당 명령어의 표준 입력(Standard Input)으로 세션 상태가 담긴 JSON이 전달되며, 표준 출력(Standard Output)으로 나오는 문자열이 그대로 한 줄로 표시된다. 이 JSON 안에 바로 잔량 정보가 들어 있다:

{
"model": { "display_name": "Opus 4.8" },
"workspace": { "current_dir": "/path/to/nova-workspace" },
...
}

context_window(컨텍스트 잔량)와 rate_limits(/usage와 동일한 5시간 한도·주간 한도 수치)를 추출하여 정렬하기만 하면 된다. 외부 도구나 유료 결제도 필요 없다. 게다가 각 한도에는 resets_at (리셋 시각의 Unix epoch 초 단위 값) 도 포함되어 있으므로, /usage를 열지 않고도 「앞으로 몇 분 뒤에 5시간 한도가 회복되는지」까지 스테이터스 라인에 표시할 수 있다.

rate_limits는 claude.ai 유료 사용자(Pro/Max)이며, 세션 첫 API 응답 이후에만 나타난다. 각 한도는 독립적으로 소진될 수 있으므로 ?. (Optional Chaining)를 사용하여 에러를 방지한다.

설정

~/.claude/settings.json (프로젝트 단위라면 .claude/settings.json)에 명령어를 등록한다:

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

refreshInterval은 「이벤트가 없더라도 지정된 초마다 재실행」하는 설정이다. 리셋까지 남은 시간과 같은 시간 표시를 작업 중에도 계속 업데이트하고 싶으므로 설정해 두는 것이 좋다.

지정한 statusline-command.js는 위의 JSON을 조합하여 | 구분자로 출력하기만 하면 된다. resets_at(epoch 초)으로부터 남은 시간 및 리셋 시각을 계산한다:

#!/usr/bin/env node
"use strict";
const path = require("path");
...

이렇게 하면 다음과 같이 표시된다 (5시간 한도는 「앞으로 1시간 58분 남음」, 주간 한도는 「월요일 17:00에 리셋」):

Opus 4.8 | nova-workspace | main | Ctx 83% | 5h 61% (1h58m) | Wk 45% (월 17:00)

• Ctx는 잔량, 5h와 Wk는 사용된 비율이다. 5시간 한도는 상대적 시간(남은 시간)으로, 주간 한도는 며칠 뒤의 일이므로 절대적 시간(요일+시각)으로 표시하는 것이 읽기 편하다.
• 임계값에 따라 색상을 입히거나, git 브랜치(git branch --show-current)를 추가하는 것도 자유롭다.
• /statusline 명령어를 통해 대화형으로도 만들 수 있다. 「모델과 브랜치, 사용률과 리셋 시각을 보여줘」라고 자연어로 요청하면 이와 같은 스크립트를 생성해 준다.

이를 통해 제한에 걸리기 전에 /compact를 실행할지, 아니면 모델을 낮출지를 화면을 보는 것만으로 판단할 수 있게 된다.

비용 내역까지 보고 싶다면 ccusage

한도의 잔량(%)이 아니라 「얼마나 사용했는지(비용·토큰)」를 상시 표시하고 싶다면, 앞서 언급한 ccusage에도 statusline 서브 명령어가 있다:

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

이 경우 💰 $0.23 session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr 와 같이 표시된다.

이와 같이 비용 중심의 표시가 된다. 잔량 관리가 목적이라면 내장 JSON 방식, 비용 파악이 목적이라면 ccusage를 선택한다 (두 가지를 하나의 스크립트로 합칠 수도 있다).

요약

현재 대화의 무게 → /context
내용이 불어나면 /compact 또는 /clear 사용

플랜 잔량 및 리셋 시각 → /usage
5시간 단위 프레임과 주간 프레임의 2개 게이지를 확인

일/주/월간 소비량 및 비용 → npx ccusage@latest

상시 표시 → settings.json의 statusLine에 스크립트를 설정하여, 전달되는 JSON의 context_window 및 rate_limits를 출력. Ctx / 5h / Wk를 항상 확인할 수 있으면 제한 관리가 훨씬 쉬워진다 (비용을 중시한다면 ccusage statusline 사용).

이 기사는 Claude Code를 최대한 활용하며 개인적으로 Web 툴을 대량 생산하는 과정에서 쌓인 메모입니다. 제작한 툴 모음과 대량 생산 기록은 Novare Orbis에서 공개하고 있습니다. 괜찮으시다면 한 번 둘러봐 주세요.

Discussion