Javis603/token-monitor

모든 AI 코딩 도구를 위한 하나의 라이브 대시보드, 모든 기기 간 동기화.

다양한 AI 코딩 도구(Claude Code, Codex, Hermes Agent, OpenCode, OpenClaw, Cursor, Antigravity 등)의 실시간 토큰 사용량(token usage)과 AI 도구 제한(AI Tool Limits)을 보여주는 데스크톱 위젯으로, 실시간 멀티 디바이스 동기화, 과거 사용 트렌드, 그리고 도구, 기기, 모델 또는 세션별 상세 내역을 제공합니다.

Token Monitor는 토큰 사용량, 계정 제한 확인, 세션 상세 정보를 각각 지원합니다:

대부분의 사용량 모니터는 실행 중인 기기 내에서만 유용합니다. Token Monitor는 멀티 디바이스 작업(multi-device work)을 위해 구축되었습니다. 각 기기는 자체 로컬 로그(local logs)를 감시하고, 요약 업데이트를 허브(hub)로 전송하며, 연결된 모든 위젯은 토큰 변경 사항을 거의 즉시 확인합니다.

Claude Code, Codex, Hermes Agent, OpenCode, OpenClaw, Cursor, Antigravity를 위한 실시간 토큰 추적(각 턴(turn) 발생 후 수 초 내에 UI 업데이트)
Server-Sent Events를 통한 실시간 멀티 디바이스 동기화
상세 보기(Breakdown views): 도구, 기기, 모델, 세션 또는 계정 제한별로 그룹화
세션별 상세 정보— Claude Code, Codex 또는 OpenCode 세션을 열어 프롬프트당 토큰을 확인하고, 각 응답의 정확한 토큰 분할 및 사용된 도구까지 확장하여 확인 가능 (로컬 트랜스크립트(transcripts) 또는 데이터베이스에서 온디맨드(on-demand)로 읽으며, 절대 동기화되지 않음)
캐시 히트 통계(Cache hit statistics)— 도구 또는 모델을 클릭하여 입력 토큰(캐시 히트 vs 미스), 출력 토큰 및 히트율(hit rate) 백분율에 대한 상세 내역 확장
비용 상세 내역(Cost breakdown): 토큰 수와 함께 제공
사용 트렌드 및 대시보드(Usage Trends & Dashboard)(선택 사항) — GitHub 스타일의 활동 히트맵(activity heatmap), 스트릭(streaks), 그리고 모든 기기에 걸친 도구별/모델별 누적 사용 기록(막대 및 K-line 뷰)을 제공하는 전용 대시보드 창
AI 도구 제한 감지(AI Tool Limits detection): Claude Code, Codex, Cursor, Antigravity, OpenCode에 대해 세션, 주간, 결제 및 크레딧 범위를 지원하며, DeepSeek 선불 잔액 및 오늘/이번 달 지출액도 포함
선택적 상태 보기(Optional Status view): Claude, OpenAI, Cursor 및 DeepSeek 상태 페이지를 수동 또는 간격 기반으로 재확인
사용자 정의 도구 목록(Customizable tool list): 메인 대시보드에서 도구를 숨기거나, 고정하거나, 순서를 변경 가능

추적되는 항목을 변경하지 않고도 가능
외관 제어 (Appearance controls) — 인터페이스 테마 전환 (라이트 모드 포함), 도구별 벤더 색상, 유리 불투명도 (glass opacity), 블러 (blur), 투명 창 모드
메뉴 바 (macOS) 및 시스템 트레이 (Windows) 팝오버 (popover) — 아이콘 옆에 실시간 비용, 토큰, 또는 Claude/Codex/Cursor/Antigravity/OpenCode 한도 % 표시
플로팅 버블 (Floating Bubble) 모드 — 위젯을 클릭 또는 호버 시 미리보기가 가능한 드래그 가능한 미니 창과 트레이 스타일 콘텐츠로 축소
기록 가능한 글로벌 단축키 (Recordable global shortcut) — 어디서든 창을 표시하거나 숨길 수 있음
로컬 우선 (Local-first): 단일 기기 사용 시 서버가 필요 없음
셀프 호스팅 동기화 백엔드 (Self-hosted sync backend) — 위젯 내 허브 (in-widget hub), Node CLI 허브, 또는 Cloudflare Worker 지원
iOS 위젯 지원 — Worker 허브를 통해 Widgy 및 Scriptable으로 지원
Discord Rich Presence — 오늘의 토큰, 비용, 주요 클라이언트를 방송 (선택 사항)
개인정보 보호 우선 (Privacy-first): 요약된 숫자만이 기기를 떠남

한도 보기 (Limits View)	기기 보기 (Devices View)	모델 보기 (Models View)

세션 보기 (Session View)	세션 상세 (Session Details)	서비스 상태 (Service Status)

사용량 대시보드 — 개요 (Usage Dashboard — Overview)	사용량 대시보드 — 트렌드 (Usage Dashboard — Trends)

기본 설정. 허브, 에이전트, 설정이 필요 없습니다.

npm install
npm start

모든 기기(및 헤드리스 에이전트)가 연결될 단 하나의 허브 백엔드를 선택하세요. 각 기기에서 위젯을 열고 Settings → Multi-device Sync 아래에서 모드를 선택하세요. 위젯은 이 기기의 사용량을 자동으로 기여합니다. 위젯이 없는 기기에서만 npm run agent를 실행하세요.

항상 켜져 있는 한 대의 기기에서 위젯을 열고 Settings → Multi-device Sync를 선택한 뒤 Host hub on this device를 선택하세요. 위젯이 무작위 비밀번호(secret)를 생성하고 다른 기기가 연결할 수 있는 LAN URL 목록을 표시합니다 (Tailscale 또는 ZeroTier 주소도 여기에 표시됩니다). 다른 모든 기기에서는 Connect to a hub를 선택하고 URL + 비밀번호를 붙여넣으세요.

허브는 Token Monitor가 실행되는 동안 작동합니다. (단순히 창을 닫는 것이 아니라) 프로그램을 종료하면 연결된 모든 기기에 대해 허브가 중단됩니다.

# 항상 켜져 있는 기기에서
cp .env.example .env
# TOKEN_MONITOR_SECRET를 개인적인 값으로 설정한 후:
...

원클릭 배포(One-click deploy) — 설정 중에 Cloudflare에서 TOKEN_MONITOR_SECRET 입력을 요청합니다.

또는 수동으로 배포하세요:

cd worker
npm install
npx wrangler login
...

배포된 URL을 각 기기의 Settings → Multi-device Sync 메뉴에 있는 위젯에 붙여넣으세요. iOS 위젯 레시피와 엔드포인트(endpoint) 참조는 worker/README.md를, 허브 HTTP API는 docs/API.md를 확인하세요.

릴리스(releases) 페이지에서 앱을 다운로드할 수 있습니다. 모든 릴리스는 서명되지 않았습니다(unsigned). 릴리스 노트에는 macOS (arm64) 및 Windows (x64)를 위한 첫 실행 잠금 해제 단계가 포함되어 있습니다. 다른 플랫폼은 npm start를 통해 소스에서 직접 실행합니다.

앱 상태는 OS의 사용자 데이터(user-data) 디렉토리에 저장됩니다 — 완전히 삭제하려면 앱과 함께 해당 디렉토리를 삭제하세요.

플랫폼	경로
macOS	~/Library/Application Support/Token Monitor/
Windows	%APPDATA%/Token Monitor/

릴리스는 서명되지 않았으므로, 직접 설치 프로그램을 빌드하는 것을 선호할 수도 있습니다 — 동일한 코드를 사용하되 사용자의 기기에 맞게 빌드합니다. Node.js 18.17+ 버전과 대상(target) OS가 필요합니다 (electron-builder는 Windows에서 macOS .dmg를 교차 빌드(cross-build)할 수 없으며, 그 반대도 마찬가지입니다).

npm install
npm run dist:mac # macOS arm64 .dmg → dist/
npm run dist:win # Windows x64 installer .exe → dist/
...

결과물은 dist/에 저장됩니다. 빌드된 파일은 서명되지 않았으므로, 동일한 첫 실행 잠금 해제 단계가 적용됩니다. Linux 및 Intel Mac은 패키징 대상이 없으므로 npm start로 직접 실행합니다.

모드 A — 로컬 (기본값, 설정 불필요)
widget (Electron) ──▶ tokscale ──▶ ~/.claude, ~/.codex, $HERMES_HOME
모드 B — 동기화 (선택 사항, 다중 기기)
...

위젯은 Settings → Multi-device Sync 설정에 따라 로컬 모드와 동기화(sync) 모드 중 하나를 선택합니다. 허브 자체는 별도의 npm run hub 프로세스, Cloudflare Worker, 또는 위젯 중 하나 내부(Host mode)에서 직접 실행될 수 있습니다. 동기화 모드에서 허브는 Server-Sent Events를 통해 연결된 모든 위젯으로 집계된 통계(stats)를 푸시하므로, 한 기기에서의 업데이트가 몇 초 이내에 다른 기기에도 나타납니다.

⚙ 아이콘을 클릭하세요.

위젯 헤더의 버튼을 클릭하여 설정 패널을 엽니다.

다중 기기 동기화(Multi-device Sync) — 세 가지 모드:

• 로컬 전용(Local only) (이 장치에서만, 허브 없음)
• 허브에 연결(Connect to a hub) (다른 장치의 Hub URL + 시크릿을 붙여넣기)
• 이 장치에 허브 호스팅(Host hub on this device) (여기서 허브를 열어 다른 장치가 연결할 수 있게 합니다. LAN/Tailscale/ZeroTier 주소가 표시됩니다).
  추적 도구(Tracked Tools) — 수집할 AI 도구를 선택하고, 메인 목록에서 도구를 개별적으로 숨기거나, 고정하거나, 재배열합니다.
  AI 도구 제한(AI Tool Limits) — Claude Code, Codex, Cursor, Antigravity, OpenCode, DeepSeek의 제한 감지 및 새로고침 빈도를 선택합니다.
  트렌드(Trends) — 사용 기록에 동의합니다. 켜면 일일 기록을 수집하고 사용 대시보드(활동 히트맵, 연속 기록, 도구/모델별 누적 막대 및 K-라인 차트)를 열 수 있습니다.
  창 동작(Window behavior) — 앱 위에 떠 있는 플로팅 창, 일반 창, 또는 데스크톱 고정 모드를 선택합니다.
  트레이 모드(Tray Mode) — 메뉴 표시줄(macOS) 또는 시스템 트레이(Windows) 팝오버로 전환하고 아이콘 옆에 표시할 항목을 선택합니다: 비용, 오늘 토큰, 총 토큰, 비용 + 토큰, 가장 가까운 Claude/Codex/Cursor/Antigravity/OpenCode 제한 % 잔여량, 또는 아이콘 전용.
  플로팅 버블(Floating Bubble) — 위젯을 드래그 가능한 미니 창으로 축소하고, 클릭하거나 호버 미리보기로 다시 열며, 아이콘, 토큰, 비용, 또는 AI 도구 제한 막대에서 버블 내용을 선택합니다.
  바로가기(Shortcut) — 창을 표시하거나 숨길 전역 바로가기를 기록합니다.
  모양(Appearance) — 인터페이스 테마를 프리셋(Default, Obsidian, 그리고 Porcelain 라이트 모드) 또는 사용자 지정 색상(강조색, 배경, 텍스트, 뮤트)으로 전환하고, 도구별 공급업체 색상, 시스템 유리 효과(system glass), 실시간 점(live dot), 도구 아이콘, Discord Rich Presence, 유리 불투명도, 그리고 유리 블러를 설정합니다.
  고급(Advanced) — allTimeSince와 같은 덜 일반적인 옵션을 위해 기본 settings.json을 엽니다.

위젯 헤더의 고정 버튼은

TOKEN_MONITOR_HUB_URL= # 동기화 모드(sync mode)에 필수 — Worker URL 또는 http://<lan-ip>:17321
TOKEN_MONITOR_SECRET= # 공유 비밀키(shared secret), 허브(hub)와 일치해야 함
TOKEN_MONITOR_DEVICE_ID= # 선택 사항 — 기본값은 호스트 이름(hostname)
...

위젯은 첫 실행 시 기본값으로 사용되는 것과 동일한 환경 변수(env vars)를 읽은 다음, 자체 GUI로 관리되는 설정으로 제어권을 가져옵니다.

모든 값은 CLI 플래그(flag)로도 전달할 수 있습니다 (--hub=, --secret=, --device=, --clients=, --history=, --limits=, --limitProviders=) — 플래그가 환경 변수보다 우선합니다. 덜 일반적인 설정값들(TOKEN_MONITOR_INTERVAL_MS, TOKEN_MONITOR_PORT, TOKEN_MONITOR_STALE_AFTER_MS, TOKEN_MONITOR_HISTORY_INTERVAL_MS, TOKEN_MONITOR_LIMITS_REFRESH_MS, …) 또한 환경 변수 또는 플래그를 통해 허용되지만, 노이즈를 줄이기 위해 .env.example 파일에는 포함되지 않았습니다.

일회성 실행 예시:

npm run agent -- --clients=claude,codex,opencode --once

허브(hub)와 에이전트(agent)는 오직 요약 필드만 전송합니다:

• 디바이스 ID(device id), 호스트 이름(hostname), 플랫폼(platform)
• 기간별 총 토큰 수 (오늘 / 이번 달 / 전체 기간)
• 총 비용 ( tokscale 이 비용 데이터를 반환하는 경우) - 클라이언트별 및 모델별 상세 내역
• AI 도구 제한(AI Tool Limits)이 활성화된 경우, 정규화된 Claude Code/Codex/Cursor/Antigravity/OpenCode 제한 상태

이들은 원본 AI 로그, 프롬프트(prompts), 소스 코드 또는 대화 내용을 전송하지 않습니다. 또한 OAuth 자격 증명, 액세스 토큰(access tokens), 리프레시 토큰(refresh tokens), 이메일 또는 원본 제공자(provider) 응답도 전송하지 않습니다. .env, data/, node_modules/는 gitignore 처리되어 있습니다.

• macOS 또는 Windows
• Node.js 18.17+
• 동기화 모드(sync mode) 전용: 각 에이전트/위젯에서 허브(hub)로의 네트워크 도달 가능성