ccusage는 로컬 JSONL 파일로부터 Claude Code의 토큰 사용량과 비용을 분석하는 데 특화된 고성능 CLI(Command Line Interface) 도구입니다. 이 도구는 사용자의 AI 모델 인터랙션 데이터를 파싱하여 일별, 월별, 세션별 사용량 및 비용을 시각적으로 풍부한 테이블 형식으로 제공하며, Claude의 5시간 과금 구간(billing window)을 추적하는 기능도 포함합니다.

핵심 기능 및 분석 방법론:

1. 데이터 소스 및 파싱: ccusage는 Claude Code가 생성하는 로컬 JSONL(JSON Lines) 형식의 로그 파일을 주된 데이터 소스로 활용합니다. 이 JSONL 파일들은 각 대화 세션 또는 API 호출에서 사용된 토큰 수, 모델 정보, 발생 시간 등 구조화된 사용량 데이터를 포함합니다. 도구는 이 파일들을 파싱하여 개별 트랜잭션 데이터를 추출합니다.

2. 데이터 집계 및 보고서 생성:
   • 시간 기반 집계: 파싱된 데이터를 기반으로 일별(daily), 월별(monthly), 세션별(session)로 토큰 사용량과 비용을 집계합니다. 특히, blocks 리포트는 Claude의 특정 과금 체계인 5시간 단위의 활성 블록(active block) 내 사용량을 모니터링하여, 사용자가 과금 기준에 맞춰 사용량을 최적화할 수 있도록 돕습니다.
   • 비용 계산: 각 모델별(예: Opus, Sonnet) 토큰 당 단가 정보를 활용하여 사용된 토큰에 대한 비용을 USD 단위로 계산합니다. 이 단가는 캐시된 데이터를 사용하므로 offline 모드에서도 작동합니다.
   • 모델별 분석: --breakdown 플래그를 통해 사용된 Claude 모델(Opus, Sonnet 등)별로 토큰 사용량과 비용을 상세하게 분류하여 표시합니다. 캐시 생성(cache creation) 및 캐시 읽기(cache read) 토큰도 별도로 추적 및 표시합니다.

3. 필터링 및 사용자 정의:
   • 날짜 필터링: --since 및 --until 플래그를 사용하여 특정 날짜 범위 내의 데이터를 조회할 수 있습니다.
   • 프로젝트 기반 분석: --instances 플래그를 사용하여 여러 프로젝트 또는 인스턴스별로 사용량을 그룹화하고, --project 플래그로 특정 프로젝트의 사용량만 필터링하여 볼 수 있습니다. 이는 다중 인스턴스 환경에서 효율적인 자원 관리를 지원합니다.
   • 시간대 및 로케일 지원: --timezone 옵션으로 보고서의 시간대를 설정하고, --locale 옵션으로 날짜/시간 형식의 지역화를 지원하여 전 세계 사용자에게 유연성을 제공합니다.

4. 출력 형식:
   • 시각적 출력: 컬러풀하고 자동 반응형 레이아웃을 가진 테이블 형식으로 데이터를 출력하며, 터미널 너비에 따라 자동으로 압축 모드(compact mode)를 적용합니다. --compact 플래그를 통해 강제 압축 모드 설정도 가능합니다.
   • JSON 출력: --json 플래그를 사용하여 분석된 데이터를 구조화된 JSON 형식으로 내보낼 수 있어, 다른 도구나 스크립트와의 연동성을 높입니다.

5. MCP(Model Context Protocol) 통합: ccusage는 MCP 서버를 내장하고 있어, Claude Desktop과 같은 MCP 호환 도구에 실시간으로 사용량 데이터를 노출할 수 있습니다. 이는 AI 워크플로우 내에서 실시간 사용량 추적을 가능하게 하는 중요한 기술적 연동 지점입니다.

확장성 및 관련 도구:

ccusage는 단일 도구를 넘어 ccusage Family라는 일련의 분석 도구들을 포함합니다. 이는 Claude Code 외에도 OpenAI Codex (@ccusage/codex, GPT-5 및 1M 토큰 컨텍스트 지원), OpenCode (@ccusage/opencode), pi-agent (@ccusage/pi), 그리고 Amp CLI (@ccusage/amp) 등 다양한 AI 모델 및 CLI 도구의 토큰 사용량 및 비용 분석을 위한 동반 도구들을 제공하여, 유사한 분석 기능과 보고 능력을 확장합니다.

이 도구는 매우 작은 번들 사이즈를 특징으로 하며, npx를 통한 직접 실행을 권장하여 사용자가 별도의 설치 없이 최신 버전을 손쉽게 사용할 수 있도록 합니다. 개발 환경은 Nix flake를 통해 관리되어 일관된 개발 경험을 제공합니다.