ccusage로 Claude Code 실제 지출을 먼저 보고, 과금 방식을 결정하라
'이번 달 비싼 느낌'은 데이터가 아니다. ccusage는 로컬 세션 로그를 읽어 공개 정가로 환산한다: 한 줄 명령으로 시작하고, 그 숫자가 무슨 가격인지 이해하고, 일주일을 돌려 자기 사용 형태를 얻는다—그 형태가 구독인지 종량인지 답해준다.
Claude Code를 쓰는 사람이라면 누구나 같은 순간의 의심을 한다: 이번 달, 쓴 게 과했나? 의심은 대개 느낌에서 멈춘다. 다음 단계가 어색하기 때문이다—구독자에게는 청구서가 없고 진행 바만 있다. API 사용자에겐 청구서가 있지만 보는 건 한 달 끝. 사실 답은 줄곧 자기 컴퓨터 안에 있다: Claude Code는 매 세션의 사용량을 로컬 로그에 기록하고, ccusage가 그 장부를 읽어주는 가장 간단한 도구다. 이 글은 ccusage 설명서가 아니다—명령은 한 줄이라 설명서가 필요 없다. 잰 다음의 이야기다: 그 숫자는 어떤 가격으로 계산되는지, 어떤 숫자를 봐야 하는지, 그리고 일주일 측정이 '어떻게 지불해야 하는가'에 어떻게 답하는지.
먼저 밝힙니다: 나는 종량 과금 API 게이트웨이 Teapot Router를 운영한다. '구독인지 종량인지 정하는 법'을 쓰는 건 명백히 내 이해관계다—그래서 앞의 네 절은 어떤 사업자에도 의존하지 않는 자기 숫자만의 이야기이고, 이해관계 부분은 마지막 절에 있으며 그 판단 기준은 모두 공개되어 다시 계산할 수 있다.
'비싼 느낌'은 데이터가 아니라, 로컬 로그가 데이터다
Claude Code는 매 세션을 ~/.claude 아래 JSONL 파일에 기록한다: 어떤 요청에 어떤 모델을 썼고, 입력·출력 토큰이 얼마이고, 캐시가 얼마나 적중했는지. 로그는 설치 첫날부터 쌓여서, 사고라도 나지 않는 한 지난 몇 주의 사용량이 전부 거기 있다.
ccusage가 하는 일은 놀랍도록 소박하다: 그 로그를 읽고 가격표를 곱해 날짜별·주별·세션별로 편다. 아무것도 업로드하지 않고, API 키를 요구하지 않고, 설정을 바꾸지도 않는다—필요 없기 때문이다: 장부와 산술 모두 자기 컴퓨터 안에서 끝난다.
한 줄로 시작, 알아둘 세 가지 뷰
설치 불필요, npx ccusage daily로 바로 돈다. 일상에서 알아둘 가치가 있는 뷰는 세 가지이고 각각 하나의 질문에 답한다:
- daily: 하루당 지출—'어느 날 태웠나'에 답한다.
- blocks: 5시간 과금 블록 단위 구분—구독 한도 창에 맞춘 시점으로, 무거운 작업이 어디에 떨어지는지 보여준다.
- monthly: 월 단위 합산—'지불 방식을 바꿔야 하나'를 묻기 전에 먼저 본다.
계산에 쓰이는 건 '정가'—모두가 건너뛰는 단계
ccusage가 곱하는 건 공식 정가표다. 여기에 결정적 구별이 따른다: 구독자라면 그 숫자는 당신이 낸 돈이 아니다(내는 건 고정 월액이다)—그것은 '이 사용량을 API 정가로 환산하면 얼마'라는, 사용량을 재는 자이지 청구서가 아니다. API 사용자라면 청구서의 근사값이다—근사라 하는 건 캐시 읽기/쓰기 과금이 사업자의 정확한 명세와 세부에서 다를 수 있어서고, 요청 단위 명세가 여전히 정확한 출처다.
이 구별은 트집이 아니라 다음 단계로 들어가는 문이다: ccusage 출력을 '청구서'가 아니라 '사용 형태'로 읽을 때, 숫자가 당신 대신 결정하기 시작한다.
일주일 돌리면, 합계 이상이 손에 들어온다
합계는 비싼지만 알려준다. 형태는 왜 비싼지, 다른 과금 방식이면 싸질지 알려준다. 일주일 돌리고 출력에서 네 가지 형태 변수를 읽어라: 하루 집중 시간(blocks의 시간 폭), 작업 강도(플래그십인지 균형 모델이 주인지), 캐시 적중률(같은 컨텍스트도 적중과 콜드는 한 자릿수 다르다), 그리고 산의 형태(매일 고른지, 이틀만 터지는지). 이 네 개가 월 합계보다 훨씬 쓸모 있다—모든 과금 방식의 차이가 이 네 축을 따라 펼쳐지기 때문이다.
형태에서 결정으로: 그 산술의 생김새
형태가 있으면 구독 대 종량은 진영 싸움이 아니라 대입 가능한 곱셈이 된다: '하루 시간 × 강도'를 비용 계산기에 넣어 종량 월액을 내고, 구독 월액 옆에 놓는다. 아래면 종량이 이득, 위면 '상한 없음을 종량 가격으로 사는 중'이다—그것도 말은 되지만, 이제는 알고 하는 선택이다.
이해관계 부분은 분명히: 우리 스스로 이걸 위한 계산기와 요청 단위 명세를 유지한다—요금은 공개 가격 엔드포인트에서 실시간으로, 각 요청의 비용은 나중에 확인·내보내기 가능하다. 하지만 우리를 쓸 필요는 없다: 기계 판독 가격표와 요청 단위 명세를 내주는 사업자라면 누구나 같은 산술을 할 수 있다. 그 둘을 내주지 않는 곳은 요금표가 아무리 싸 보여도 '검증 불가' 자체를 비용으로 계상해야 한다.
ccusage의 가치는 명령이 아니라 '느낌'을 '형태'로 바꾸는 것이다. 일주일 재고 네 숫자를 기억하라: 시간, 강도, 적중률, 산과 골. 이 네 개가 있으면 어떤 과금 세일즈도—우리 것 포함—겁줄 수 없다. 답은 스스로 곱한 것이니까.
자주 묻는 질문
ccusage는 무료인가? 네트워크나 API 키가 필요한가?
무료 오픈소스다. ~/.claude 아래 세션 로그만 읽고 로컬에서 계산한다—업로드 없음, 키 불필요, 설치 없이 npx로 바로 돈다.
구독 사용자에게 그 숫자는 청구서인가?
아니다. 구독자가 보는 건 '이 사용량을 공식 API 정가로 환산한 등값'으로 사용 형태를 재는 자다. 실제로 내는 건 고정 월액이다. API 사용자에겐 청구서의 근사값이며, 정확한 출처는 사업자의 요청 단위 명세다.
Claude Code 내장 /usage와 뭐가 다른가?
/usage는 현재 한도 창의 잔량과 소비를 보여주는 '지금' 계기다. ccusage는 기록 로그를 모아 날짜·월·블록별 전체 회고를 준다. 하나는 현재를, 하나는 과거를 관할한다—지불 방식 결정에 필요한 건 후자다.