Claude Count Usage is a minimal, open-source Claude usage tracker — a patch for the Claude Desktop app that surfaces the two stats people actually want to see: how much of your session and weekly usage you've used, and what the current reply cost. No promos, no donate buttons, no bloat.
Created by Abdullah Alhar.
Sidebar usage bars — Session (5h) and weekly token usage, with live progress bars and reset timers, injected directly into Claude's sidebar.
Usage ⚙
Session (5h): 2% ⏱ 4h 53m
[████░░░░░░░░░░░░░░░░░]
Weekly: 23% ⏱ 23h 33m
[████████░░░░░░░░░░░░░]
Top-bar token stats — appended below the existing chat heading (the heading itself isn't touched):
Length*: 33,868 tokens | Cost: 210 credits | Cached for: 60m
No extra launcher needed — this patches the official Claude Desktop app directly.
- Install Node.js if you don't have it.
- Download this repo, or grab the Mac Installer and unzip it.
- Double-click Install.app (from the zip) or
install.command(from the repo).- If macOS shows a security prompt, click Open.
- If Claude Desktop isn't installed yet, the installer downloads it from Anthropic's CDN first.
- Works standalone — pulls the rest of the extension from GitHub automatically.
- Claude Desktop restarts with usage tracking already active.
To remove it, double-click Uninstall.app or run uninstall.command. This performs a full, clean uninstall of Claude Desktop rather than trying to patch it back — reinstall fresh from claude.ai/download afterward if you want to keep using Claude without the tracker.
- Install Node.js.
- Download this repo, or grab the Windows Installer and unzip it.
- Run
install.bat.- If Claude Desktop isn't found, it's installed automatically.
- Works standalone and fetches the rest from GitHub if run alone.
- Claude Desktop restarts with usage tracking active.
To remove it, run uninstall.bat — this fully uninstalls Claude Desktop rather than trying to patch it back; grab a fresh copy from claude.ai/download afterward if you want to keep using it.
(Optional) Run create-shortcuts.bat once afterward to generate desktop shortcuts with proper custom icons instead of the default script icon.
The tracker checks this repo's latest release every 12 hours (turn this off under Settings → Updates, or use Check for updates now). To update, download the new installer for your platform from the release and run it again — Install.app / install.command on Mac, Install.exe / install.bat on Windows.
When Claude Desktop itself updates, the update replaces the patched app with the official one, so the usage bars disappear after the restart that installs it. Run the installer again to bring them back. The tracker shows a notification when a Claude update has been downloaded.
Claude closing by itself in the middle of a task (Mac, v1.4)? Older installers removed Claude's updater helper (ShipIt). From v1.4 on, Claude got far enough into installing its own update to need that helper, and crashed instead. Since v1.5 the helper is left in place. If yours was already removed, the installer reinstalls the latest official Claude Desktop once to restore it; your chats and settings are kept.
Black screen for 30+ seconds when opening Claude (Mac)? macOS is asking whether Claude may use "Claude Safe Storage" in your keychain, and the prompt is often hidden behind Claude's window. Find the prompt, enter your Mac password and click Always Allow. Since v1.4 this is needed once; earlier versions asked again after every install.
Slow start or black screen on Windows? Since v1.4 every launch writes a timing log to %LOCALAPPDATA%\Claude\logs\ccu-startup.log (if it isn't there, check %APPDATA%\Claude\logs). Please attach that file and main.log from the same folder when you report it. The log shows where the time went: before the app started at all, before the window opened, or while claude.ai loaded. Note that patching changes claude.exe, so it is no longer signed by Anthropic, and antivirus software may scan it more thoroughly than the official build.
| Feature | Status |
|---|---|
| Session (5h) usage bar | ✅ |
| Weekly usage bar | ✅ |
| Top-bar token / cost / cache stats | ✅ |
| Blue / orange / red severity colors (70% / 90%) | ✅ |
| Background refresh while idle (every 2 min) | ✅ |
| Update check against GitHub releases | ✅ |
The tracker reads Claude's own API traffic locally — your usage data is never sent to an external server.
Claude API
│
▼
injections/sse-watcher.js Patches window.fetch (MAIN world),
reads SSE events from the /completion endpoint
│
▼
content-components/*.js Injected into claude.ai, tokenizes replies
locally with o200k (message text never leaves the page)
│
▼
background.js Service worker — fetches /usage for session/weekly
percentages, caches locally, pushes updates to open tabs
│
▼
UI injected into the page Sidebar bars + top-bar stats
On Claude Desktop, there's no plugin API to hook into, so the installer patches the app directly: it unpacks Electron's app.asar, injects the same tracker code, repacks it, fixes the macOS integrity hash, and re-signs the app so Gatekeeper doesn't block it.
None of your usage or conversation data leaves your device.
- Message text is never stored or transmitted — only a token count (an integer) is computed
- Tokenization happens locally using the o200k tokenizer
- No analytics, no telemetry
- The only request outside claude.ai is the optional update check to GitHub's public releases API
See PRIVACY.md for full details.
MIT © 2026 Abdullah Alhar — see LICENSE for details.
Found a bug or have an idea? Open an issue — contributions welcome.