Claude Code 사용량을 데스크톱 위젯으로 — Claude Usage Widget
Claude Code를 자주 쓰면서 사용량을 확인하려고 대시보드를 열거나 터미널 명령을 매번 치고 있다면, 이 위젯이 도움 될지도 모른다.
Claude Usage Widget은 Claude Code 사용량을 데스크톱 한구석에 항상 띄워주는 Windows·macOS 위젯이다. 현재 세션, 주간 한도, 최근 5h 블록, 모델별 비용까지 — 브라우저 열 필요 없이 한눈에 보인다.
쓸 만한 점 3가지
1. 상황에 맞춰 골라 쓰는 3-모드
| 모드 | 언제 쓰면 좋은가 |
|---|---|
| Mini | 코드에 집중할 때 — 데스크톱 모서리에 살짝 |
| Normal | 평소 (기본값) — 도넛 차트 + 주간 한도 |
| Detail | 사용 패턴 들여다볼 때 — 세션·기간·블록·모델 한 화면에 |
드래그로 크기 조정하면 모드별로 알아서 기억한다. 한 번 자기 모니터에 맞춰두면 끝.
 |  |  |
| Mini | Normal | Detail |
2. 트레이 아이콘만 봐도 연결 상태가 보인다
위젯 창을 닫아도 시스템 트레이 아이콘은 살아 있다. Anthropic 마크 옆의 작은 상태 점이 sync 성공이면 녹색, 실패면 빨간색으로 바뀐다 — 위젯을 띄우지 않아도 연결 상태가 한눈에 들어온다.
3. 토큰 만료, 알아서 복구된다
Claude Code OAuth 토큰은 가끔 만료된다. 보통은 claude 명령을 다시 한 번 실행해 새 토큰을 받아야 하는데, 이 위젯은 토큰이 갱신된 직후 다음 동기화 주기에 자동으로 다시 붙는다. Windows에서는 credentials.json 파일이 바뀌는 걸 1분마다 감시해 더 빨리 복구되고, macOS에서는 직접 감지가 어려워 Auto sync(기본 5분)가 따라잡는다. 만료 외에도 자격 증명 누락·레이트 리밋·네트워크 오류를 따로 인식해서 배너 메시지로 알려준다.
그 외에도
- OS 사용량 알림 — 5시간 세션 또는 7일 주간 한도가 85% / 95%에 도달하면 OS 알림으로 띄워준다 (같은 블록에서 임계치당 1회, 위젯을 보지 않고 있어도 놓치지 않게)
- Auto-sync 주기 선택 —
Off / 5분 / 10분 / 30분 / 1시간중 골라 쓸 수 있다 (기본 5분) - 배경 투명도 슬라이더 — 백드롭만 단계별로 옅게, 글자·도넛·게이지는 그대로 또렷하게 유지
- 모델 카드 항상 노출 — Detail 모드의 모델 카드는 Opus/Sonnet/Haiku 슬롯이 항상 떠 있어서 (안 쓴 모델은 0으로) 한눈에 비교하기 좋다
- 새 버전이 나오면 백그라운드로 받아두고 “지금 재시작” 버튼 한 번이면 업데이트 끝
- 한국어 ⇄ 영어 즉시 전환
- OS 네이티브 백드롭 — Windows는 Win11 Mica/Acrylic, macOS는 NSVisualEffectView Vibrancy로 화면에 자연스럽게 녹는다
설치
Windows
- Releases 페이지에서 최신
Claude Widget_X.Y.Z_x64-setup.exe를 받는다 - 더블 클릭으로 설치 (Windows 10이라면 WebView2 런타임도 같이 자동 설치된다)
- 실행 — Claude Code에 이미 로그인되어 있다면 별도 설정 없이 바로 사용량이 뜬다
처음 실행 시 Windows SmartScreen이 “알 수 없는 게시자”라고 경고할 수 있다. 개인 빌드라 코드 서명이 들어가 있지 않아서다.
자세히 → 그래도 실행을 누르면 된다.
macOS (Apple Silicon)
- Releases 페이지에서 최신
Claude Widget_X.Y.Z_aarch64.dmg를 받는다 .dmg를 열어Claude Widget.app을/Applications로 드래그- 실행 — Mac에서 한 번이라도
claudeCLI를 써본 적 있으면 Keychain의 토큰을 읽어 바로 사용량이 뜬다
첫 실행 시 Gatekeeper가 “Apple이 확인할 수 없습니다”라며 막을 수 있다. 유료 Apple Developer ID 서명이 아닌 ad-hoc 서명이라서다. Finder에서 우클릭 →
열기를 누르거나, 터미널에서xattr -d com.apple.quarantine "/Applications/Claude Widget.app"한 번 실행하면 된다.
만들면서 했던 고민이나 PyQt6에서 Tauri 2로 갈아탄 과정은 회고 글에 정리했다.