ccusage 소개
최근 AI 모델을 활용한 개발이 늘어남에 따라, 사용량 및 비용을 정밀하게 관리하는 도구에 대한 수요가 높아지고 있습니다. 특히 Anthropic의 Claude 모델, 특히 Claude Code를 사용하는 개발자라면, API 호출이 얼마나 이루어졌고 어떤 모델이 얼마나 비용을 유발했는지를 파악하는 것은 매우 중요한 관리 포인트입니다. ccusage는 바로 이런 요구를 충족시키기 위해 만들어진 경량화된 CLI 도구입니다. 사용자의 컴퓨터에 저장된 JSONL 로그 파일(~/.claude.json)을 기반으로 Claude API의 사용량과 비용을 빠르고 직관적으로 분석할 수 있도록 도와줍니다.
ccusage는 경량화된 바이너리를 제공하여 설치 없이도 바로 실행이 가능하며, 다양한 뷰(일별, 월별, 세션별, 프로젝트별 등)를 통해 데이터를 시각화합니다. 특히 실시간 모니터링 기능까지 제공되어, Claude API 사용량을 지속적으로 트래킹하고자 하는 개발자들에게 큰 도움을 줄 수 있습니다. 또한, 특정 프로젝트 단위로 분석하거나 모델별로 비용을 분류할 수 있는 기능도 있어 팀 단위의 비용 관리에도 적합합니다.
이 도구는 번들 사이즈가 매우 작기 때문에, npx, bunx, deno를 통해 즉시 실행 가능하며, 특별한 환경 구성 없이도 간편하게 활용할 수 있습니다. Claude API를 자주 사용하는 사용자라면 반드시 눈여겨볼 만한 유틸리티입니다.
ccusage는 기존에 존재하던 로그 분석 도구들과 비교해도 매우 경량화되어 있으며, 실시간 대시보드나 모델별 비용 분해 기능과 같은 세부 기능들이 탑재되어 있다는 점이 큰 강점입니다. 예를 들어 OpenAI 관련 CLI 분석 도구들 중 일부는 로그 포맷 제한이 있거나, 실시간 기능이 없고 시각화가 부족한 경우가 많습니다.
ccusage는 Claude 모델 전용 분석에 초점을 맞추고 있으며, ClaudeLog와 같은 커뮤니티 도구들과도 연계되어 있어 Claude 사용 문화를 잘 반영하고 있습니다. 또한 MCP 서버 통합 기능을 통해 외부 툴과도 쉽게 연동될 수 있다는 점도 타 도구와 차별화되는 부분입니다.
ccusage의 주요 기능 및 사용 방법
설치 및 실행
ccusage는 번들 크기가 매우 작아 설치 없이도 npx, bunx, 또는 deno를 이용해 곧바로 실행할 수 있습니다. 다음 명령어 중 하나를 실행하여 바로 실행해볼 수 있습니다:
# bunx 사용 시 (권장)
bunx ccusage
# npx 사용 시
npx ccusage@latest
# pnpm 사용 시
pnpm dlx ccusage
# deno 사용 시
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest
사용자의 컴퓨터에 바이너리를 설치하려면 다음과 같은 설치 명령어를 실행합니다:
# npm 사용 시
npm install -g ccusage
# bun 사용 시
bun install -g ccusage
# yarn 사용 시
yarn global add ccusage
# pnpm 사용 시
pnpm add -g ccusage
설치 후에는 다음과 같은 명령어로 바로 실행해볼 수 있습니다:
ccusage daily
ccusage monthly --breakdown
ccusage blocks --live
사용 예시
다양한 명령어를 통해 로그를 시각화할 수 있습니다:
ccusage daily # 일별 사용량 및 비용
ccusage monthly # 월별 통계
ccusage session # 세션별 통계
ccusage blocks # 5시간 단위 청구 구간
ccusage blocks --live # 실시간 대시보드
ccusage daily --since 20250801 --until 20250815 --breakdown
또한 JSON 출력, 프로젝트 필터링, 시간대/로케일 설정 등의 다양한 옵션도 제공합니다.
주요 기능
- 실시간 모니터링: API 호출 상황을 실시간으로 추적 가능
- 모델별 분석: Claude Opus, Sonnet 등 모델별 사용량/비용 확인
- 다양한 출력 옵션: 컬러 테이블, JSON 포맷, 상태바 통합 등
- 오프라인 모드: 캐시된 가격 데이터를 이용한 분석 가능
- 프로젝트 기반 그룹화: 인스턴스 또는 프로젝트별 통계 지원
- 초소형 번들: 설치 없이 빠르게 실행 가능
라이선스
ccusage 프로젝트는 MIT 라이선스로 공개 및 배포되고 있습니다. 상업적 사용에 제한이 없습니다.
ccusage 홈페이지 (및 문서)
ccusage 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 