Claude Usage Widget

English · 한국어 · Website: https://sunggap.github.io/claude-usage-widget/

A tiny, always-on-top, semi-transparent desktop widget for Windows that shows:

• Claude Pro / Max plan usage — current session (5-hour rolling window) %, weekly limit %, and time until each resets
• Today's Claude Code token usage — tokens, request count, and estimated cost (USD) for today's local Claude Code sessions

The UI is available in English and Korean (auto-detected from your OS locale, switchable any time with the EN / 한 button).

This extension, the widget app, and this README were written with Claude Code.

Features

• Always-on-top translucent widget — small, stays out of the way
• Toggle button (⇄) in the top-left switches between two views:
  • Plan usage: current session (5-hour rolling window) %, weekly limit %, time to reset for each
  • Today's tokens: tokens / requests / estimated cost, aggregated from your local ~/.claude/projects/**/*.jsonl logs
• Language button (EN / 한) — switch between English and Korean; the choice is remembered
• Companion Chrome extension — reads plan usage from a logged-in claude.ai tab and forwards it to the widget over loopback (127.0.0.1) only, auto-refreshing every 30 seconds
• Packageable as an .exe, can be registered to auto-start on Windows logon

How it works

• Today's token usage: reads the session logs Claude Code writes locally (~/.claude/projects/**/*.jsonl) and sums today's token usage directly. Cost is an estimate based on publicly listed Claude model pricing.
• Plan usage: this data is only available through claude.ai's own logged-in web app — there is no public API. The extension in chrome-extension/ calls that API from inside your logged-in claude.ai tab and forwards only the resulting JSON to the local widget (http://127.0.0.1:47821). Cookie / session values themselves are never read or transmitted.
• Without the extension, you can instead paste your sessionKey cookie value once into the widget UI (not recommended — see Security notes).

How this compares

There is a similar but much heavier project — projectvelox/claude-usage-widget (unrelated to this one). If you want per-model weekly history graphs, threshold notifications, a mascot, tray-icon styles and 13-language coverage, look at that one. This widget is deliberately smaller and leans on three things:

1. Today's Claude Code local token usage and estimated cost. This widget reads your local Claude Code session logs (~/.claude/projects/**/*.jsonl) and shows tokens used today, request count, and an estimated USD cost derived from per-model pricing. projectvelox reads only the account-level usage endpoint (plan / session / weekly quotas, credit-pool dollars) — it does not aggregate your local per-day token and cost totals.
2. A tiny, glanceable footprint. A ~150 px translucent always-on-top window with two views and nothing else — no layout modes, no notification system, no background polling daemon. It sits in a screen corner and stays out of the way.
3. Plan usage without needing Claude Code. The companion Chrome extension reads plan usage from any logged-in claude.ai browser tab, so it works even if you never use Claude Code. (There's also a one-time manual sessionKey fallback.)

Trade-off to know: this widget's plan-usage path is session/cookie-based via claude.ai's web API, so it depends on that browser session staying valid. projectvelox uses the Claude Code OAuth token (~/.claude/.credentials.json) against api.anthropic.com, which is sturdier for plan usage but requires that you use Claude Code. Pick whichever matches how you work — or run both.

Download (run without building)

Download ClaudeUsageWidget-v0.2.0-win-x64.zip from Releases, extract it anywhere, and run ClaudeUsageWidget.exe inside the extracted folder — no install step. (Keep the .exe next to the files it ships with; it needs them to run.)

Install & run (from source)

npm install
npm start

Build the .exe yourself

npm run dist

This produces release/ClaudeUsageWidget-win32-x64/ClaudeUsageWidget.exe.

Auto-start on Windows logon

Instead of Task Scheduler (which needs admin rights), add a shortcut to the Startup folder:

$exePath = "<repo path>\release\ClaudeUsageWidget-win32-x64\ClaudeUsageWidget.exe"
$startupDir = [Environment]::GetFolderPath('Startup')
$shortcut = (New-Object -ComObject WScript.Shell).CreateShortcut("$startupDir\ClaudeUsageWidget.lnk")
$shortcut.TargetPath = $exePath
$shortcut.WorkingDirectory = Split-Path $exePath
$shortcut.Save()

To disable auto-start, delete the generated .lnk file.

Chrome extension setup (automatic plan-usage sync)

1. Open chrome://extensions → enable Developer mode
2. Click Load unpacked → select this repo's chrome-extension folder
3. Keep one logged-in claude.ai tab open — it syncs to the widget automatically every 30 seconds
4. Click the extension icon → Sync now to refresh immediately

The extension follows your browser's UI language (English or Korean).

Config file

Stored at ~/.claude-usage-widget.config.json (Windows: C:\Users\<username>\.claude-usage-widget.config.json).

Field	Description
claudeSessionKey	(optional) claude.ai sessionKey cookie value, used only to sync plan usage manually without the Chrome extension
claudeOrgUuid	auto-filled organization UUID cache

Security notes

• claudeSessionKey is as sensitive as being logged in. Never share this file or commit it. If it leaks, log out of all devices on claude.ai to invalidate it immediately.
• The Chrome extension requests no cookies permission. It only forwards the result JSON fetched inside the claude.ai page to http://127.0.0.1 (local). Nothing is sent to any external server.
• The bridge server binds to 127.0.0.1 only and is not reachable from the network.

Project structure

src/
  main.js            Electron main process, widget window
  preload.js         renderer <-> main IPC bridge
  usage-reader.js    aggregates today's token usage from local .jsonl session logs
  plan-usage.js      sessionKey-based plan usage lookup (manual fallback)
  bridge-server.js   local (127.0.0.1) HTTP server the Chrome extension posts to
  renderer/          widget UI (HTML/CSS/JS)
    i18n.js          English / Korean string tables + language switching
chrome-extension/    Chrome extension for automatic plan-usage sync
  _locales/          en / ko extension strings

Website & search

A landing page is published with GitHub Pages from the docs/ folder: https://sunggap.github.io/claude-usage-widget/. It carries the SEO basics — a descriptive <title> and meta description, Open Graph tags, SoftwareApplication JSON-LD, a canonical URL, static content and FAQ, plus robots.txt and sitemap.xml.

To get it indexed (needs your Google account): Google Search Console → add property https://sunggap.github.io/claude-usage-widget/ → verify with the HTML-tag method (paste the <meta> into docs/index.html <head>) → submit https://sunggap.github.io/claude-usage-widget/sitemap.xml → Request indexing. Ranking then comes from links and use — share on relevant communities and add the repo to "awesome" lists. Aim for long-tail queries ("Claude Code token usage tracker", "클로드 코드 사용량 위젯"), not broad ones.

License

Personal-use project.

---

한국어

Windows 데스크톱에서 상시 표시되는 작은 반투명 위젯으로 Claude Pro/Max 플랜의 사용량(현재 세션 롤링 윈도우 %, 주간 한도 %)과 오늘 Claude Code 로컬 세션의 토큰 사용량/예상 비용을 확인할 수 있습니다.

UI는 영어와 한국어를 지원하며, OS 언어에 따라 자동 선택되고 위젯의 EN / 한 버튼으로 언제든 전환할 수 있습니다.

특징

• 항상 위에 표시되는 반투명 위젯 — 작고, 화면을 많이 가리지 않음
• 왼쪽 위 전환 버튼(⇄) 으로 두 화면을 오갈 수 있음
  • 플랜 사용량: 현재 세션(5시간 롤링 윈도우) %, 주간 한도 %, 각각의 재설정까지 남은 시간
  • 오늘 토큰 사용량: 로컬 ~/.claude/projects/**/*.jsonl 로그를 집계한 오늘의 토큰/요청 수/예상 비용(USD, 추정치)
• 언어 버튼(EN / 한) — 영어/한국어 전환, 선택은 저장됨
• 크롬 확장 프로그램 동봉 — claude.ai에 로그인된 탭에서 사용량 데이터를 읽어 로컬(127.0.0.1)로만 전달, 30초마다 자동 갱신
• exe로 패키징 가능, Windows 로그온 시 자동 실행 등록 가능

동작 원리

• 오늘 토큰 사용량: Claude Code가 로컬에 남기는 세션 로그(~/.claude/projects/**/*.jsonl)를 직접 읽어 오늘 날짜의 토큰 사용량을 합산합니다. 비용은 공개된 Claude 모델 가격표 기준 추정치입니다.
• 플랜 사용량: claude.ai 웹앱에서만 조회 가능한 내부 API라 공식 API가 없습니다. chrome-extension/ 폴더의 확장 프로그램이 로그인된 claude.ai 탭 안에서 직접 API를 호출해 결과 JSON만 로컬 위젯(http://127.0.0.1:47821)으로 전달합니다 — 쿠키/세션 값 자체는 다루지 않습니다.
• 확장 프로그램 없이도, 위젯 UI에서 sessionKey 쿠키 값을 한 번 수동으로 붙여넣는 방식으로 대체 가능합니다(비추천 — 아래 보안 참고).

이 프로젝트와의 차이

기능이 훨씬 많은 유사 프로젝트로 projectvelox/claude-usage-widget(본 프로젝트와 무관)이 있습니다. 모델별 주간 히스토리 그래프, 임계치 알림, 마스코트, 트레이 아이콘 스타일, 13개 언어가 필요하다면 그쪽을 보세요. 이 위젯은 의도적으로 더 가볍고, 세 가지에 집중합니다:

1. 오늘의 Claude Code 로컬 토큰 사용량과 예상 비용. 로컬 세션 로그(~/.claude/projects/**/*.jsonl)를 읽어 오늘 사용한 토큰 수, 요청 수, 모델별 가격 기준 예상 USD 비용을 보여줍니다. projectvelox는 계정 단위 usage 엔드포인트(플랜/세션/주간 한도, 크레딧 풀 금액)만 읽고, 로컬 일자별 토큰·비용 합계는 집계하지 않습니다.
2. 작고 한눈에 보이는 크기. 두 개 화면만 있는 ~150px 반투명 상시 표시 창 — 레이아웃 모드도, 알림 시스템도, 백그라운드 폴링 데몬도 없습니다. 화면 구석에 두고 볼 때만 보면 됩니다.
3. Claude Code 없이도 플랜 사용량 조회. 동봉된 크롬 확장이 로그인된 claude.ai 탭에서 플랜 사용량을 읽으므로 Claude Code를 전혀 쓰지 않아도 동작합니다. (일회성 수동 sessionKey 대체 방식도 있음.)

알아둘 트레이드오프: 이 위젯의 플랜 사용량 경로는 claude.ai 웹 API 기반(세션/쿠키)이라 브라우저 세션이 유효해야 합니다. projectvelox는 Claude Code OAuth 토큰(~/.claude/.credentials.json)으로 api.anthropic.com을 호출해 플랜 사용량 면에서는 더 견고하지만 Claude Code 사용이 전제입니다. 작업 방식에 맞는 쪽을 고르거나, 둘 다 함께 써도 됩니다.

다운로드 (빌드 없이 바로 실행)

Releases에서 ClaudeUsageWidget-v0.2.0-win-x64.zip를 받아 아무 곳에나 압축을 풀고, 그 폴더 안의 ClaudeUsageWidget.exe를 실행하면 됩니다(별도 설치 없음). exe는 함께 들어 있는 파일들과 같은 폴더에 있어야 실행됩니다.

설치 및 실행 (소스에서)

npm install
npm start

exe로 직접 빌드하기

npm run dist

release/ClaudeUsageWidget-win32-x64/ClaudeUsageWidget.exe가 생성됩니다.

Windows 로그온 시 자동 실행

관리자 권한이 필요한 작업 스케줄러 대신, 시작프로그램 폴더에 바로가기를 등록하는 방법을 권장합니다:

$exePath = "<repo 경로>\release\ClaudeUsageWidget-win32-x64\ClaudeUsageWidget.exe"
$startupDir = [Environment]::GetFolderPath('Startup')
$shortcut = (New-Object -ComObject WScript.Shell).CreateShortcut("$startupDir\ClaudeUsageWidget.lnk")
$shortcut.TargetPath = $exePath
$shortcut.WorkingDirectory = Split-Path $exePath
$shortcut.Save()

자동 실행을 끄려면 생성된 .lnk 파일을 삭제하면 됩니다.

크롬 확장 프로그램 설정 (플랜 사용량 자동 동기화)

1. chrome://extensions 접속 → 개발자 모드 켜기
2. 압축해제된 확장 프로그램을 로드합니다 클릭 → 이 저장소의 chrome-extension 폴더 선택
3. claude.ai에 로그인된 탭을 하나 열어두면 30초마다 자동으로 위젯에 동기화됩니다
4. 확장 아이콘 클릭 → "지금 동기화"로 즉시 갱신 가능

확장 프로그램은 브라우저 UI 언어(영어/한국어)를 따릅니다.

설정 파일

~/.claude-usage-widget.config.json (Windows: C:\Users\<사용자명>\.claude-usage-widget.config.json)에 저장됩니다.

필드	설명
claudeSessionKey	(선택) 크롬 확장 없이 수동으로 플랜 사용량을 연동할 때 쓰는 claude.ai sessionKey 쿠키 값
claudeOrgUuid	자동으로 채워지는 조직 UUID 캐시

보안 참고

• claudeSessionKey는 로그인 상태와 동등한 권한을 가진 민감한 값입니다. 이 파일을 절대 공유하거나 저장소에 커밋하지 마세요. 유출이 의심되면 claude.ai에서 모든 기기 로그아웃하면 즉시 무효화됩니다.
• 크롬 확장 프로그램은 cookies 권한을 요구하지 않고, claude.ai 페이지 안에서 직접 fetch한 결과 JSON만 http://127.0.0.1(로컬)로 전달합니다. 외부 서버로는 아무것도 전송하지 않습니다.
• 브릿지 서버는 127.0.0.1에만 바인딩되어 외부 네트워크에서 접근할 수 없습니다.

웹사이트

소개 페이지: https://sunggap.github.io/claude-usage-widget/ (GitHub Pages, docs/ 폴더에서 배포). 검색 노출용 메타태그·Open Graph·JSON-LD·사이트맵 포함. 색인은 Google Search Console에 속성 등록 후 사이트맵 제출로 요청합니다(구글 계정 필요).

라이선스

개인 용도 프로젝트입니다.