ryoppippi/ccusage

로컬 데이터를 통해 코딩 (에이전트) CLI의 토큰 사용량 및 비용을 분석합니다.

ccusage는 코딩 에이전트 CLI의 로컬 사용 데이터를 읽어 일간, 주간, 월간 및 세션 보고서로 변환합니다.

소스 (Source)	집중 명령 예시
Claude Code	ccusage claude daily
...
ccusage daily, ccusage weekly, ccusage monthly 또는 ccusage session을 사용하여 감지된 모든 소스를 하나의 보고서에 포함할 수 있습니다.

글로벌 설치 없이 ccusage를 직접 실행할 수 있습니다:

# 권장 사항
bunx ccusage
# Nix
...

bunx는 다운로드된 패키지를 캐싱하므로, 첫 실행 이후 반복 실행 시 더 빠릅니다.

# 기본 사용법
bunx ccusage # 일별로 감지된 모든 소스 표시 (기본값)
bunx ccusage daily # 일별로 감지된 모든 소스
...

• 📊
  일간 보고서 (Daily Report): 날짜별로 집계된 토큰 사용량 및 비용 확인 - 📅
  월간 보고서 (Monthly Report): 월별로 집계된 토큰 사용량 및 비용 확인 - 💬
  세션 보고서 (Session Report): 대화 세션별로 그룹화된 사용량 확인 - 🤖
  통합 CLI 보고서 (Unified CLI Reports): Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI 및 Gemini CLI 사용량을 하나의 CLI에서 확인 - ⏰
  5시간 단위 보고서 (5-Hour Blocks Report): 활성 블록 모니터링을 통해 Claude의 과금 창(billing windows) 내 사용량 추적 - 🚀
  상태줄 통합 (Statusline Integration): Claude Code 상태 표시줄 훅을 위한 컴팩트한 사용량 표시 (베타) - 🤖
  모델 추적 (Model Tracking): 지원되는 소스 전반에서 어떤 모델이 사용되는지 확인 - 📊
  모델 상세 분석 (Model Breakdown): --breakdown 플래그를 사용하여 모델별 비용 상세 내역 확인 - 📅
  날짜 필터링 (Date Filtering): --since 및 --until을 사용하여 날짜 범위별로 보고서 필터링 - 📁
  사용자 정의 경로 (Custom Paths): 사용자 정의 로컬 데이터 디렉토리 위치 지원 - 🎨
  미려한 출력 (Beautiful Output): 자동 반응형 레이아웃이 적용된 색상 테이블 형식 디스플레이 - 📱
  스마트 테이블 (Smart Tables): 폭이 좁은 터미널(< 100자)의 경우 필수 열만 포함하는 자동 컴팩트 모드 - 📸
  컴팩트 모드 (Compact Mode): --compact 사용

테이블 레이아웃을 강제로 컴팩트하게 만드는 플래그로, 스크린샷 촬영 및 공유에 완벽합니다 - 📋
향상된 모델 표시 (Enhanced Model Display): 가독성을 높이기 위해 모델 이름을 글머리 기호 목록으로 표시합니다 - 📄
JSON 출력 (JSON Output): --json 옵션을 사용하여 데이터를 구조화된 JSON 형식으로 내보냅니다

• 💰
  비용 추적 (Cost Tracking): 일별/월별/세션별 비용을 USD로 표시합니다 - 🔄
  캐시 토큰 지원 (Cache Token Support): 캐시 생성 (cache creation) 및 캐시 읽기 (cache read) 토큰을 별도로 추적하고 표시합니다 - 🌐
  오프라인 모드 (Offline Mode): --offline을 사용하여 네트워크 연결 없이 사전 캐시된 가격 데이터를 사용합니다

• 🏗️
  Claude 인스턴스 지원 (Claude Instance Support): --instances를 사용하여 Claude Code 사용량을 프로젝트별로 그룹화하고 특정 프로젝트별로 필터링할 수 있습니다 - 🌍
  시간대 지원 (Timezone Support): --timezone 옵션으로 날짜 그룹화를 위한 시간대를 설정합니다 - ⚙️
  설정 파일 (Configuration Files): JSON 설정 파일을 통해 기본값을 설정할 수 있으며, IDE 자동 완성 및 유효성 검사 기능을 완벽하게 지원합니다

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

기여자 설정 (Contributor setup)

기여자 설정에는 nix-direnv가 포함된 Nix flake 개발 환경이 필요합니다. nix-command와 flakes 실험적 기능이 활성화된 상태로 Nix를 설치한 다음, 디렉토리에 진입할 때 nix-direenv가 개발 셸 (dev shell)을 자동으로 로드하도록 하세요:

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

개발 셸은 flake.nix로부터 고정된 pnpm, Rust 툴체인 (toolchain), GitHub CLI, git hooks, 생성된 로컬 에이전트 기술 (local agent skills), 그리고 프로젝트 유틸리티를 제공합니다. 또한 필요할 때 pnpm-lock.yaml로부터 패키지 의존성을 설치합니다.

Nix 환경 내부에서 일반적인 체크 항목들을 실행하세요:

pnpm run format
pnpm typecheck
pnpm run test

flake는 ccusage를 기본 패키지 및 앱으로 노출합니다:

nix run github:ryoppippi/ccusage
nix run github:ryoppippi/ccusage -- codex daily --offline
nix build github:ryoppippi/ccusage

Nix 빌드는 고정된 litellm flake 입력으로부터 LiteLLM 가격 파일을 포함하므로, 샌드박스 빌드 (sandboxed builds) 시 빌드 타임에 가격을 가져오지 않습니다. 고정된 가격 스냅샷을 업데이트하려면:

Non-Nix Cargo 빌드는 flake.lock에서 동일한 잠금된 (locked) LiteLLM 리비전을 읽고, 빌드 타임에 해당 리비전으로부터 가격 파일을 가져옵니다.

nix flake update litellm
nix flake check

예약된 update pricing 워크플로우 (workflow)는 동일한 명령어를 실행하며, 잠금된 입력값이 변경되면 PR (Pull Request)을 생성합니다.

ccusage를 확인해 보세요: 바이럴이 된 Claude Code 비용 스코어카드 (cost scorecard)