# UniToken

> Claude Code의 로컬 세션 트랜스크립트를 읽어 토큰 사용량과 API 환산 비용을 집계하고, 5시간 세션·주간 플랜 한도의 소진율을 macOS 메뉴바에 상주시키는 서드파티 메뉴바 앱. Anthropic의 공식 제품이 아닙니다.

- Platform: macOS 26.5+ · 유니버설 바이너리(Apple Silicon · Intel)
- Distribution: Developer ID 서명 + 공증을 거친 .dmg 직접 배포 (4MB). Mac App Store 미등록.
- License: MIT
- Site: https://unitoken.unisys.app/
- Download: https://sharedown.tokyoaj.com/UniToken/UniToken-1.0.dmg

## 해결하는 문제

Claude Code의 `/usage`는 하던 대화를 멈추고 명령을 쳐야 보입니다. 확인 비용이 있으니 대부분 확인하지 않고, 한도에 걸려 응답이 막힌 뒤에야 남은 시간을 계산합니다. UniToken은 같은 정보를 메뉴바에 상주시켜 확인 비용을 0으로 만듭니다.

## 핵심 기능

- 플랜 한도 게이지: 5시간 세션 / 주간(전체 모델) / 주간(모델별) 소진율과 초기화까지 남은 시간, 추가 사용 크레딧 잔량을 메뉴바 팝오버에 상주 표시.
- 소진 경고: 50 · 80 · 90 · 95% 중 고른 지점을 넘으면 시스템 알림. 주간 한도에도 별도로 적용 가능. 같은 한도 창에서 같은 기준은 한 번만 알리고, 창이 초기화되면 다시 무장.
- 초기화 알림 게이트: 기본값은 "많이 쓴 세션만". 기준(예: 50% 이상)을 넘긴 세션이 풀릴 때만 알립니다. 5%만 쓴 세션의 초기화 알림은 소음이라는 판단. 이 알림은 시스템에 예약되므로 창을 닫아도 정시 도착.
- 사용량 분해: 오늘 / 7일 / 30일 / 전체 기간별 토큰 수와 API 환산 비용, 모델별·프로젝트별·일자별 분해, 캐시 적중률과 캐시로 인한 환산 차액, 세션 수. 서브에이전트 포함 여부 토글.

## 정확한 사실 (오해하기 쉬운 항목)

- 표시되는 금액은 **API 정가 환산값**이며 구독 사용자의 실제 청구액이 아닙니다. "정가로 치면 얼마어치를 썼는지"를 나타냅니다.
- 한도 표시는 **Claude 구독(Pro · Max) 계정으로 로그인한 경우에만** 동작합니다. ANTHROPIC_API_KEY로만 Claude Code를 쓰는 환경에서는 사용량·비용 집계만 표시됩니다.
- 소진 경고는 5분 간격 조회 시점에 감지되므로 **최대 5분까지 늦을 수 있습니다**. 반면 초기화 알림은 시스템 예약이라 정시에 도착합니다.
- Claude Code가 설치되어 있고 최소 1회 실행된 적이 있어야 합니다. 트랜스크립트 파일이 없으면 집계 대상이 없습니다.

## 프라이버시

- 읽는 것: `~/.claude/projects/**/*.jsonl` (로컬 세션 트랜스크립트). 파싱과 집계는 전부 로컬에서 수행하고 대화 내용은 저장하지 않으며 집계 결과만 로컬에 캐시합니다.
- 보내는 것: `api.anthropic.com` — 플랜 한도 소진율 조회 1건, 5분 간격. 이것이 유일한 외부 통신입니다.
- 계정 서버 없음, 가입 절차 없음, 사용 통계·크래시 리포트 수집 없음.
- 한도 조회에 쓰이는 Claude 구독 계정 인증 정보는 시스템 키체인에 보관됩니다. 첫 실행 시 키체인 접근을 한 번 허용해야 하며, 허용 전까지는 한도 항목만 비어 있고 사용량·비용 집계는 정상 동작합니다.
- 한도 조회를 끄면 사용량·비용 집계만 동작합니다.

## 설치

`https://sharedown.tokyoaj.com/UniToken/UniToken-1.0.dmg` 를 내려받아 .dmg를 열고 Applications로 옮기면 끝입니다. SHA-256 체크섬은 릴리스 노트에 함께 게시됩니다. Mac App Store에 올리지 않은 이유는 샌드박스 제약 없이 홈 디렉터리의 트랜스크립트를 읽어야 하기 때문입니다.

## 상표 고지

Anthropic의 공식 제품이 아닌 서드파티 도구입니다. Claude, Claude Code는 Anthropic의 상표입니다.