Claude Code 사용량 확인법: /usage 화면과 5시간·주간 한도

Claude Code를 오래 붙잡고 있으면 “한도에 가까워졌다”는 경고가 한 번쯤 뜹니다. 그래서 /usage를 열어 보면 숫자 덩어리가 네 개나 있고, 서로 맞지 않아 보여요. 어느 숫자를 봐야 남은 양을 알 수 있는지부터 헷갈리죠.

계정 전체의 남은 양을 정확히 보여 주는 건 그중 하나, 플랜 한도 막대입니다. 그리고 구독 한도는 요청 횟수가 아니라 토큰으로 줄고, 한 번 쓸 때마다 5시간 창과 주간 창에 같이 쌓입니다. 매번 창을 열기 번거롭다면 상태 표시줄에 rate_limits 값을 띄워 두면 됩니다.

2026년 9월 18일 공식 문서 기준입니다. Ubuntu 24.04 · Claude Code 2.1.276에서 예산 상한 플래그는 직접 실행해 확인했습니다.

10월 12일에는 Windows 11 · PowerShell 5.1 · Claude Code 2.1.296에서 claude -p "/usage" 출력, 예산 상한에 닿았을 때의 동작, PowerShell 상태 표시줄 스크립트를 확인했습니다.

/usage의 네 덩어리, 어느 숫자를 믿나

남은 양은 서버에서 받아 오는 플랜 한도 막대를 보면 됩니다. 네 덩어리가 어긋나 보이는 건 숫자를 가져오는 곳이 서로 달라서예요.

Windows에서 실제로 연 /usage 화면의 위쪽입니다. 맨 위가 세션 블록이고, 그 아래 막대 세 개가 플랜 한도예요. 주간 막대는 전체 모델 몫과 Fable 몫이 따로 있습니다. 그 아래의 사용 내역 부분은 생략했습니다.

덩어리	숫자 출처	믿을 범위
세션 블록(맨 위)	로컬 계산(정가 기준)	API 사용자용 추정치
플랜 한도 막대	서버	계정 전체
사용 내역	이 컴퓨터의 세션 기록	이 기기 사용분만
사용 크레딧 행	계정 크레딧 설정	크레딧을 켰을 때만 표시

사용 내역 숫자를 보면 되지 않나 싶지만, 거기에는 다른 기기와 claude.ai에서 쓴 양이 빠져 있습니다. 노트북과 데스크톱을 오가거나 claude.ai를 같이 쓴다면 비중이 실제와 달라져요. 그래서 저는 사용 내역을 무엇이 많이 썼는지 볼 때만 씁니다.

덩어리마다 알아 두면 좋은 것도 있습니다.

• 세션 블록은 이번 세션의 토큰과 달러 금액입니다. 이 금액은 청구액이 아니라 정가로 계산한 추정치라서, Pro·Max 구독자에게는 청구와 상관없는 숫자예요. 확정 청구액은 Claude 콘솔의 사용량 페이지에서 봅니다. 조직 관리 설정에 계약 단가 표가 있으면 그 단가로 계산하고, 계약 단가를 쓰는 조직이라면 /usage·상태 표시줄·OpenTelemetry 수치가 청구서와 맞지 않습니다. /clear로 새 세션을 시작하면 0달러부터 다시 셉니다(v2.1.211 이전에는 계속 누적).
• 플랜 한도 막대는 조회가 실패하면(대개 서버가 조회를 잠시 막을 때) 지난 60분 안에 받아 둔 마지막 막대를 Showing last-known usage 표시와 함께 보여 줍니다. r을 누르면 다시 불러와요.
• 사용 내역은 Pro·Max·Team·Enterprise에서 스킬·서브에이전트·플러그인·MCP 서버별 비중을 보여 줍니다. MCP 서버 몫은 그 서버의 도구 결과를 실제로 받아 쓴 요청만 셉니다. 긴 컨텍스트나 캐시 미스가 최근 사용량의 10% 이상이면 표시가 붙고, /loop 같은 예약 작업은 토큰을 많이 쓴 것부터 줄로 나옵니다(v2.1.242 이상). d·w로 최근 24시간과 7일을 오갑니다.
• 사용 크레딧 행은 Pro·Max에서 이번 달 지출과 월 상한을 보여 주고, 상한을 걸지 않았으면 금액 없이 Unlimited로 나옵니다.

스크립트에서는 claude -p "/usage"

창을 열 수 없는 스크립트에서도 남은 한도를 볼 수 있습니다. Windows에서 claude -p "/usage"를 실행하니 플랜 한도가 글자로 나왔어요. 숫자와 시각은 가렸습니다.

Current session: <n>% used · resets <날짜 시각> (<시간대>)
Current week (all models): <n>% used · resets <날짜 시각> (<시간대>)
Current week (Fable): <n>% used · resets <날짜 시각> (<시간대>)

그 아래 사용 내역 묶음의 첫머리에는, 이 숫자가 이 기기의 로컬 세션으로 낸 추정치이고 다른 기기와 claude.ai에서 쓴 양은 빠진다는 안내가 붙어 나와요. 위 표의 “이 기기 사용분만”이 바로 이 뜻입니다.

한도는 토큰으로, 두 창에 같이 쌓인다

Claude Code는 요청 횟수가 아니라 처리한 토큰으로 계산하고, 구독 플랜에는 시간이 흐르며 갱신되는 할당량이 들어 있습니다. 한 번 쓴 양이 5시간 창과 주간 창에 같이 쌓이기 때문에, 5시간 창이 리셋돼도 주간 쪽은 줄어든 채 남아요. 서브에이전트를 여러 개 띄우는 큰 작업 한 번이면 5시간 창이 리셋되기도 전에 주간 한도를 먼저 태울 수 있습니다.

직접 입력하지 않은 토큰도 같은 통에서 나갑니다. 서브에이전트, /loop 같은 예약 작업, 캐시가 식은 뒤 대화 전체를 다시 읽는 것까지 모두요.

에이전트 팀은 각자 컨텍스트를 가진 인스턴스를 여러 개 띄우니 활성 팀원 수와 각자 돈 시간에 비례해 토큰이 늘어납니다. 서브에이전트로 조사와 검토를 나누는 방법을 쓰고 있다면 이 몫이 가장 클 거예요.

사용 방식	한도 단위	상태 표시줄 rate_limits
claude.ai Pro·Max	구독에 든 갱신형 할당량	나옴
Team·Enterprise	좌석별 할당량(5시간·주간)	지원 목록에 없음
Claude 콘솔(API)·클라우드	토큰 단위 조직 청구	지출 한도 게이트웨이 뒤일 때만

Team·Enterprise의 좌석 할당량은 Claude 채팅·Cowork와 함께 쓰고, 크기는 좌석 등급(Standard 또는 Premium)에 따라 다릅니다. 구독과 API 키가 섞인 조직에서는 각 개발자가 로그인한 방식 기준으로 계산됩니다.

그럼 모델을 바꾸면 한도가 풀릴까요? 세션·주간 한도는 모든 모델이 함께 쓰므로 풀리지 않습니다. Opus·Sonnet 계열 한도라면 그 계열 밖 모델로 바꿔서 계속 쓸 수 있고요.

상태 표시줄에 남은 한도 띄우기

/usage를 매번 여는 대신 상태 표시줄에 띄워 두는 방법이 있습니다. 상태 표시줄 스크립트가 받는 JSON에 5시간 창과 주간 창의 사용률(0~100)과 리셋 시각이 들어 있거든요.

필드	뜻
rate_limits.five_hour.used_percentage	5시간 창 사용률
rate_limits.seven_day.used_percentage	주간 창 사용률
rate_limits.*.resets_at	리셋 시각(Unix epoch 초)

공식 예제는 jq로 값이 없으면 빈칸으로 둡니다. 값이 빠지는 경우가 꽤 많아서 이 처리는 빼지 마세요.

jq -r '.rate_limits.five_hour.used_percentage // empty'

값이 비는 건 이럴 때입니다.

• claude.ai Pro·Max 구독도 아니고 지출 한도가 걸린 Claude apps 게이트웨이 뒤도 아닐 때
• 세션의 첫 API 응답이 아직 오지 않았을 때
• 창(five_hour, seven_day, spend_limit)마다 따로 빠질 수 있고, resets_at이 지난 창은 사라짐

Windows에서는 jq 대신 PowerShell로

Windows에는 jq가 기본으로 없습니다. Git Bash에도 들어 있지 않아서 공식 예제를 그대로 쓰면 값이 안 나와요. 공식 문서의 PowerShell 예제를 고쳐 두 창의 사용률을 꺼내는 스크립트입니다.

$data = $input | Out-String | ConvertFrom-Json
$five = $data.rate_limits.five_hour.used_percentage
$week = $data.rate_limits.seven_day.used_percentage
$parts = @($data.model.display_name)
if ($null -ne $five) { $parts += "5h $([math]::Round($five))%" }
if ($null -ne $week) { $parts += "7d $([math]::Round($week))%" }
Write-Host ($parts -join ' | ')

~/.claude/statusline.ps1로 저장하고 설정 파일에서 powershell로 부릅니다.

{ "statusLine": { "type": "command", "command": "powershell -NoProfile -File C:/Users/YourName/.claude/statusline.ps1" } }

문서에 나온 JSON 모양으로 값을 넣어 보니 Opus 5.5 | 5h 23% | 7d 41%가 나왔고, rate_limits를 뺀 JSON에서는 Opus 5.5만 나왔습니다. 값이 빠져도 오류 없이 지나가는 거죠.

경로는 슬래시(/)로 적으세요.

Git Bash가 있으면 상태 표시줄 명령이 Git Bash로 도는데, 역슬래시로 적었더니 경로가 C:workusage-demostatusline.ps1처럼 붙어 버려 스크립트를 찾지 못했습니다.

Team 플랜인데 상태 표시줄에 한도가 안 나온다면 앞의 조건 때문입니다. rate_limits는 Team·Enterprise가 지원 목록에 없으니, 그때는 /usage의 플랜 한도 막대로 확인하세요. 상태 표시줄을 만드는 법은 Customize your status line에 언어별 예제가 있습니다.

“가득 찼다”는데 한도가 아닌 경우

“가득 찼다”는 말이 떠도 사용량 한도가 아닌 경우가 둘 있습니다. 메시지만 보고 리셋 시각을 기다리기 전에 무엇이 찬 건지부터 갈라 보세요.

메시지	실제 뜻	할 일
컨텍스트·자동 압축 경고	대화가 길어 요약할 시점	/compact·/clear
1M 컨텍스트 모델 선택 오류	기능 자격 확인	플랜·크레딧 확인
You've hit your … limit · resets …	플랜 사용량 한도	리셋까지 대기

1M 자격 오류는 세션·주간 할당량이 남아 있어도 납니다.

상태 표시줄에서도 컨텍스트는 context_window.used_percentage, 한도는 rate_limits로 필드가 다릅니다. exceeds_200k_tokens는 가장 최근 응답의 입력·캐시·출력 토큰 합이 20만을 넘었는지만 알려 주는 고정 기준이라 남은 한도와는 무관해요.

컨텍스트를 줄이는 법은 컨텍스트가 차면 생기는 일과 관리법에 있습니다.

한도에 걸린 뒤에는

창이 다 차기 전에 You've used 85% of your session limit · resets 3:45pm 같은 경고가 먼저 뜰 수 있습니다. 실제로 걸리면 메시지에 붙은 리셋 시각까지 요청이 막힙니다.

claude.ai 구독으로 로그인한 대화형 세션은 기본으로 그 자리에서 기다렸다가 리셋되면 작업을 이어 갑니다(v2.1.234 이상). 이때 마지막 메시지를 다시 보내는 게 아니라, 정해진 문구로 작업을 이어받게 해요. 이어서 또 한도에 걸리면 자동 대기를 연속 두 번까지만 다시 걸고, 그 뒤에는 멈추고 /rate-limit-options를 안내합니다.

메시지마다 무엇이 막혔는지는 한도·과부하 오류를 메시지별로 나누는 법에 정리했습니다.

스크립트 실행에는 금액 상한을 걸 수 있다

claude -p(--print)로 돌리는 비대화형 실행에는 --max-budget-usd로 달러 상한을 겁니다. 직접 실행해 claude --help에서 확인한 설명입니다.

  --max-budget-usd <amount>             Maximum dollar amount to spend on API
                                        calls (only works with --print)

이 상한은 --print 실행에서만 동작합니다. 평소의 대화형 세션에는 걸 수 없습니다.

상한에 닿으면 어떻게 끝나는지 Windows에서 일부러 0.0001달러를 걸어 봤습니다.

> claude -p "Write a 300-word story about a bear." --max-budget-usd 0.0001 --model haiku
Error: Exceeded USD budget (0.0001)

종료 코드는 1이었고, --output-format json으로 받으면 subtype이 error_max_budget_usd이고 답 본문(result)은 비어 있습니다. 눈여겨볼 건 실제로 나간 금액이에요. 상한은 0.0001달러였는데 기록된 비용은 0.003~0.004달러였습니다.

요청을 보내기 전에 막는 게 아니라, 한 번 쓰고 나서 넘었는지 보고 멈추는 겁니다. 그러니 상한은 요청 한 번 값만큼 여유를 두고 거세요. 0.05달러로 걸었을 때는 같은 요청이 약 0.003달러로 정상 종료(종료 코드 0)했습니다.

서브에이전트가 쓴 금액도 상한에 들어갑니다. 상한에 닿으면 새 서브에이전트 생성이 Budget limit reached로 실패하고, 돌고 있던 백그라운드 서브에이전트는 중단돼요(v2.1.217 이상).

다른 사람들이 겪은 문제

GitHub 이슈를 보면 숫자가 서로 달라 보인다는 보고와, 직접 입력하지 않은 토큰이 한도를 크게 줄였다는 보고가 반복해서 나옵니다. 아래 네 건 모두 열려 있으며 원인은 확정되지 않았습니다.

• navigatorpnw(2026-09-16, #94694): 주간 한도에 가까워졌다는 배너가 뜬 상태에서 사용량 팝업은 주간 54%였다고 보고했습니다. 배너에 숫자도, 어느 창인지도 없어 맞춰 볼 수 없었다고 적었습니다(데스크톱 앱 2.110.0, 번들 Claude Code 2.1.271, Windows 11, Max 플랜).
• nerdperegrino-png(2026-09-16, #94781): 서로 다른 사용량 수치가 둘 나와 무엇을 기준으로 할지 모르겠다고 보고했습니다(2.1.261, Windows).
• lucascampolina(2026-09-16, #94770): 서브에이전트를 분류 12개·집필 20개로 병렬로 띄웠더니 주간 Fable 5.1 할당량(그 모델 몫)의 약 70%가 나갔고, 도중에 429가 나며 결과 없이 끝난 호출이 27건이었다고 보고했습니다. 보고자의 우회법은 CLAUDE_CODE_SUBAGENT_MODEL=sonnet과 동시 실행 수·모델을 제한하는 규칙 파일입니다.
• vaishnavkoka(2026-09-17, #95222): 오래 쉰 뒤 캐시가 만료돼 다음 메시지가 약 80만 토큰을 다시 캐싱한다는 경고를 근거로, 이런 재캐싱이 한도를 과하게 줄여서는 안 된다고 주장했습니다. 환경은 CLI가 아니라 VS Code 확장의 에이전트 모드(2.1.251, Opus)입니다.

이 사례들을 보면서 저는 확인하는 순서를 정해 두는 게 낫다고 생각했습니다. 숫자가 어긋나 보이면 위 표에서 어느 덩어리의 숫자인지부터 가르고, 소진이 빠르면 사용 내역에서 서브에이전트·MCP 서버 비중을 보세요. 캐시가 언제 식는지는 프롬프트 캐싱이 실제로 싸지는 조건에 있습니다.

마치며

/usage 화면이 헷갈리는 건 숫자가 틀려서가 아니라, 네 덩어리가 서로 다른 곳에서 숫자를 가져오기 때문이었습니다. 계정 전체의 남은 양은 플랜 한도 막대로 보고, 사용 내역은 이 기기에서 무엇이 많이 썼는지 볼 때만 쓰면 덜 헷갈립니다. 한 번 쓴 양이 5시간 창과 주간 창에 같이 쌓이고, 서브에이전트처럼 직접 입력하지 않은 토큰도 들어간다는 것도 기억해 두세요.

지금 /usage를 열어 사용 내역에서 가장 큰 몫이 무엇인지 한 번 확인해 보시길 권합니다. 그 몫을 줄이는 방법은 토큰 절약 8가지를 직접 잰 글에 전후 숫자로 정리해 뒀습니다.