ccusage의 개요
ccusage는 Claude Code 등 에이전트 CLI가 사용자의 머신에 남기는 사용 로그를 읽어 일, 주, 월, 세션 단위로 토큰과 추정 비용을 보고합니다. Claude Code의 경우 5시간 과금 블록을 실시간 보기와 함께 보여 주고, Claude Code 상태 표시줄용 간결한 statusline(베타)도 제공합니다.
`npx ccusage@latest`(또는 bunx, pnpm dlx, Nix)로 실행하며 계정이나 API 키가 필요 없습니다. README는 Claude Code, Codex, OpenCode, Amp, Goose, Kilo, Gemini CLI, GitHub Copilot CLI를 포함한 18개 소스를 나열합니다. 가격은 LiteLLM, models.dev, 내장된 과거 요금표에서 가져와 로컬에 캐시하며, `--offline` 모드도 있습니다.
ccusage, 쓸 만한 가치가 있습니까?
ccusage는 코딩 에이전트 사용량의 기본 로컬 계량기가 되었습니다. GitHub 스타는 약 19,100개이고, npm은 2026년 10월 18일까지 30일 동안 약 871,000회 다운로드를 집계했으며, 거의 매일 출시됩니다. 10월 15일 v20.0.34부터 10월 22일 v20.0.41까지입니다. ryoppippi가 시작했고 지금은 ccusage 조직 아래에 있으며, 코드베이스는 Rust이지만 여전히 npm으로 배포됩니다.
비용 열은 주의해서 읽어야 합니다. 기본 auto 모드는 Claude Code가 저장한 costUSD가 있으면 그것을 쓰고, 없으면 토큰에 공개된 토큰당 가격을 곱합니다. 문서는 비용이 "실제 청구액을 반영하지 않을 수 있다"고, 웹 검색 같은 도구 호출은 포함하지 않는다고 분명히 말합니다. Pro나 Max 구독이라면 이 수치는 청구서가 아니라 같은 작업을 종량제 요금으로 했을 때의 비용입니다.
덜 눈에 띄는 한계 는 기록입니다. Claude Code는 기본적으로 로컬 대화 기록을 30일 동안 보관하며(cleanupPeriodDays 설정), ccusage는 디스크에 남아 있는 것만 셀 수 있습니다. 분기 추세를 보고 싶다면 먼저 그 설정을 늘리거나, 정기적으로 `--json` 스냅숏을 내보내야 합니다.
문서에 따르면 사용 데이터는 머신 밖으로 나가지 않지만, ccusage는 기본적으로 네트워크로 가격 캐시를 갱신합니다. `--offline`이 이를 멈춥니다. 보고서는 모델별로 입력, 출력, 캐시 생성, 캐시 읽기 토큰을 나누는데, 프롬프트 캐싱 변경이나 토큰 절약 플러그인이 정말 도움이 됐는지 판단하려면 바로 이 구분이 필요합니다.
범위는 머신 한 대입니다. 문서화된 서버나 팀 보기가 없으므로, 개발자 열 명을 비교하려는 매니저는 JSON 파일 열 개를 손으로 모아 합쳐야 하고, 각각은 해당 노트북의 로그 보존 기간만큼만 완전합니다.
제 역할을 하는 곳
RTK 같은 토큰 절약 플러그인을 시험하는 개발자
정말 사용량이 줄어드는지 증명하기
설치 전 1주와 설치 후 1주 동안 `ccusage daily --json`을 실행하고, 모델별 입력 토큰과 캐시 읽기 토큰을 비교합니다. 몇 분이면 되고 비용은 없으며, 비교의 공정성은 두 주의 작업량이 얼마나 비슷한지에 달려 있습니다.
Claude Max 좌석 비용을 내는 엔지니어링 매니저
팀을 API 과금으로 옮기는 편이 더 저렴한지 판단하기
개발자마다 `ccusage monthly --json`을 실행해 파일을 공유하면, 합계가 같은 사용량을 API 요금으로 냈을 때의 비용을 보여 줍니다. 공유 보기가 없으므로 파일을 모아 합치는 일은 수작업입니다.
여러 고객에게 청구하는 프리랜서 개발자
에이전트 비용을 고객 프로젝트별로 배분하기
`ccusage claude daily --instances --project <name>`이 Claude Code 사용량을 프로젝트별로 묶습니다. 계약이 도구 비용을 실비로 청구한다면 API 기준 수치는 근거 있는 청구 항목이 됩니다.
도입 전 확인할 점
- 설정
- `npx ccusage@latest`는 몇 초 만에 일별 보고서를 출력합니다. bunx는 패키지를 캐시하므로 반복 실행이 더 빠릅니다. 실시간 수치를 보려면 Claude Code의 status line 훅에 `ccusage statusline`을 추가합니다.
- 연동
- Claude Code(~/.claude와 ~/.config/claude/projects), Codex, OpenCode, Gemini CLI, Copilot CLI를 포함한 에이전트 CLI 18개의 로컬 로그를 읽습니다. 표나 JSON으로 출력하며, 가격 재정의는 ccusage.json에 둡니다.
- 데이터와 개인정보
- 문서에 따르면 분석은 로컬에서 이뤄지고 사용 데이터는 업로드되지 않습니다. 가격 데이터는 --offline을 주지 않으면 가져와서 캐시합니다. MIT 라이선스이므로 상업적 사용에 제한이 없습니다.
- 대규모 사용 시 비용
- 무료이며 유료 버전은 없고, 후원으로 운영됩니다. 유일한 비용은 집계하고 싶은 모든 머신에서 이를 돌리는 습관입니다.
- 제한
- 달러 수치는 웹 검색을 제외한 추정치입니다. cleanupPeriodDays를 늘리지 않으면 Claude Code는 30일 뒤 대화 기록을 지웁니다. 팀 단위 집계가 없습니다. 마지막 확인 시점의 열린 이슈는 4개뿐입니다.
좋은 점
- 계정 없이 완전히 로컬에서 보고
- 에이전트 CLI 18 개를 보고서 하나로
- 모델별로 캐시 생성 토큰과 캐시 읽기 토큰 구분
- 5시간 블록 보기, statusline, --json 출력
아쉬운 점
- 비용은 API 기준 추정치이며 웹 검색 제외
- 기록이 에이전트가 디스크에 남기는 범위로 제한(Claude Code는 기본 30일)
- 팀 또는 서버 모드 없음
추천 대상
에이전트 세션 간 토큰 사용량을 추적하거나 비교하려는 모든 사람.
ccusage 대안
ccusage: 자주 묻는 질문
- ccusage, 쓸 만한 가치가 있습니까?
- ccusage는 에이전트를 많이 쓰는 사람이라면 누구나 돌려야 할 계량기입니다. 다만 달러 열은 실제로 낸 돈이 아니라 같은 작업을 API로 했을 때의 비용으로 읽어야 합니다. 평점은 5점 만점에 4.4점입니다.
- ccusage의 가격은 얼마입니까?
- 무료 오픈소스(MIT)입니다.
- ccusage의 단점은 무엇입니까?
- 비용은 API 기준 추정치이며 웹 검색 제외; 기록이 에이전트가 디스크에 남기는 범위로 제한(Claude Code는 기본 30일); 팀 또는 서버 모드 없음.
- ccusage에 적합한 사람은 누구입니까?
- 에이전트 세션 간 토큰 사용량을 추적하거나 비교하려는 모든 사람.
- 팀이나 프로덕션 환경에서 ccusage의 비용은 얼마입니까?
- 무료이며 유료 버전은 없고, 후원으로 운영됩니다. 유일한 비용은 집계하고 싶은 모든 머신에서 이를 돌리는 습관입니다.
- ccusage에 회사 데이터를 맡겨도 안전합니까?
- 문서에 따르면 분석은 로컬에서 이뤄지고 사용 데이터는 업로드되지 않습니다. 가격 데이터는 --offline을 주지 않으면 가져와서 캐시합니다. MIT 라이선스이므로 상업적 사용에 제한이 없습니다.
- ccusage의 가장 좋은 대안은 무엇입니까?
- 저희가 리뷰한 것 중 가장 가까운 대안은 rtk (Rust Token Killer), Claude Code Router 및 mindwalk입니다.
답변 확인일: 2026년 10월 23일.
ccusage 개발사입니까? 이 평점을 사이트에 표시하십시오
