# task-1168.1 완료 보고서

**작업**: Claude Code 사용량 조회 방법 GitHub 리서치
**팀**: dev7-team (이참나)
**소요**: 리서치 에이전트 3명 병렬 투입 (쿠쿨칸/이쉬첼/아쿠인)

---

## SCQA

**S**: 대시보드에서 계정별 Claude 사용량을 조회하기 위해 Admin API 키, 원격 브라우저 스크래핑, /status 파싱 3가지 방법이 알려져 있다.

**C**: 이 외에 커뮤니티에서 발견한 비공식 API, 로컬 파일 파싱, OpenTelemetry 등 최소 7가지 추가 방법이 존재하며, v2.1.80(2026-03-19)에서 statusline에 rate_limits 필드가 공식 추가되었다.

**Q**: 우리 환경(Max20 개인 구독)에서 프로그래매틱하게 사용량을 조회할 수 있는 최적의 방법은 무엇인가?

**A**: 총 10가지 방법을 발견하고 구현 난이도/실시간성/접근 권한별로 분류했다. 우리 환경에서 즉시 적용 가능한 방법은 5가지이며, 추천 순위: (1) JSONL 파일 파싱 — 추가 인프라 없이 토큰/비용/모델별 상세 데이터 제공, ccusage(npm) 참조 구현 존재. (2) statusline rate_limits — v2.1.80+에서 5시간/7일 사용량% 실시간 조회. (3) OpenTelemetry — 환경변수 1개로 활성화, Prometheus/Grafana 연동 가능.

---

## 발견한 전체 방법 (10가지)

### 공식 방법 (6가지)

**1. Admin API - Usage Report**
- 엔드포인트: `GET /v1/organizations/usage_report/messages`
- 인증: Admin API Key (sk-ant-admin...) + 조직 계정 필수
- 데이터: 토큰 (모델/워크스페이스별, 1m/1h/1d 버킷)
- 구현 난이도: 보통 / 지연: 5분
- 우리 환경: **불가** (조직 계정 없음)

**2. Admin API - Cost Report**
- 엔드포인트: `GET /v1/organizations/cost_report`
- 데이터: USD 비용 (일별)
- 우리 환경: **불가**

**3. Admin API - Claude Code Analytics**
- 엔드포인트: `GET /v1/organizations/usage_report/claude_code`
- 데이터: 사용자별 일별 집계 (세션수, LOC, 커밋, PR, 도구 승인율)
- 우리 환경: **불가** + subscription 유저 누락 버그 (#27780)

**4. Rate Limit Response Headers (14개)**
- 모든 API 응답에 자동 포함 (`anthropic-ratelimit-tokens-remaining` 등)
- 일반 API Key로 접근 가능, 실시간
- 우리 환경: Claude Code CLI 내부에서 직접 접근 불가 (API 직접 호출 시에만)

**5. statusline rate_limits 필드 (v2.1.80+, 2026-03-19)**
- statusLine.command JSON에 `rate_limits.five_hour.used_percentage`, `resets_at` 포함
- 구현 난이도: 쉬움 / 실시간
- 우리 환경: **즉시 적용 가능** (현재 v2.1.85)

**6. OpenTelemetry 내장**
- `CLAUDE_CODE_ENABLE_TELEMETRY=1` 환경변수로 활성화
- 메트릭: `claude_code.token.usage`, `claude_code.cost.usage` 등 8개
- 이벤트: `api_request` (model, cost_usd, tokens), `tool_result` 등 5개
- 구현 난이도: 중간 (수집 인프라 필요) / 실시간 (5-60초)
- 우리 환경: **적용 가능** (Prometheus+Grafana 스택 필요)

### 비공식 방법 (4가지)

**7. OAuth Usage API 직접 호출**
- URL: `https://api.anthropic.com/api/oauth/usage`
- 토큰: `~/.claude/.credentials.json` accessToken
- 헤더: `anthropic-beta: oauth-2025-04-20`
- 응답: five_hour/seven_day utilization(%), resets_at, extra_usage
- 구현 난이도: 쉬움 / 실시간
- 위험: 비문서화 API, 과도한 rate limiting (#31637), 언제든 변경/폐기 가능

**8. 로컬 JSONL 파일 파싱**
- 경로: `~/.claude/projects/[project-slug]/[sessionId].jsonl`
- 데이터: per-turn 토큰(input/output/cache_creation/cache_read), costUSD, model, speed
- 구현 난이도: 쉬움 / 실시간 가능 (fs.watch)
- 우리 환경: **최적 추천** — 추가 인프라 없음, 가장 상세한 데이터

**9. Hook + JSONL 조합**
- PostToolUse hook → cost.total_cost_usd + context_window 실시간 수신
- JSONL → 히스토리 분석
- 우리 환경: **적용 가능**

**10. MCP 서버 (anthropic-billing-mcp)**
- Admin API를 MCP 도구로 래핑, 자연어 비용 조회
- 우리 환경: **불가** (Admin API Key 필요)

---

## 주요 커뮤니티 도구 (즉시 사용 가능)

**ccusage** (npm, 가장 인기)
- 설치: `npx ccusage@latest`
- 기능: 일별/월별/세션별/5시간블록별 리포트, MCP 서버 지원, JSON 출력
- GitHub: https://github.com/ryoppippi/ccusage

**claude-monitor** (Python)
- 설치: `pip install claude-monitor`
- 기능: 실시간 터미널 대시보드, ML P90 예측, 0.1-20Hz 갱신
- GitHub: https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor

**sniffly** (웹 대시보드)
- GitHub: https://github.com/chiphuyen/sniffly
- 기능: 웹 UI 통계, 에러 분석, 공유 기능

**claude-code-otel** (OTel 스택)
- GitHub: https://github.com/ColeMurray/claude-code-otel
- 기능: Prometheus+Grafana 대시보드, Docker Compose

---

## 구현 권장

### 즉시 적용 (난이도: 쉬움)
1. **ccusage 설치**: `npx ccusage@latest` — 기존 사용 히스토리 분석
2. **statusline rate_limits 활용**: 현재 v2.1.85에서 이미 지원

### 대시보드 통합 시 (난이도: 보통)
1. **JSONL 파싱 모듈 구현**: ccusage 파싱 로직 참고하여 자체 구현
2. **계정별 분리**: `~/.claude/.credentials.json`에서 `subscriptionType`, `rateLimitTier` 확인

### 팀/조직 규모 확장 시 (난이도: 높음)
1. **OpenTelemetry 활성화**: `CLAUDE_CODE_ENABLE_TELEMETRY=1` + Prometheus 수집
2. **Admin API 도입**: 조직 계정 생성 후 Admin Key 발급

---

## 발견 이슈 및 해결

### 자체 해결 (0건)
코드 작업 없음 (리서치 전용 태스크)

### 범위 외 미해결 (3건)
1. **Admin API subscription 유저 누락** — 범위 외 사유: Anthropic 서버 버그 (#27780), 우리가 수정 불가
2. **OAuth Usage API rate limiting** — 범위 외 사유: Anthropic 서버 정책 (#31637)
3. **`claude usage --json` CLI 미구현** — 범위 외 사유: Anthropic 미구현 (#33978), 커뮤니티 최다 요청

---

## 산출물

- 통합 리서치: `/home/jay/workspace/memory/research/claude-code-usage-methods.md`
- GitHub 이슈 분석: `/home/jay/.cokacdir/workspace/BCBD5839/research_github.md`
- API/커뮤니티 도구: `/home/jay/.cokacdir/workspace/BCBD5839/research_api_community.md`
- 소스/문서 분석: `/home/jay/.cokacdir/workspace/BCBD5839/research_source_analysis.md`

---

## QC 자동 검증 결과

- **전체**: PASS (5 PASS, 7 SKIP)
- file_check: PASS (보고서 6,434 bytes)
- data_integrity: PASS
- critical_gap: PASS
- spec_compliance: PASS
- duplicate_check: PASS (최대 유사도 5.4%)
- api_health/test_runner/tdd_check/pyright_check/style_check/scope_check/schema_contract: SKIP (리서치 태스크, 코드 변경 없음)