Claude 토큰 모니터 🚀 — Windows 데스크톱용 실시간 Claude 사용 HUD

Source: Dev.to

Claude Token Monitor 🚀

⚠️ Disclaimer: 이 도구는 비공식 커뮤니티 기반 툴이며 Anthropic, PBC와는 어떠한 형태로도 제휴·연관·보증·공식 연결되어 있지 않습니다.

세션 중에 Claude 할당량을 얼마나 사용했는지 궁금하셨나요? Claude Token Monitor는 로컬 우선 데스크톱 유틸리티로, Claude 사용량을 실시간으로 보여주는 아름다운 상시 최상단 부동 HUD를 제공합니다 — Claude.ai 웹 앱 할당량과 Claude Code CLI 토큰 소비를 모두 커버합니다.

🔗 GitHub 저장소: github.com/glatinone/claude-token-monitor-usage

📸 화면 예시

HUD는 원형 진행 링이 동적으로 색상을 바꾸는 세련된 글래스모피즘 디자인을 사용합니다:

• 🟢 녹색 — 사용량 낮음
• 🟡 호박색 — 사용량 중간
• 🔴 빨간색 — 사용량 높음 (속도를 낮출 때!)

화면 어디든 드래그해서 위치를 옮길 수 있고, 더블 클릭하면 작은 타이틀 알약 형태로 축소됩니다. 시스템 트레이에서도 제어할 수 있습니다.

✨ 주요 기능

이중 동기화 전략:

• Standalone Mode — 저장된 sessionKey 쿠키를 이용해 직접 API를 폴링
• Browser Extension Sync — Chrome 확장 프로그램이 claude.ai에서 메시지를 보낼 때마다 실시간 통계를 푸시

항상 최상단 부동 HUD — 원형 진행 링, 남은 할당량 %, 리셋 타이머 표시

드래그 가능 & 위치 기억 — 원하는 위치에 끌어다 놓으면 종료 시 위치가 저장됩니다

Claude Code CLI 통합 — 실시간 토큰 파싱(입력, 출력, 캐시 쓰기, 캐시 읽기) 및 Claude Sonnet 가격을 기반으로 한 USD 비용 추정

단일 인스턴스 보호 — TCP 소켓 락으로 중복 프로세스 및 트레이 아이콘 스팸 방지

100% 프라이버시·오프라인 우선 — 모든 데이터는 usage_data.json 파일에 로컬에만 저장됩니다. 로컬 서버는 127.0.0.1에만 바인딩됩니다

🛠️ 아키텍처

구성 요소들의 관계는 다음과 같습니다:

Web Browser (claude.ai)
  └── Chrome Extension MV3
        └── POST JSON ──────────────────────┐
                                            ▼
Terminal / IDE                     Desktop App (Python)
  └── Claude Code CLI               ├── Local HTTP Server :9988
        └── Writes logs ──►         ├── Log Watcher
              ~/.claude/projects/   ├── Direct API Fetcher
              *.jsonl               ├── Storage Manager
                                    ├── CTk Floating HUD
                                    └── Tray Manager

Enter fullscreen mode


Exit fullscreen mode

• Log Watcher — CLI 토큰 이벤트를 위해 %USERPROFILE%\.claude\projects\*.jsonl 파일을 모니터링

• Local HTTP Server (port 9988) — Chrome 확장 프로그램이 푸시한 JSON 페이로드를 수신

• Direct Fetcher — 확장 프로그램이 실행 중이지 않을 때 sessionKey 쿠키를 사용해 Claude API를 직접 폴링

  🚀 설치 및 설정

  사전 요구 사항

• Python 3.10 이상

• Windows OS

  1. 데스크톱 앱 설치

git clone https://github.com/glatinone/claude-token-monitor-usage.git
cd claude-token-monitor-usage
pip install -r requirements.txt
python -m app.main

Enter fullscreen mode


Exit fullscreen mode

Windows 사용자는 run.bat을 더블 클릭하면 의존성을 설치하고 한 번에 실행할 수 있습니다.

2. Standalone Mode (세션 키 설정)

앱이 확장 프로그램 없이 직접 할당량을 조회하도록 하려면:

• claude.ai에 접속해 로그인
• F12 → Application → Cookies → https://claude.ai 로 이동
• sessionKey 쿠키 값(예: sk-ant-sid...)을 복사

시스템 트레이의 C 아이콘을 오른쪽 클릭 → Setup Session Key 선택

• 붙여넣고 OK 클릭 — 위젯이 자동으로 동기화됩니다!

  3. Chrome Extension (선택 사항이지만 권장)

chrome://extensions 페이지 열기

Developer Mode 활성화

• Load Unpacked 클릭 → extension/ 폴더 선택

• claude.ai에 접속해 메시지를 보내면 할당량이 즉시 동기화됩니다!

  🔒 보안·프라이버시

• Zero Cloud Sharing — 사용 데이터는 로컬 디스크의 app/usage_data.json에만 저장됩니다

• Localhost Lock — API 서버는 127.0.0.1에만 바인딩; LAN 접근 불가

• Credential Isolation — Chrome 확장 프로그램은 sessionKey에 절대 접근하지 않으며, 해당 키는 로컬 app/config.json에 (git 무시) 저장됩니다

  🤝 기여

기여를 언제든 환영합니다! Linux/macOS 지원, UI 개선, CLI 로그 파싱 개선 등 어떤 형태든 좋습니다:

• 저장소 포크

• 브랜치 생성: git checkout -b feature/AmazingFeature

• 커밋: git commit -m 'Add AmazingFeature'

• 푸시: git push origin feature/AmazingFeature

• Pull Request 열기

  📄 라이선스

MIT License — 자유롭게 사용·수정·배포 가능.

🔗 전체 프로젝트는 GitHub에서 확인하세요: github.com/glatinone/claude-token-monitor-usage

유용하다고 생각되시면 레포에 ⭐를 달고, Claude 파워 유저들과 공유해 주세요!