← 블로그 목록으로

Claude Code 사용량 확인하는 방법 - ccusage

Claude Code Korea··3분 읽기
#도구#사용량#모니터링#ccusage#CLI

Claude Code를 사용하다 보면 토큰 사용량과 비용이 궁금할 때가 있습니다. ccusage는 로컬 JSONL 파일에서 Claude Code 토큰 사용량과 비용을 분석하는 강력한 CLI 도구입니다.

설치 방법

빠른 시작 (권장)

ccusage는 매우 작은 번들 크기를 가지고 있어 설치 없이 바로 실행할 수 있습니다:

# bunx 사용 (속도가 빠름, 권장)
bunx ccusage

# npx 사용
npx ccusage@latest

# deno 사용 (보안 플래그 포함)
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest

💡 팁: 속도 향상을 위해 npx 대신 bunx 사용을 권장합니다!

로컬 설치 (선택사항)

ccusage는 번들 크기가 매우 작아 설치는 완전히 선택사항입니다:

npm install -g ccusage

사용법

기본 사용법

# 기본 사용
ccusage          # 일일 리포트 표시 (기본값)
ccusage daily    # 일일 토큰 사용량 및 비용
ccusage monthly  # 월별 집계 리포트
ccusage session  # 대화 세션별 사용량
ccusage blocks   # 5시간 빌링 윈도우
ccusage statusline  # 후크용 컴팩트 상태 라인 (베타)

실시간 모니터링

ccusage blocks --live  # 실시간 사용량 대시보드

필터 및 옵션

# 날짜 필터링
ccusage daily --since 20250525 --until 20250530

# 출력 형식
ccusage daily --json  # JSON 출력
ccusage daily --breakdown  # 모델별 비용 분석

# 시간대 및 로케일 설정
ccusage daily --timezone UTC  # UTC 시간대 사용
ccusage daily --locale ja-JP  # 일본어 로케일로 날짜/시간 포맷

프로젝트 분석

ccusage daily --instances  # 프로젝트/인스턴스별 그룹화
ccusage daily --project myproject  # 특정 프로젝트만 필터링
ccusage daily --instances --project myproject --json  # 조합 사용

주요 기능

📊 리포트 유형

  • 일일 리포트: 날짜별로 집계된 토큰 사용량과 비용 확인
  • 월별 리포트: 월별로 집계된 토큰 사용량과 비용 확인
  • 세션 리포트: 대화 세션별로 그룹화된 사용량 확인
  • 5시간 블록 리포트: Claude의 빌링 윈도우 내 사용량 추적

📈 모니터링 기능

  • 실시간 모니터링: blocks --live로 활성 세션 진행률, 토큰 소비율, 비용 예측을 실시간으로 확인
  • 상태 표시줄 통합: Claude Code 상태 표시줄 후크용 컴팩트 사용량 표시 (베타)

🤖 모델 추적

  • 사용 중인 Claude 모델 확인 (Opus, Sonnet 등)
  • --breakdown 플래그로 모델별 비용 분석
  • 모델명을 불릿 리스트로 표시하여 가독성 향상

📅 필터링 및 커스터마이징

  • --since와 --until로 날짜 범위 필터링
  • 커스텀 Claude 데이터 디렉토리 위치 지원
  • --timezone 옵션으로 시간대 설정
  • --locale 옵션으로 날짜/시간 포맷 커스터마이징

💰 비용 추적

  • 일/월/세션별 USD 비용 표시
  • 캐시 생성 및 캐시 읽기 토큰을 별도로 추적 및 표시

🎨 출력 옵션

  • 자동 반응형 레이아웃의 컬러풀한 테이블 형식
  • 좁은 터미널(< 100자)을 위한 자동 컴팩트 모드
  • --json으로 구조화된 JSON 형식 내보내기

🔌 고급 기능

  • 오프라인 모드: --offline으로 네트워크 연결 없이 미리 캐시된 가격 데이터 사용
  • MCP 통합: 다른 도구와의 통합을 위한 내장 Model Context Protocol 서버
  • 다중 인스턴스 지원: --instances 플래그로 프로젝트별 사용량 그룹화

문서 및 리소스

전체 문서는 ccusage.com에서 확인할 수 있습니다.

스폰서 및 관련 리소스

주요 스폰서

Greg Baugues의 47 Claude Code ProTips 확인해보세요.

Claude Code 리소스

ClaudeLog by InventorBlack - 다음을 포함한 고급 주제에 대한 상세한 분석을 제공하는 종합적인 지식 베이스:

  • 고급 메커니즘과 CLAUDE.md 모범 사례
  • plan mode, ultrathink, sub-agents를 위한 실용적인 기술 가이드
  • agent-first design, agent engineering, humanizing agents와 같은 개념
  • 구성 가이드

라이선스

MIT © @ryoppippi

ccusage를 사용하면 Claude Code 사용량을 효과적으로 모니터링하고 비용을 관리할 수 있습니다. 작은 번들 크기와 강력한 기능으로 모든 Claude Code 사용자에게 필수적인 도구입니다!