두 가지 도구를 하나로. Claude 플랜 한도에 얼마나 근접했는지 보여주는 실시간 트레이 **사용량 위젯(usage widget)**과, 토큰 및 달러가 프로젝트별, 모델별, 도구별로 실제로 어디에 사용되었는지를 추적하는 영구적인 로컬 **토큰 추적기(token tracker)**를 제공합니다.

MIT · Linux GTK 대시보드 + 크로스 플랫폼 CLI · Python 3.8 이상 · 파이썬 종속성 없음

🟢 사용량 위젯 (실시간) |
📊 토큰 추적기 (로컬) |
|---|---|---|
답변하는 질문 | "지금 플랜 한도에 얼마나 근접했나요?" | "제 토큰과 돈은 어디에 쓰였나요?" |
데이터 출처 | Claude 플랜의 실시간 5시간/7일 사용량 (claude.ai usage API) | 로컬 디스크의 Claude 코드 로그 (~/.claude/projects) |
표시 방식 | 시스템 트레이 게이지 + 경고 알림 | CLI (ctt) + GTK 대시보드 + SQLite 히스토리 |
네트워크/토큰 필요? | 예 — claude CLI OAuth 토큰을 읽음 (위험 고지 참고) | 아니요 — 100% 오프라인, 토큰에 접근하지 않음 |
플랫폼 | Linux 트레이 (GTK) | Linux/macOS/Windows용 CLI; Linux용 대시보드 |

이 위젯은 claude_ai_usage_widget의 정신적 후속작이며, 추적기는 그 위에 새롭게 구축된 절반입니다. 두 부분 중 어느 것을 단독으로 사용해도 됩니다. 실시간 폴링을 비활성화하면 순수한 로컬 분석 도구가 되고, 대시보드를 무시하면 트레이 게이지는 원래 위젯처럼 작동합니다.

1 · 사용량 위젯(Usage Widget) — 시스템 트레이에서 바로 확인할 수 있는 실시간 5시간/7일 플랜 한도, 현재 블록 소모 및 지출 현황, 빠른 작업 기능.

2 · 토큰 추적기(Token Tracker) — 로컬 히스토리: 프로젝트별/모델별 지출 내역, 예산, 그리고 5시간 단위의 블록 예측치 (프로젝트 이름은 흐림 처리).

사용량 위젯 (실시간 플랜 한도)

트레이 게이지(Tray gauge)— Anthropic의 claude /usage 의미론을 반영하여 현재 5시간 플랜 사용량을 한눈에 보여주는 색상 코딩된 링입니다. 5시간 + 7일 이동 창(rolling windows) — 단기 및 주간 한도 사용량 모두 확인 가능하며, 초기화 카운트다운 표시가 있습니다. 모델별 주간 한도(Per-model weekly limits) — 플랜이 모델을 개별적으로 측정하는 경우 (예: Max에 대한 전용 Opus 주간 제한), 각 모델의 한도는 백분율과 초기화 시점을 표시하며 별도의 행/막대로 표시됩니다.

현재 사용량을 제한하는 주체일 때. ETA to limit— 현재 소모 속도로 할당량에 도달할 예상 시점. Escalation notifications— 창의 75% / 90% / 100% 지점에서 데스크톱 알림. Multi-account— 여러 Claude 로그인 계정을 한 번에 추적하며, 각 계정은 자체 트레이 표시기를 가집니다; 트레이에서 특정 계정을 숨기거나 폴링을 비활성화할 수 있습니다.

토큰 추적기 (Token Tracker) (로컬 분석)

SQLite 기록 (~/.config/claude-token-tracker/history.db)

그것이 보존됩니다— 실시간 위젯은 현재 상태만 보았지만, 이것은 수개월간의 기록을 유지합니다. (~/.claude/projects)

분리 및 정리 프로젝트별 / 모델별 / 도구별 사용량 할당 — 어떤 프로젝트가, 어떤 모델이, 그리고 어떤 도구 호출(Bash, Read, Edit, Agent, …)이 지출을 유발하는지 확인합니다. 비용 추정치— 내장된 요금표를 통해 가격 책정되며 이 요금표는 사용자가 재정의할 수 있습니다. 5시간 세션 + 예측— 계정이 실제로 청구되는 기간으로, 사용량 API가 보고하는 초기화 시간에 고정되어 있으며 소모 속도와 시간까지 제공합니다. 토큰이 없는 경우 로그에서 기간을 추론하여 표시하며, claude.ai에서의 사용량은 앱과 다른 기기에서의 사용량과 동일한 기간에 포함되며 로컬 로그에는 절대 나타나지 않습니다. 예산(Budgets)— 일일 / 주간 / 월간 USD 또는 토큰 한도 설정으로, 전역적, 프로젝트별, 모델별로 범위 지정할 수 있습니다. 또한 실시간 5시간/7일 기간에 연동되는 선택적 플랜 활용률 % 예산 기능도 제공합니다. 임계값을 초과하면 데스크톱 알림이 발생합니다. 크로스 플랫폼 CLI (ctt)

셸 프롬프트, 상태 표시줄 및 CI 검사를 위한 테이블 또는 --json 출력을 지원합니다. GTK 대시보드 (Linux)— 대시보드, 프로젝트, 상세 내역, 예산, 설정 뷰를 제공하며, 시스템 / 라이트 / 다크 테마 전환 기능이 있습니다; 숨겨지면 실시간 폴링을 중단합니다.

curl -fsSL https://github.com/StaticB1/claude_ai_usage_widget/raw/main/install.sh | bash

스크립트는 배포판의 패키지 관리자(apt / dnf / pacman / zypper)를 통해 GTK3 바인딩을 설치하고, 앱을 ~/.local/share/claude-token-tracker에 배치하며, claude-token-tracker (GUI)와 **(CLI)**를 ctt 및 ~/.local/bin에 등록합니다.

, hicolor 아이콘을 설치하고 로그인 자동 시작 항목을 추가합니다. 자동 시작을 건너뛰려면 다음 명령어를 사용하세요: curl -fsSL https://github.com/StaticB1/claude_ai_usage_widget/raw/main/install.sh | bash -s -- --no-autostart

git clone https://github.com/StaticB1/claude_ai_usage_widget.git
cd claude_ai_usage_widget
bash install.sh # 로그인 시작 시 자동 시작을 건너뛰려면 --no-autostart 추가

v2는 드롭인 업데이트가 아닌 리브랜딩입니다. 기존의 단일 파일 claude_ai_usage_widget은 다음과 같이 설치되었습니다:
claude-usage-widget (바이너리: claude-widget-start, /-stop, 설정: ~/.config/claude-usage-widget). v2는 Claude Usage Widget & Token Tracker로 리브랜딩되었으며, claude-token-tracker (+ ctt CLI)로 설치되고 모든 새로운 경로를 사용합니다. 경로가 다르기 때문에 v2를 설치한다고 해서 v1이 제거되는 것은 아닙니다. 이전 위젯은 새 위젯과 함께 로그인 시 계속 자동 시작될 것이므로, 이를 정리해야 합니다.

만약 한 줄 설치 프로그램(저장소 폴더 없음)으로 이전 위젯을 설치했다면,
설치 프로그램을 다시 실행하기만 하세요. 이제 이 프로그램은 이전의 claude-usage-widget (위젯, claude-widget-start, /-stop 바이너리, 자동 시작 항목)을 감지하고 v2를 설치하기 전에 이를 중지하고 파일을 제거합니다:

curl -fsSL https://github.com/StaticB1/claude_ai_usage_widget/raw/main/install.sh | bash

만약 클론(clone)을 가지고 있다면, 하나의 명령어로 최신 버전을 가져오고 동일한 마이그레이션을 실행할 수 있습니다:

cd claude_ai_usage_widget
git pull # 또는: bash upgrade.sh (이는 끌어와서 + 재설치하고 + 다시 시작해줍니다)
bash install.sh

어느 쪽이든 데이터는 자동으로 이전됩니다. 라이브 위젯은 ~/.claude/.credentials.json에서 OAuth 토큰을 다시 읽고, 새로운 로컬 히스토리 DB는 첫 번째 ctt scan 시점에서 ~/.claude/projects에서 백필(backfill)됩니다. 이전 설정 디렉터리인 ~/.config/claude-usage-widget은 수동으로 붙여넣은 토큰이 있을 경우를 대비하여 그대로 남아 있습니다. v2가 정상적으로 작동하는 것이 확인되면 rm -rf 명령어로 삭제할 수 있습니다.

CLI (ctt)는 순수 Python stdlib이며 GTK 없이 작동합니다:

pip install --user git+https://github.com/StaticB1/claude_ai_usage_widget.git
ctt --help

ctt scan # 로컬 스토어로 새 로그 가져오기 (빠르고, 증분적)
ctt summary --period 7d # 이번 주에 토큰과 돈은 어디로 갔을까?
ctt block # 현재 5시간 블록 중 얼마나 사용했지?
...

claude-token-tracker를 실행하면 시스템 트레이에 게이지가 나타납니다:

• 이 링/퍼센티지는 실시간 5시간 플랜 사용량(Pro/Max/Team 한도의 0–100%)입니다. 용량이 임박함에 따라 초록색 → 호박색 → 빨간색으로 변합니다. - 전체 내용은 트레이 아이콘을 마우스 오른쪽 버튼으로 클릭하여 확인할 수 있습니다: LIMITS 섹션(5시간 및 7일 창 + 모델별 주간 한도 등, 각각 재설정됨), 계정별 ACCOUNT 사용량, 그리고 현재 5시간 블록 소모량입니다 (이 부분은 로컬이며 토큰 없이도 작동합니다). 전체 추적기 UI는 Open Dashboard에서 확인하고; Refresh now를 누르면 폴링을 강제 실행합니다. - 창의 **75% / 90% / 100%**에 도달할 때 알림이 발생합니다.

대시보드가 숨겨져 있는 동안에는 폴링 간격이 자동으로 줄어들며, 설정(Settings)에서 계정별 '폴링 비활성화'(disable polling) 스위치를 준수합니다.

실시간 위젯은 claude CLI가 ~/.claude/.credentials.json에 저장하는 OAuth 토큰이 필요합니다. 의존하기 전에 위험 고지 사항을 확인하세요. 토큰 추적기의 모든 기능은 이 없이도 작동합니다.

--period는 다음 값을 허용합니다: today, 5h, 7d, 30d, NNd, NNh, 또는 all.

# USD 또는 토큰 한도 설정, 전역/프로젝트별/모델별 범위 지정:
ctt budget add --name

claude-token-tracker

(또는 ctt gui)

을 열면 다음 내용이 담긴 창이 나타납니다:

**대시보드 (Dashboard)** — 실시간 제한량 (5시간 / 7일 + 모델별 주간 한도), 현재 블록, 헤드라인 총합.
**프로젝트 (Projects)** — 프로젝트별 지출 및 최근 세션.
**분해 (Breakdowns)** — 모델별 및 도구별 사용량 배분.
**예산 (Budgets)** — 진행률 표시줄과 함께 예산 생성/추적.
**설정 (Settings)** — 계정, 폴링(polling), 알림 임계값, OAuth 토큰,
**외관 (Appearance)** (시스템 / 라이트 / 다크 테마, 스위치 실시간 작동).

트레이 메뉴 자체에서도 5시간/7일 제한량과 현재 블록을 단순 숫자가 아닌 인라인 진행률 표시줄로 보여주며, **사용량 패널(Usage panel)...** 항목을 열면 작은 독립형 카드와 함께 동일한 막대 그래프 및 클라우드 연결 상태를 볼 수 있습니다. 이는 앱 인디케이터 드롭다운 자체를 재스타일링할 수 없는 데스크톱 환경(또는 윈도우 매니저)에서 유용합니다.

| 경로 (Path) | 내용 (What it is) | 
|---|---|
`~/.claude/projects/` | 읽기 — Claude Code의 세션 JSONL (트래커의 진실 공급원). |
`~/.claude/.credentials.json` | 읽기 — `claude` CLI가 관리하는 OAuth 토큰 (실시간 위젯에 사용됨). |
`~/.config/claude-token-tracker/history.db` | SQLite — 장기적인 토큰/비용 기록. |
`~/.config/claude-token-tracker/config.json` | 계정, 설정 및 선택적 대체 OAuth 토큰. |
`~/.config/claude-token-tracker/rate_card.json` | 선택적 가격 재정의 (pricing override). |

여러 Claude 로그인(각각은 `~/.claude` 스타일 디렉토리임)을 구성할 수 있습니다.
설치 프로그램으로 상호작용적으로 설정하거나, `config.json` 파일을 직접 편집할 수 있습니다:

{
"accounts": [
{ "label": "work", "claude_dir": "~/.claude", "disable_polling": false, "hide_from_tray": false },
...
}

{
"models": {
"claude-fable-5": [10.0, 12.50, 20.0, 1.00, 50.0],
...
}

튜플은 `[입력(input), 캐시_쓰기_5분(cache_write_5m), 캐시_쓰기_1시간(cache_write_1h), 캐시_읽기(cache_read), 출력(output)]` 순서로 되어 있으며, 100만 토큰당 USD 기준입니다. 편집 후에는 `ctt reprice`를 실행하여 저장된 기록의 비용을 재산정해야 합니다.

cct/
├── parser.py JSONL → Turn (도구 사용 추출, sidechain 플래그)
├── pricing.py 가격표 + 재정의 로더
...

스캔은 **증분적(incremental)**입니다: 각 패스는 크기/수정 시간(mtime)이 변경되지 않은 세션 로그를 건너뛰므로, 10초마다 새로고침할 때 전체 기록을 재파싱하는 대신 활성 세션만 다시 파싱합니다. 행은 upsert로 작성되므로, 파싱 또는 가격 책정 수정 사항이 배포되면 재스캔이 기존 데이터베이스의 기록을 수리하며 이전 숫자를 그대로 두지 않습니다.

캘린더 기간 — `오늘`

, 그리고 일/주/월 예산 창은 로컬 캘린더를 따르므로 월별 한도는 현지 자정(local midnight)에 1일자로 이월됩니다.

| Linux | macOS | Windows |
|---|---|---|
| CLI (`ctt`) | ✅ | ✅ | ✅ |
| 트레이 위젯 + 대시보드 | ✅ (GTK3) | — | — |

GUI는 PyGObject + GTK3가 필요하며, 배포판을 통해 설치합니다(설치 프로그램이 처리함). 라이브러리와 CLI는 **Python 의존성 없이** 순수 표준 라이브러리(stdlib)로 구성되어 있습니다.

pip install pytest
pytest

클론된 상태에서 — 한 명령어(레거시 위젯도 삭제):

bash uninstall.sh

클론이 없는 경우? 설치 프로그램 자체가 제거 프로그램 역할을 합니다:

...

제거 프로그램은 앱 디렉터리, 두 바이너리, `.desktop` 항목, 자동 시작 항목, hicolor 아이콘을 제거합니다. 하지만 재설치 시 수개월의 데이터를 잃지 않도록 `~/.config/claude-token-tracker/`(기록, 예산, 요율표 오버라이드)는 **유지**합니다 — 완전히 깨끗하게 지우려면 해당 디렉터리를 수동으로 삭제하세요.

기여 환영합니다!

**버그 보고 / 기능 요청**— 이슈 열기 **토론 / 협업**— GitHub Discussions **이메일**— [email protected]