ccusage: 클로드 코드 토큰 사용량과 비용을 한눈에

클로드 코드를 쓰다 보면 어느 순간 궁금해지는 게 있어요. 이번 달에 토큰을 얼마나 썼지? 비용은 얼마쯤 나왔을까? 세션 중에 /cost로 현재 비용을 확인할 수는 있는데, 지난주 월요일에 얼마를 썼는지나 프로젝트별 비용 분포는 알기 어렵죠.

ccusage는 이 질문들에 답해주는 CLI 도구예요. 클로드 코드가 로컬에 남기는 세션 로그 파일을 분석해서 일별, 월별, 세션별 토큰 사용량과 비용을 테이블 형태로 보여줘요. 설치할 필요도 없이 npx 한 줄이면 바로 실행할 수 있어서 진입 장벽이 거의 없어요.

바로 실행해보기

ccusage는 npm 패키지로 배포되어 있어서 별도 설치 없이 바로 실행할 수 있어요. 사용하는 패키지 매니저에 따라 아래 명령어 중 하나를 실행하면 돼요.

npx ccusage@latest

bunx ccusage@latest

pnpm dlx ccusage@latest

@latest를 붙이는 게 좋은데, ccusage는 업데이트가 활발한 프로젝트라서 새 기능이나 버그 수정이 자주 나오거든요.

명령어를 실행하면 기본적으로 일별 사용량 리포트가 출력돼요. 날짜별로 모델, 입력/출력 토큰, 비용을 깔끔한 테이블로 보여줘요.

리포트 형식

ccusage는 데이터를 보고 싶은 관점에 따라 여러 리포트 형식을 제공해요.

가장 기본적인 건 일별 리포트예요.

bunx ccusage@latest daily

날짜별로 토큰 사용량과 비용이 집계되니까 “오늘은 얼마 썼지?”나 “이번 주에 어느 날이 가장 많이 썼나?” 같은 질문에 바로 답할 수 있어요.

월 단위로 큰 그림을 보고 싶으면 monthly 명령어를 쓰면 돼요.

bunx ccusage@latest monthly

월별 총 사용량이 나오니까 비용 추세를 보기 좋아요. 팀에 비용 보고를 해야 한다면 이걸로 스크린샷 찍으면 돼요.

세션 단위로 보고 싶을 때는 session을 쓰면 돼요.

bunx ccusage@latest session

각 대화 세션별로 토큰과 비용이 집계돼요. “아까 그 긴 리팩토링 세션에서 토큰을 얼마나 썼을까?” 같은 궁금증을 해소할 수 있죠.

Claude.ai 구독자라면 blocks 명령어가 특히 유용할 거예요.

bunx ccusage@latest blocks

Claude의 5시간 빌링 윈도우 단위로 사용량을 보여줘요. Pro나 Max 플랜은 5시간마다 사용 한도가 리셋되니까, 현재 윈도우에서 얼마나 썼는지 파악하면 한도에 걸리기 전에 대응할 수 있어요.

주별로 묶어 보고 싶으면 weekly도 있고요.

bunx ccusage@latest weekly

무엇을 보고 싶냐에 따라 골라 쓰면 돼요. 주간 회고 때는 weekly, 청구서 검토 때는 monthly 식으로요.

기간 필터링과 출력 형식

전체 기간이 아니라 특정 기간만 보고 싶을 때는 --since와 --until 옵션을 쓰면 돼요.

bunx ccusage@latest daily --since 20260401 --until 20260404

날짜 형식은 YYYYMMDD예요. 이번 주 사용량만 보거나 지난달 비용만 뽑아볼 때 유용해요.

데이터를 프로그래밍적으로 처리하고 싶으면 --json 옵션으로 JSON 형식으로 출력할 수 있어요.

bunx ccusage@latest daily --json > usage.json

이러면 테이블 대신 JSON이 나오니까 스크립트에서 파싱하거나 스프레드시트, 대시보드에 연동하기 좋아요.

모델별 비용 상세 보기

어떤 모델이 비용을 얼마나 잡아먹고 있는지 궁금하면 --breakdown 옵션을 써보세요.

bunx ccusage@latest daily --breakdown

Opus, Sonnet, Haiku 같은 모델별로 비용이 분리되어 나와요. 모델 전환을 자주 하는 편이라면 어떤 모델이 비용의 대부분을 차지하는지 확인해서 최적화 포인트를 찾을 수 있어요.

프로젝트별 사용량 분석

여러 프로젝트를 오가며 클로드 코드를 쓰고 있다면 프로젝트별로 사용량을 분리해서 보고 싶을 거예요.

bunx ccusage@latest daily --instances

--instances 옵션을 주면 프로젝트(인스턴스)별로 그루핑해서 보여줘요. 특정 프로젝트만 필터링하고 싶으면 --project 옵션을 쓰면 돼요.

bunx ccusage@latest daily --project my-app

이러면 my-app 프로젝트의 사용량만 나와요. 여러 클라이언트 프로젝트를 동시에 진행하고 있다면 이 옵션으로 비용을 깔끔하게 분리할 수 있어요.

시간대와 로케일 설정

기본적으로 ccusage는 시스템 시간대를 사용하는데, UTC 기준으로 보고 싶거나 다른 시간대로 그룹핑하고 싶으면 --timezone 옵션을 쓰면 돼요.

bunx ccusage@latest daily --timezone Asia/Seoul

날짜와 시간 형식을 지역에 맞게 표시하려면 --locale 옵션도 있어요.

bunx ccusage@latest daily --locale ko-KR

팀원이 여러 시간대에 분산되어 있다면 같은 기준으로 데이터를 맞출 때 유용해요.

테이블 레이아웃과 오프라인 모드

ccusage는 터미널 너비에 맞게 자동으로 테이블 레이아웃을 조정해요. 터미널이 100자 이상이면 캐시 토큰까지 포함한 풀 레이아웃을, 그보다 좁으면 핵심 정보만 담은 컴팩트 레이아웃을 보여줘요.

강제로 컴팩트 모드를 쓰고 싶으면 --compact 옵션을 주면 돼요.

bunx ccusage@latest daily --compact

네트워크 연결 없이도 동작하게 하려면 --offline 옵션이 있어요.

bunx ccusage@latest daily --offline

ccusage는 모델 가격 정보를 가져오기 위해 네트워크를 사용하는데, --offline을 주면 미리 캐시된 가격 데이터를 써요. 비행기 안에서도 사용량 리포트를 돌릴 수 있는 셈이죠 😅

Statusline 통합

ccusage는 클로드 코드 statusline과도 연동할 수 있어요.

bunx ccusage@latest statusline

이 명령어는 statusline 훅용 컴팩트 형식으로 현재 사용량을 출력해요. 클로드 코드 하단에 토큰 사용량과 비용을 실시간으로 띄워두고 싶다면 딱 맞아요. 아직 베타 기능이긴 하지만 세션 진행 상황을 한눈에 파악하기에 좋아요.

MCP 서버로 사용하기

ccusage를 MCP 서버로도 쓸 수 있어요. @ccusage/mcp 패키지를 쓰면 Claude Desktop에서 ccusage 데이터를 직접 조회할 수 있어요.

Claude Desktop에서 “이번 주 토큰 사용량 알려줘”라고 물어보면 ccusage MCP 서버가 데이터를 가져와서 자연어로 답변해주는 식이에요. CLI를 매번 실행하는 대신 대화형으로 사용량을 조회하고 싶은 분들에게 편리한 방식이죠.

관련 도구들

ccusage 생태계에는 Claude Code 외의 AI 코딩 도구를 위한 사용량 분석기도 있어요.

• @ccusage/codex — OpenAI Codex 사용량 추적
• @ccusage/opencode — OpenCode 사용량 분석
• @ccusage/amp — Amp CLI 세션 모니터링
• @ccusage/pi — Pi-agent 세션 추적

여러 AI 코딩 도구를 병행해서 쓰고 있다면 각각의 사용량을 동일한 형식으로 분석할 수 있다는 게 장점이에요.

마치며

AI 코딩 도구를 쓰면서 비용 관리를 안 하는 건 택시 미터기를 안 보고 타는 것과 비슷해요. 목적지에 도착하고 나서야 요금에 깜짝 놀라게 되죠. ccusage는 그 미터기 역할을 해줘요. 일별, 월별, 세션별로 토큰 사용량과 비용을 한눈에 보여주니까 어디에 얼마를 쓰고 있는지 투명하게 파악할 수 있어요.

--breakdown이랑 --instances를 같이 쓰면 “어떤 프로젝트에서 어떤 모델이 돈을 쓰고 있는지”가 한눈에 들어와요. 비용이 생각보다 많이 나왔다면 거기서 최적화 포인트를 찾을 수 있어요.

설치 없이 npx ccusage@latest 한 줄이면 바로 확인할 수 있으니까 한번 돌려보세요. 지금까지 클로드 코드를 얼마나 썼는지 숫자로 확인하는 순간이 꽤 흥미로울 거예요.

더 자세한 내용은 ccusage 공식 문서를 참고하세요.