ccusage - Claude Code 사용 상황 분석 도구

프로젝트 개요

ccusage는 Claude Code 로컬 JSONL 파일의 사용 상황 데이터를 분석하는 CLI 도구입니다. 이 프로젝트는 @ryoppippi가 개발했으며, Claude Code 사용 비용 추적에 대한 글에서 영감을 받았습니다.

주요 특성

📊 다양한 보고서 유형

• 일별 보고서: 날짜별 토큰 사용량 및 비용 요약
• 월별 보고서: 월별 토큰 사용량 및 비용 요약
• 세션별 보고서: 대화 세션별 사용량 그룹화 표시
• 5시간 블록 보고서: 5시간 청구 기간을 기반으로 한 보고서
• 상태 표시줄: 훅(hooks)을 위한 간결한 상태 표시줄 (베타 버전)

🎯 강력한 필터링 및 분석 기능

• 날짜 필터링: --since 및 --until을 사용하여 날짜 범위별로 보고서 필터링
• 프로젝트 분석: 프로젝트/인스턴스별 그룹화, 특정 프로젝트 필터링 지원
• 모델별 비용 세분화: 각 모델의 비용 세분화
• 시간대 및 현지화: UTC 시간대 및 일본어 현지화 형식 지원

🎨 미려한 출력 및 표시

• 자동 반응형 레이아웃을 갖춘 컬러 테이블 형식 표시
• 스마트 테이블: 좁은 터미널(<100자)에서는 자동으로 컴팩트 모드로 전환되어 필수 열만 표시
• 컴팩트 모드: --compact 플래그를 사용하여 강제로 컴팩트 테이블 레이아웃을 적용, 스크린샷 및 공유에 매우 적합
• 향상된 모델 표시: 모델 이름이 글머리 기호 목록으로 표시되어 가독성 향상

💰 비용 추적 기능

• 일별/월별/세션별 비용을 USD로 표시
• 캐시 토큰 지원: 캐시 생성 및 캐시 읽기 토큰을 각각 추적 및 표시
• 오프라인 모드: --offline을 사용하여 네트워크 연결 없이 미리 캐시된 가격 데이터 사용 (Claude 모델에 한함)

⚡ 실시간 모니터링

• 실시간 사용 상황 대시보드
• 실시간 모니터링: ccusage blocks --live

설치 및 사용

빠른 시작 (설치 불필요)

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

전역 설치

# npm을 사용하여 전역 설치
npm install -g ccusage

# bun을 사용하여 전역 설치
bun install -g ccusage

# 그 다음 실행
ccusage

개발 환경

# 저장소 클론
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# 의존성 설치
bun install

# 도구 실행
bun run report [subcommand] [options]

기본 사용법

일별 보고서

# 모든 일별 사용 상황 표시
ccusage daily

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

# 사용자 정의 Claude 데이터 디렉토리 사용
ccusage daily --path /custom/path/to/.claude

# JSON 형식 출력
ccusage daily --json

# 각 모델의 비용 세분화
ccusage daily --breakdown

# UTC 시간대 사용
ccusage daily --timezone UTC

# 일본어 현지화 사용
ccusage daily --locale ja-JP

프로젝트 분석

# 프로젝트/인스턴스별 그룹화
ccusage daily --instances

# 특정 프로젝트로 필터링
ccusage daily --project myproject

# 조합하여 사용
ccusage daily --instances --project myproject --json

세션별 보고서

# 모든 세션 표시
ccusage session

# 마지막 활동 날짜별 세션 필터링
ccusage session --since 20250525

# 필터 조합
ccusage session --since 20250525 --until 20250530 --path /custom/path

# JSON 형식 출력
ccusage session --json

실시간 모니터링

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

# 5시간 청구 기간
ccusage blocks

# 상태 표시줄 (베타 버전)
ccusage statusline

컴팩트 모드

# 강제로 컴팩트 테이블 모드 적용
ccusage --compact

# 컴팩트 월별 보고서
ccusage monthly --compact

명령어 옵션

모든 명령어는 다음 옵션을 지원합니다:

• -s, --since <date>: 시작 날짜로 필터링 (YYYYMMDD 형식)
• -u, --until <date>: 종료 날짜까지 필터링 (YYYYMMDD 형식)
• -p, --path <path>: Claude 데이터 디렉토리의 사용자 정의 경로 (기본값: ~/.claude)
• -j, --json: 결과를 테이블 대신 JSON 형식으로 출력
• -h, --help: 도움말 정보 표시
• -v, --version: 버전 표시

출력 예시

일별 보고서 출력

╭──────────────────────────────────────────╮
│                                          │
│ Claude Code Token Usage Report - Daily  │
│                                          │
╰──────────────────────────────────────────╯
┌──────────────────┬──────────────┬───────────────┬──────────────┬────────────┐
│ Date             │ Input Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ 2025-05-30       │ 277          │ 31,456        │ 31,733       │ $17.45     │
│ 2025-05-29       │ 959          │ 39,662        │ 40,621       │ $16.37     │
│ 2025-05-28       │ 155          │ 21,693        │ 21,848       │ $8.33      │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ Total            │ 11,174       │ 720,366       │ 731,540      │ $336.17    │
└──────────────────┴──────────────┴───────────────┴──────────────┴────────────┘

세션별 보고서 출력

╭───────────────────────────────────────────────╮
│                                               │
│ Claude Code Token Usage Report - By Session  │
│                                               │
╰───────────────────────────────────────────────╯
┌──────────────────────────────┬──────────────┬───────────────┬──────────────┬────────────┬───────────────┐
│ Project / Session            │ Input Tokens │ Output Tokens │ Total Tokens │ Cost (USD) │ Last Activity │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ my-project                   │ 2,775        │ 186,645       │ 189,420      │ $98.40     │ 2025-05-26    │
│ └─ session-abc123...         │              │               │              │            │               │
│ another-project              │ 1,063        │ 41,421        │ 42,484       │ $20.08     │ 2025-05-29    │
│ └─ session-def456...         │              │               │              │            │               │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ Total                        │ 11,174       │ 720,445       │ 731,619      │ $336.38    │               │
└──────────────────────────────┴──────────────┴───────────────┴──────────────┴────────────┴───────────────┘

기술 아키텍처

의존성 요구 사항

• Bun 런타임
• Claude Code 사용 기록 파일 (~/.claude/projects/**/*.jsonl)

프로젝트 구조

ccusage/
├── commands/
│   ├── daily.ts        # 일별 보고서 명령어
│   └── session.ts      # 세션별 보고서 명령어
├── data-loader.ts      # JSONL 데이터 로딩 로직
├── index.ts           # CLI 진입점
├── logger.ts          # 로깅 설정
├── utils.ts           # 공유 유틸리티
└── package.json

개발 및 테스트

# 테스트 실행
bun test

# 타입 검사
bun run typecheck

# 코드 검사
bun run lint

# 코드 포맷팅
bun run format

통합 기능

🔌 MCP 통합

다른 도구와의 통합을 위한 내장 모델 컨텍스트 프로토콜 서버

요약

ccusage는 Claude Code 사용자를 위해 특별히 설계된 강력하고 사용하기 쉬운 CLI 도구로, 토큰 사용량 및 관련 비용을 분석하고 추적합니다. 경량 디자인, 풍부한 기능 세트 및 미려한 출력은 Claude Code 사용을 최적화하고 비용을 관리하려는 개발자에게 이상적인 선택입니다.