evanlong-me/claude-code-usage

Claude Code 사용 통계 및 비용을 로컬에서 분석하기 위한 경량 CLI 도구입니다.

• 🔒
  100% 로컬 및 보안 (Local & Secure)- API 키가 필요하지 않으며, 로컬 Claude Code 데이터만 읽습니다. - ⚡
  빠른 분석 (Quick Analysis)- 단일 ccu 명령어로 모든 사용 통계를 확인하세요. - 💰
  비용 추적 (Cost Tracking)- Claude 가격 책정을 기반으로 정확한 비용을 계산합니다. - 📊
  이중 보기 모드 (Dual View Modes)- 일별 집계 보기와 상세 메시지 보기 사이를 전환할 수 있습니다. - 🎯
  스마트 프로젝트 감지 (Smart Project Detection)- 프로젝트 디렉토리에서 실행 시 현재 프로젝트를 자동으로 감지합니다. - 📋
  깔끔한 테이블 표시 (Clean Table Display)- 토큰 수, 비용 및 프로젝트 정보가 포함된 정리된 표 형식의 출력을 제공합니다. - 🔍
  스마트 필터링 (Smart Filtering)- 시간 범위 및 프로젝트 이름별로 필터링합니다. - 📈
  유연한 정렬 (Flexible Sorting)- 비용, 시간, 토큰 또는 프로젝트 이름별로 정렬합니다. - 🔄
  자동 업데이트 확인 (Auto Update Check)- 새 버전을 자동으로 확인하고 업데이트가 가능할 때 알림을 보냅니다. - 🚀
  사용 용이성 (Easy to Use)- 간단한 설치와 직관적인 명령어를 제공합니다.

npm install -g claude-code-usage
ccu # 즉시 통계 보기

# 일회성 사용 (설치 불필요)
npx claude-code-usage
# 로컬 프로젝트 설치
...

사용 가능한 기본 명령어는 다음과 같습니다:

# 사용 통계 보기 (기본 명령어)
ccu
# 버전 정보 표시
...

시간 범위와 프로젝트별로 사용 데이터를 필터링하세요.

참고: 시간 필터에 공백이 포함된 경우 따옴표로 감싸는 것을 권장합니다.

이 도구는 최대의 유연성을 위해 다양한 시간 필터링 형식을 지원합니다:

상대적 시간 필터 (Relative Time Filters) (따옴표 불필요):

5min, 30min - 최근 N분
2h, 12h - 최근 N시간
7d, 30d - 최근 N일
1m, 6m - 최근 N개월
1y, 2y - 최근 N년

날짜 범위 필터 (Date Range Filters):

6-8 - 월 범위 (6월부터 8월까지, 현재 연도)
july-august, jan-mar - 이름으로 지정된 월 범위
2024-7-2024-8 - 연도를 넘나드는 월 범위
2024-07-01,2024-08-31 - 특정 날짜 범위

정밀한 날짜/시간 필터 (Precise DateTime Filters) (ISO 8601 형식, 권장):

2024-07-30T16:00:00,2024-07-30T18:00:00 - 초 단위 정밀도
2024-07-30T16:00,2024-07-30T18:00

• 분 단위 정밀도 2024-07-30T16,2024-07-30T18

• 시간 단위 정밀도

읽기 쉬운 날짜/시간 (Human-readable DateTime) (따옴표 필요):

"2024-07-30 16:00:00,2024-07-30 18:00:00"

• 초 단위 정밀도 "2024-07-30 16:00,2024-07-30 18:00"

• 분 단위 정밀도

# 상대적 시간으로 필터링 (따옴표 불필요)
ccu -t 5min # 최근 5분
ccu -t 2h # 최근 2시간
...

다양한 기준에 따라 결과를 정렬하세요:

# 비용 기준 정렬 (높은 순서부터)
ccu -s cost -o desc
# 비용 기준 정렬 (낮은 순서부터)
...

이 도구는 현재 프로젝트를 자동으로 감지하여 그에 따라 결과를 필터링합니다:

# 프로젝트 디렉토리에서 실행할 경우, 해당 프로젝트로 자동 필터링
cd my-project
ccu # my-project 사용량만 표시
...

다양한 보기 모드 간 전환:

# 기본값: 집계된 보기 (프로젝트 및 날짜별)
ccu
# 상세 보기: 개별 메시지 표시
...

결과를 표시한 후 나타나는 GitHub 스타(star) 요청 프롬프트를 관리하세요:

# GitHub 스타 요청 프롬프트를 영구적으로 비활성화
ccu --disable-github-prompt
# GitHub 스타 요청 프롬프트를 다시 활성화
...

이 도구는 사용 통계를 표시한 후 GitHub에서 저장소를 스타(star) 해달라는 친절한 프롬프트를 보여줍니다. 다음과 같이 선택할 수 있습니다:

활성화 상태 유지(기본값) - 프로젝트 지원에 도움이 됩니다
영구적으로 비활성화 - 설정이 저장되어 향후 모든 실행 시 적용됩니다
언제든 다시 활성화 - 마음이 바뀌면 다시 켤 수 있습니다

사용자의 설정은 ~/.claude-code-usage-config.json에 저장됩니다.

옵션은 용도별로 그룹화되어 있습니다:

옵션	설명	값	기본값
-t, --time	시간 필터	5min , 2h , 7d , 1m , 1y , 6-8 , july-august , 2024-07-01T14:30,2024-07-01T16:45 , 등	-
-p, --project	프로젝트 필터	프로젝트 이름 (부분 일치)	자동 감지 (auto-detect)
-a, --all	모든 프로젝트 표시	-	false (자동 감지)

옵션 (Option)	설명 (Description)	값 (Values)	기본값 (Default)
-d, --detailed	개별 메시지 표시	-	false (집계됨)
--by-date	날짜별로만 집계하여 하루 동안의 모든 프로젝트를 통합
-	-	-	false

옵션 (Option)	설명 (Description)	값 (Values)	기본값 (Default)
-s, --sort	정렬 필드	cost (비용), time (시간), tokens (토큰), project (프로젝트)	time
-o, --order	정렬 순서	asc (오름차순), desc (내림차순)	asc

옵션 (Option)	설명 (Description)	값 (Values)	기본값 (Default)
-lp, --list-projects	모든 프로젝트 목록 표시	-	-
-lm, --list-models	가격 정보와 함께 사용 가능한 모든 모델 목록 표시	-	-

옵션 (Option)	설명 (Description)	값 (Values)	기본값 (Default)
--disable-github-prompt	GitHub 스타 유도 프롬프트를 영구적으로 비활성화	-	-
--enable-github-prompt	GitHub 스타 유도 프롬프트를 다시 활성화	-	-

출력 결과의 예시는 다음과 같습니다:

🔍 적용된 옵션 (Options applied):
Project: my-website
Sort: cost ↓
...

ccu --list-projects
# 또는 짧은 형식 사용: ccu -lp

📁 사용 가능한 프로젝트 (Available projects):
• my-website (45 messages)
• data-analysis (8 messages)
...

Node.js >= 14.0.0
Claude Code 설치 및 설정 완료

• 대화 기록이 포함된 최소 하나 이상의 Claude Code 프로젝트

이 도구는 로컬 파일에서 Claude Code 사용 데이터를 읽어옵니다:

~/.claude.json

• 주요 Claude Code 설정

~/.claude/projects/

• 세션 기록 및 프로젝트 데이터

~/.claude/settings.json

• 사용자 설정 (선택 사항)

이 도구를 처음 사용하시나요? 시스템에 Claude Code가 설정되어 있지 않으면 다음과 같은 메시지가 표시됩니다:

❌ Claude Code 설정을 찾을 수 없습니다! (Claude Code configuration not found!)
📋 해결 방법:
1. Claude Code 설치:
...

100% 로컬 데이터 (100% Local Data)

• 모든 Claude Code 사용 데이터는 로컬 파일에서 읽어옵니다.

최소한의 네트워크 사용 (Minimal Network Usage)

• LiteLLM으로부터 모델 가격 정보만 가져옵니다 (1시간 동안 캐싱됨).

API 키 불필요 (No API Keys)

• 인증이 필요하지 않습니다.

개인정보 보호 우선 (Privacy First)

• 사용자의 사용 데이터는 절대 기기를 벗어나지 않습니다.

기여(Contributions)를 환영합니다! Pull Request를 제출해 주세요.

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.

버그를 발견하셨나요? Issue를 생성해 주세요.