이번 글에서는 Claude Code와 Codex 사용량을 분석하기 위한 CLI 도구인 ccusage에 대해 정리합니다.
ccusage는 로컬에 저장된 JSONL 로그를 기반으로 토큰 사용량과 비용을 빠르게 분석할 수 있도록 설계된 도구로, 일별·월별·세션별 사용량을 직관적인 테이블 형태로 확인할 수 있는 것이 특징입니다. 이 글에서는 ccusage의 개발 배경, 주요 기능, 확장 패키지 구성, 그리고 실제 사용 방법까지 입력된 정보를 중심으로 정리해 보겠습니다.
ccusage란 무엇인가
ccusage는 Claude Code 및 Codex의 토큰 사용량과 비용을 분석하기 위해 개발된 CLI 도구입니다.
AI 코드 도구를 사용하다 보면 어느 시점에 얼마나 많은 토큰을 사용했고, 비용이 어떻게 발생했는지 파악하기 어려운 경우가 많습니다. ccusage는 이러한 문제를 해결하기 위해 로컬 JSONL 로그 파일을 분석해 사용량을 빠르고 시각적으로 보여주는 데 초점을 맞추고 있습니다.
특히 Claude Opus, Sonnet 등 모델별 사용량 추적이 가능하고, Claude의 **청구 주기 기준(5시간 단위 블록)**으로도 사용량을 확인할 수 있어 비용 관리 측면에서 유용합니다.
ccusage의 핵심 특징
ccusage가 제공하는 주요 기능은 다음과 같습니다.
1. 사용량 요약 및 시각적 출력
- 일별, 월별, 세션별 토큰 사용량과 비용을 테이블 형태로 요약
- 컬러 테이블 기반 출력과 자동 반응형 레이아웃 지원
- 터미널 폭이 좁을 경우 자동으로 컴팩트 모드 적용
2. 비용 및 모델 단위 분석
- Claude Opus, Sonnet 등 모델별 사용량 구분
- --breakdown 옵션을 통한 모델별 비용 상세 분석
- 캐시 생성 토큰과 캐시 읽기 토큰을 분리하여 표시
3. 기간·프로젝트 기준 필터링
- 날짜 범위 필터링(--since, --until)
- 프로젝트 단위 그룹화 및 여러 인스턴스 비교
- 특정 프로젝트만 필터링해 사용량 조회 가능
4. 실시간 및 확장 기능
- Claude Code 상태 표시줄에 실시간 사용량 표시
- MCP(Model Context Protocol) 서버 내장으로 외부 도구와 실시간 연동
- JSON 형식으로 데이터 내보내기 지원
ccusage 패밀리 구성
ccusage는 하나의 도구에 그치지 않고, 다양한 AI 코드 환경을 지원하는 확장 패키지 패밀리를 제공합니다.
- ccusage: Claude Code 사용량 분석용 메인 CLI 도구
- @ccusage/codex: OpenAI Codex 사용량 분석 (GPT-5 지원 포함)
- @ccusage/opencode: OpenCode 세션 사용량 분석
- @ccusage/pi: pi-agent 세션 사용량 분석
- @ccusage/amp: Amp CLI 세션 사용량 및 크레딧 분석
- @ccusage/mcp: MCP 서버로 ccusage 데이터를 외부 도구에 노출
이러한 구성 덕분에 하나의 사용 방식으로 여러 AI 개발 환경의 사용량을 일관되게 관리할 수 있습니다.
설치 없이 바로 사용하는 방법
ccusage는 번들 크기가 매우 작아 설치 없이 바로 실행할 수 있습니다.
가장 권장되는 방법은 @latest를 명시해 최신 버전을 실행하는 것입니다.
npx ccusage@latest
또는 다음과 같은 실행 방식도 지원합니다.
bunx ccusage
pnpm dlx ccusage
pnpx ccusage
Deno 환경에서도 보안 플래그와 함께 실행할 수 있도록 안내되어 있습니다.
기본 사용 예제
ccusage는 명령어만으로 다양한 리포트를 생성할 수 있습니다.
기본 리포트
npx ccusage
- 기본적으로 일별 사용량 리포트를 출력합니다.
리포트 유형별 조회
npx ccusage daily
npx ccusage monthly
npx ccusage session
npx ccusage blocks
필터 및 옵션 예시
npx ccusage daily --since 20250525 --until 20250530
npx ccusage daily --json
npx ccusage daily --breakdown
이를 통해 기간별, 모델별, 프로젝트별 사용량을 상황에 맞게 확인할 수 있습니다.
개발자를 위한 확장성과 운영 편의성
ccusage는 단순한 리포트 도구를 넘어 운영과 분석을 고려한 설계가 돋보입니다.
- 오프라인 모드 지원으로 네트워크 없이도 비용 계산 가능
- 타임존과 로케일 설정으로 글로벌 환경 대응
- 설정 파일(JSON) 기반 기본 옵션 관리
- Nix 기반 개발 환경 제공으로 기여자 간 환경 일관성 유지
이러한 요소들은 개인 개발자뿐 아니라 팀 단위 사용에도 적합한 구조를 만들어 줍니다.
ccusage는 Claude Code와 Codex 사용량을 빠르고 정확하게 파악하기 위한 CLI 도구로, 토큰 사용량과 비용을 체계적으로 관리하고자 하는 사용자에게 실질적인 도움을 제공합니다.
설치 없이 즉시 실행 가능하고, 모델·기간·프로젝트 단위 분석까지 지원한다는 점에서 사용 장벽이 낮으면서도 활용 범위는 넓습니다.
앞으로 AI 코드 도구 사용이 늘어날수록, 사용량과 비용을 투명하게 관리하는 도구의 중요성도 함께 커질 것입니다. ccusage는 이러한 흐름 속에서 개발자들이 보다 효율적으로 AI 개발 환경을 운영할 수 있도록 돕는 실용적인 선택지가 될 것으로 기대됩니다.
https://github.com/ryoppippi/ccusage
GitHub - ryoppippi/ccusage: A CLI tool for analyzing Claude Code/Codex CLI usage from local JSONL files.
A CLI tool for analyzing Claude Code/Codex CLI usage from local JSONL files. - ryoppippi/ccusage
github.com
'인공지능' 카테고리의 다른 글
| Claude Opus 4.6 Fast Mode 공개: 속도를 극대화한 새로운 실행 옵션과 비용 구조 정리 (0) | 2026.02.10 |
|---|---|
| 오픈소스 CRM Twenty: 비용 부담과 데이터 종속에서 벗어나는 새로운 선택지 (0) | 2026.02.10 |
| 10달러 하드웨어에서 동작하는 초경량 AI 어시스턴트, PicoClaw 기술 정리 (0) | 2026.02.10 |
| AI 에이전트를 보조 도구에서 개발 파트너로 만드는 Skill 생태계 정리 (0) | 2026.02.09 |
| Claude Code 대화 기록을 LangSmith로 자동 추적하는 방법 - CLI 기반 LLM 개발 환경에서 트레이싱을 설정하는 실전 가이드 (0) | 2026.02.09 |
