ccusage란?

ccusage는 Claude Code와 Codex CLI의 사용량을 로컬 환경에서 분석하는 오픈소스 CLI 도구입니다. 가장 큰 특징은 별도의 설치 없이 npx를 통해 직접 실행할 수 있다는 점입니다. 매우 작은 번들 크기로 인해 설치 시간도 빠르고, 항상 최신 버전을 유지할 수 있습니다.

Claude Code를 사용하면서 다음과 같은 정보를 얻기 어려웠다면, ccusage가 정확히 필요한 도구입니다. 월별 정확한 사용량 현황, 프로젝트별 사용량 분석, 시간대별 사용 패턴, 예상 비용 계산, 주간 사용량 추이를 모두 확인할 수 있습니다.

ccusage 설치 방법

가장 간단한 방법: npx를 사용한 직접 실행

ccusage의 가장 큰 장점은 설치 없이 바로 사용할 수 있다는 점입니다. 터미널에서 npx ccusage@latest 명령어를 실행하면 됩니다.

@latest 접미사를 포함하는 것이 중요합니다. 이를 통해 항상 최신 버전의 ccusage를 실행할 수 있고, 최신 기능과 버그 수정 사항을 즉시 적용할 수 있습니다.

다른 패키지 매니저 옵션

npm 외에도 여러 패키지 매니저를 통해 ccusage를 실행할 수 있습니다.

Bun 사용 (빠른 성능): bunx ccusage@latest 명령어로 더 빠른 성능으로 실행할 수 있습니다.

pnpm 사용: pnpm dlx ccusage@latest 또는 pnpx ccusage@latest로 실행 가능합니다.

Deno 사용: deno run -E -R=$HOME/.claude/projects/ -S=homedir -N=’raw.githubusercontent.com:443′ npm:ccusage@latest 명령어로 보안 플래그를 포함하여 실행할 수 있습니다.

Codex CLI 전용 버전

GitHub Copilot의 Codex CLI를 사용하는 경우, npx @ccusage/codex@latest 또는 bunx @ccusage/codex@latest 명령어로 전용 버전을 설치할 수 있습니다.

Bun을 사용할 경우, 시스템에 기존 codex 명령어가 있으면 우선순위로 인해 다른 도구가 실행될 수 있으므로, 반드시 버전 태그를 포함해야 합니다.

ccusage 사용 방법

기본 실행

ccusage를 실행하면 Claude Code의 사용 데이터를 자동으로 분석합니다. 터미널에서 npx ccusage@latest를 실행하면 되는데, 첫 실행 시 Claude Code가 저장한 로컬 JSONL 파일을 스캔합니다.

Claude Code는 모든 세션 데이터를 ~/.claude/projects/ 디렉토리에 저장하므로, ccusage는 이 데이터를 읽어 분석합니다.

주요 출력 정보

ccusage를 실행하면 다음과 같은 정보를 얻을 수 있습니다.

월별 사용량 통계: 전체 월간 사용 데이터를 요약한 형태로 표시됩니다. 토큰 수, 요청 횟수, 비용 등의 정보가 포함됩니다.

프로젝트별 분석: 각 프로젝트별로 얼마나 많은 사용량을 소비했는지 확인할 수 있습니다. 웹 크롤링 프로젝트, WordPress 테마 개발, 저관여 앱 개발 등 각각의 사용량을 구분할 수 있습니다.

시간대별 패턴: 언제 Claude Code를 가장 많이 사용했는지 시간대별로 분석합니다.

예상 비용: API 기반 종량제로 사용했을 경우의 예상 비용을 계산합니다. 정액제와 비교하여 얼마나 절감되었는지 파악할 수 있습니다.

ccusage의 실제 활용

정확한 월간 사용량 파악

Claude Code를 사용하면서 가장 답답했던 점은 정확한 월간 사용량을 알 수 없다는 것이었습니다. Claude.ai 웹 인터페이스에서는 전체 사용량만 표시되고, 프로젝트별 세부 사항을 확인하기 어려웠습니다. ccusage는 이 문제를 완벽하게 해결합니다.

예를 들어, 당신이 한 달에 여러 프로젝트를 동시에 진행하면서 월 1,085.73달러의 사용량을 기록했다면, ccusage를 통해 다음을 확인할 수 있습니다. 웹 크롤링 프로젝트가 전체 사용량의 몇 퍼센트를 차지했는지, WordPress 테마 개발에 소비된 정확한 비용, 저관여 앱 개발의 평균 일일 사용량, 어느 프로젝트가 가장 비효율적이었는지를 모두 파악할 수 있습니다.

한도 관리 전략 수립

Max 플랜 $100 요금제에서 주간 한도에 도달하는 패턴을 파악할 수 있습니다. ccusage의 데이터를 통해 하루 평균 사용량 계산, 주간 사용량 추이 분석, 한도 도달 시기 예측, 프로젝트별 우선순위 결정이 모두 가능합니다.

이런 정보를 바탕으로 더 효율적인 사용 계획을 세울 수 있습니다.

비용 절감 효과 확인

정액제와 API 종량제의 비용 차이를 명확히 볼 수 있습니다. ccusage가 보여주는 예상 비용이 실제 정액제 요금 (월 $100)과 비교하여 얼마나 절감되는지 한눈에 파악할 수 있습니다.

월 사용량이 1,000달러를 초과한다면, Max 플랜의 월 $100이 얼마나 경제적인지 명확히 이해할 수 있습니다.

ccusage 사용 팁

정기적인 모니터링

주 1회 또는 월 1회 정기적으로 ccusage를 실행하여 사용 패턴을 모니터링하는 것을 추천합니다. 이를 통해 사용량 증감 추이를 파악하고 필요시 사용 전략을 조정할 수 있습니다. 단순히 npx ccusage@latest 명령어만 실행하면 됩니다.

프로젝트별 추적

여러 프로젝트를 진행 중이라면, ccusage의 프로젝트별 분석을 활용하여 각 프로젝트의 효율성을 평가하세요. 예상보다 많은 사용량을 소비하는 프로젝트가 있다면, 접근 방식을 개선할 필요가 있는지 검토해야 합니다.

Sonnet vs Opus 모델 비교

ccusage 데이터를 통해 다양한 모델을 사용했을 때의 비용 차이를 분석할 수 있습니다. Max 플랜에서 Opus 모델을 피해야 하는 이유를 데이터로 확인할 수 있습니다.

자동화된 리포팅

ccusage 실행 결과를 주기적으로 기록하면, 장기적인 사용 패턴을 분석할 수 있습니다. 스프레드시트나 간단한 스크립트를 통해 자동화하면 더 효과적입니다.

ccusage와 Claude Code의 데이터 흐름

Claude Code 데이터 저장 위치

Claude Code를 실행할 때마다 모든 세션 데이터는 ~/.claude/projects/ 디렉토리에 JSONL 형식으로 저장됩니다. 이 데이터에는 실행한 명령어, 사용한 모델, 입출력 토큰 수, 실행 시간, 프로젝트 이름 등의 정보가 포함됩니다.

ccusage의 분석 프로세스

ccusage를 실행하면 다음 과정을 거칩니다. 먼저 ~/.claude/projects/ 디렉토리를 스캔한 후, 모든 JSONL 파일을 읽고 데이터를 파싱 및 분류합니다. 그 다음 월별, 프로젝트별, 시간별 통계를 계산하고 비용 예상치를 산출한 후, 인쇄 가능한 형식으로 정렬하여 출력합니다.

ccusage를 사용해야 하는 이유

투명성

Claude Code의 정확한 사용량을 로컬에서 직접 확인할 수 있습니다. 외부 서버에 의존하지 않고 자신의 컴퓨터에 저장된 데이터만 분석하므로 완전히 투명합니다.

프라이버시

모든 데이터 분석이 로컬에서 이루어지므로, 사용 데이터가 외부 서버로 전송되지 않습니다. 완전한 프라이버시를 보장합니다.

즉시성

설치 없이 npx로 바로 실행할 수 있어, 필요할 때 언제든지 즉시 사용량을 확인할 수 있습니다.

정확성

Claude Code가 기록한 원본 데이터를 직접 분석하므로, Claude.ai 웹 인터페이스에서 보여주는 수치와 정확히 일치합니다.

ccusage 사용 예시

시나리오: 다중 프로젝트 관리자

당신이 4개의 프로젝트를 동시에 진행하고 있다면, 월 초에는 ccusage를 실행하여 지난 달의 최종 통계를 확인합니다. 월 $100 정액제 대비 얼마나 절감했는지 파악할 수 있습니다.

주 중에는 특정 프로젝트의 사용량이 예상보다 많다면, ccusage를 통해 확인하고 원인을 분석합니다. 한도 접근 시에는 ccusage를 실행하여 남은 주간 사용량을 예측하고, 다음 주기까지 작업 일정을 조정합니다.

시나리오: 비용 최적화

ccusage 데이터를 통해 다음과 같은 최적화를 할 수 있습니다. 가장 비효율적인 프로젝트 식별, Opus 모델 사용을 Sonnet으로 변경했을 때의 비용 절감 추정, 시간대별 사용량 분석으로 최적 작업 시간 결정, 프로젝트별 예산 배분 계획 등이 모두 가능합니다.

ccusage 명령어 정리

기본 실행: npx ccusage@latest 명령어를 실행하면 됩니다.

최신 버전 확인: @latest를 항상 포함하면 최신 버전이 자동으로 다운로드되고 실행됩니다.

빠른 실행: Bun을 사용하는 경우 bunx ccusage@latest 명령어로 더 빠르게 실행할 수 있습니다.

정기적 실행을 위한 쉘 별칭 설정: ~/.bashrc 또는 ~/.zshrc에 alias ccusage=’npx ccusage@latest’ 라인을 추가하면, 향후 단순히 ccusage 명령어로 실행할 수 있습니다.

결론

ccusage는 Claude Code 사용자에게 필수적인 도구입니다. 이전까지 알 수 없었던 정확한 월간 사용량과 프로젝트별 분석 데이터를 제공함으로써, 더 나은 비용 관리와 효율적인 워크플로우 계획을 가능하게 합니다.

설치가 필요 없고, 언제든지 npx로 실행할 수 있으며, 완전한 투명성과 프라이버시를 보장합니다. Claude Code의 Max 플랜을 사용 중이라면, ccusage를 통해 정확히 얼마나 절감되고 있는지 확인할 수 있고, 향후 사용 계획을 더 전략적으로 수립할 수 있습니다.