Claude Usage Monitor

KDE Plasmoid + Cross-Platform Tauri Tray + Windows AppBar

Real-time Claude AI usage limits, service health, intelligence score, and spending tracker directly in your taskbar.

Three Interfaces, One Collector

	KDE Plasmoid	Tauri Tray App	Windows AppBar
Platform	KDE Plasma 6 (Fedora, Kubuntu, Arch)	Windows, macOS, Ubuntu GNOME, Fedora	Windows 10 22H2 / Windows 11
Interface	Native QML panel widget	System tray popup (frameless)	Docked strip (SHAppBarMessage) + popup
Stack	QML + Kirigami	Rust + Vite + vanilla JS	Python + PySide6
Install	`./install.sh`	`./install.sh` or `./install.ps1`	`./install-windows.ps1` (no admin)
Trigger	Click panel widget	Click tray icon or `Super+Shift+C`	Click docked strip
Data source	`~/.claude/widget-data.json`	`~/.claude/widget-data.json`	`~/.claude/widget-data.json`

All three read the same file written by the shared Python collector at scripts/claude-usage-collector.py.

Highlights

Usage Monitoring Circular progress ring with live countdown (seconds) Session, weekly all-models, and weekly Sonnet limits Prepaid credits balance with auto-reload status Extra Usage: enabled/disabled, monthly limit, used/remaining	Intelligence Score Composite 0-100 "Dumbness Score" detects degradation 5 animated pixel art mascot states Factors: service health, rate limits, API errors, config Predictive alert: "limit in ~Xh at current rate"
Service Health Real-time from status.claude.com (Statuspage API) Component status: claude.ai, Platform, API, Claude Code Active incident details with latest update text Pulsing status dot + DownDetector link	Performance Metrics Token burn rate (output tokens/hour) API error tracking (429/529/overloaded in 2h window) Average response quality (tokens per response) Average latency (user-to-assistant response time) Model distribution bar (Opus/Sonnet/Haiku split)

Mascot States

The Clawd mascot changes based on Claude's performance score:

Score	Level	Mascot	Trigger
0-4	Genius	Crown + sparkles	Fully idle, all services green
5-19	Smart	Coffee cup + steam	Normal session, light pressure
20-44	Slow	Rain cloud + drops	Service degraded or weekly limits ≥50%
45-69	Dumb	Fire flames	Major outage or rate-limit pressure
70-100	Braindead	Tombstone + ghost Clawd	Critical outage / session near cap / errors flooding

Dumbness Score Factors (multi-parameter, continuous-curve)

Factor	Points	Source
Service health	0-30	status.claude.com indicator + active incidents
Session utilization	0-20	`(pct/100)^1.2 × 20` — smooth ramp
Weekly all-models	0-12	`(pct/100)^1.1 × 12`
Per-model weekly (Sonnet + Opus + Design, combined)	0-8	each model's `(pct − 30) / 8.75`, clamped
API errors in 2h window	0-15	Local JSONL; rate-limit errors weighted 2×
Response latency	0-10	Local JSONL; kicks in above 8s avg with ≥5 samples
Burn-rate panic	0-7	Output tokens/hour × session pressure
Adaptive Thinking ON	5	`~/.claude/settings.json`
1M Context OFF	2	`~/.claude/settings.json`

Genius band is deliberately tight (0-4): any realistic working session lands in Smart or Slow, not Genius. Levels cap at 100.

Why is Adaptive Thinking ON a penalty? With Adaptive Thinking enabled, Claude sometimes allocates zero reasoning tokens on complex tasks, causing lazy/shallow responses. Learn more

Requirements

KDE Plasmoid

KDE Plasma 6 (Fedora 40+, Kubuntu 24.04+, Arch, etc.)
Python 3.8+ with Pillow (pip install pillow)
Firefox, Chrome, or Chromium logged in to claude.ai
Claude Code installed (for local activity data)

Tauri Tray App

Windows 10+, macOS 12+, or Linux (Ubuntu 22.04+, Fedora 38+)
Rust toolchain + Node.js 18+
Python 3.8+ for the data collector (3.11+ recommended for accurate reset timers; 3.10 supported)
Firefox, Chrome, or Chromium logged in to claude.ai

Windows AppBar Widget (alternative to Tauri on Windows)

Windows 10 22H2 or Windows 11
Python 3.10+ with pythonw.exe (from python.org or Microsoft Store)
PySide6, pywin32, cryptography (installed automatically by install-windows.ps1)
No admin rights, no Rust/Node toolchain needed. See windows-widget/README.md for details.

Installation

Ubuntu / Debian (any desktop)

git clone https://github.com/MrSchrodingers/claude-usage-widget.git
cd claude-usage-widget
chmod +x install.sh
./install.sh

The installer detects your desktop environment (XDG_CURRENT_DESKTOP) and adapts accordingly:

DE detected	What the installer does
KDE	Builds plasmoid + tray app
GNOME	Builds tray app, installs AppIndicator extension via `gnome-extensions-cli`. Requires logout/login afterwards.
MATE / XFCE / Cinnamon	Builds tray app (native tray, no extra setup)
Hyprland / Sway	Builds tray app (requires `waybar` tray module or equivalent)

If the tray icon doesn't appear on GNOME after relogin:

gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com

Or use Super+Shift+C as an always-available fallback.

Every installer step prints an explicit ✓ OK, ⚠ warning, or ✗ failure status — and a consolidated report at the end summarizes what worked, what was skipped with a hint, and what aborted the install. No more silent failures.

KDE Plasmoid (Fedora, Kubuntu, Arch)

git clone https://github.com/MrSchrodingers/claude-usage-widget.git
cd claude-usage-widget
chmod +x install.sh
./install.sh

Arch Linux notes:

The installer detects paru or yay and prefers them over sudo pacman when available.
For Arch + GNOME, follow the Ubuntu / Debian section above — the same installer handles both.
For Hyprland/Sway, ensure your bar has a tray module (waybar's tray or eww).

The installer will:

Check Plasma 6 and Python 3
Install the data collector to ~/.local/bin/
Install the Plasma widget to ~/.local/share/plasma/plasmoids/
Set up a systemd timer (refreshes every 30s)
Auto-detect your claude.ai organization from browser cookies
Generate initial data
Run sanity checks (binaries present, timer active, ~/.claude/ writable)

Add to Panel

Right-click your KDE panel
Click "Add Widgets..."
Search for "Claude Usage Monitor"
Drag it to your panel

Tauri Tray App (Windows, macOS, Ubuntu GNOME)

On Linux, install.sh handles Tauri automatically. On Windows, use install.ps1 (builds Tauri via Cargo and registers a Scheduled Task for the collector). To build manually:

git clone https://github.com/MrSchrodingers/claude-usage-widget.git
cd claude-usage-widget/tauri-app
npm install
cargo tauri build

The built binary is at src-tauri/target/release/claude-usage-tray. Bundled packages (.deb, .rpm, .msi, .dmg) are generated in src-tauri/target/release/bundle/.

Windows AppBar Widget (PySide6, no Rust/Node)

.\install-windows.ps1

Self-contained alternative to the Tauri build: Python + PySide6 only, no admin, no WebView2. Docks a compact strip at the top of the screen via the Win32 AppBar API; click the strip to open the full popup. Installer copies the collector to %LOCALAPPDATA%\ClaudeUsageMonitor\, registers a Scheduled Task (60s interval), and creates a Startup shortcut.

Running the collector manually

The collector runs automatically under every installer path above. To run it yourself:

# Linux
~/.local/bin/claude-usage-collector.py

# Windows
python "%LOCALAPPDATA%\ClaudeUsageMonitor\claude-usage-collector.py"

On platforms not covered by an installer, schedule it with cron, Task Scheduler, or launchd.

Browser Support

Browser	Linux path	Windows	macOS
Firefox (native)	`~/.mozilla/firefox/`	Native	Native
Firefox (Snap, Ubuntu default)	`~/snap/firefox/common/.mozilla/firefox/`	—	—
Firefox (Flatpak)	`~/.var/app/org.mozilla.firefox/.mozilla/firefox/`	—	—
Chrome	`~/.config/google-chrome/` (encrypted via GNOME Keyring / KWallet)	Native (DPAPI)	Plaintext only
Chromium	`~/.config/chromium/`, Snap, Flatpak (encrypted via GNOME Keyring / KWallet)	Native	Plaintext only

Priority: Firefox first (plaintext cookies, fastest), then Chrome/Chromium as fallback. On KDE/Wayland, if the XDG portal fails to unlock the KWallet entry, Chrome falls back to its "peanuts" (v10) encryption — the collector handles both paths automatically.

How It Works

Browser cookies (Firefox/Chrome/Chromium)
        |
        v
claude-usage-collector.py (every 30s)
        |
        |--- claude.ai/api/.../usage
        |       Session %, weekly limits, reset timers
        |
        |--- claude.ai/api/.../prepaid/credits
        |       Balance, currency, auto-reload
        |
        |--- claude.ai/api/.../overage_spend_limit
        |       Extra usage: enabled, limit, used
        |
        |--- claude.ai/api/.../overage_credit_grant
        |       Credit grant status
        |
        |--- status.claude.com/api/v2/summary.json
        |       Service health, components, incidents
        |
        |--- ~/.claude/settings.json
        |       Adaptive thinking, effort level
        |
        |--- ~/.claude/projects/**/*.jsonl
        |       Errors, tokens, latency, sessions
        |
        v
~/.claude/widget-data.json
        |
        +---> KDE Plasmoid (QML)
        +---> Tauri Tray App (HTML/CSS/JS)

Authentication

The widget reads session cookies from your browser. No API keys or passwords stored.

Firefox: ~/.mozilla/firefox/*/cookies.sqlite (plaintext)
Chrome: ~/.config/google-chrome/Default/Cookies (AES-128-CBC, key from GNOME Keyring or KWallet)
Chromium: ~/.config/chromium/Default/Cookies (AES-128-CBC, key from GNOME Keyring or KWallet)

Data Sources

Data	Source	Scope
Session (5h) usage	claude.ai API (`five_hour`)	All devices
Weekly all-models	claude.ai API (`seven_day`)	All devices
Weekly Sonnet / Opus / Design	claude.ai API (`seven_day_sonnet` / `_opus` / `_omelette`)	All devices
Reset timers	claude.ai API	All devices
Prepaid credits	claude.ai API (`prepaid/credits`)	Organization
Extra usage limits	claude.ai API (`overage_spend_limit` + inline in `usage`)	Organization
Service health	status.claude.com	Anthropic infra
Error rate	Local JSONL	This machine
Burn rate	Local JSONL	This machine
Avg response/latency	Local JSONL	This machine
Adaptive Thinking	Local settings	This machine
Dumbness score	Composite	Combined
7-day chart	Local JSONL	This machine
Peak hours	Local stats-cache	This machine

Features

13 UI Sections

All three interfaces (plasmoid, Tauri tray, Windows AppBar) render the same sections:

Header - "Claude" title + level pill badge + animated Clawd mascot
Session Card - Circular progress ring with colored border + live countdown
Weekly Limits - All models (blue) + Sonnet (green) progress bars
Credits & Spending - Balance, auto-reload, extra usage with progress bar
Service Health - Pulsing dot, status pill, component grid, DownDetector link
Intelligence Score - Emoji label, score pill badge, color-coded background
Activity - Burn rate, errors, adaptive thinking, avg response, latency
Model Distribution - Stacked bar chart (Opus/Sonnet/Haiku) + legend
Quick Actions - claude.ai, Status, Copy Stats buttons
7-Day Activity - Bar chart with rounded tops, today highlighted
Peak Hours - 24-column chart (amber work hours, blue night)
Footer - Sessions count, since date, streak badge, version
Easter Egg - Tap Clawd 5x to cycle mascot states

Tray App Platform Notes

Platform / DE	Tray Click	Keyboard Shortcut	Setup
Windows (Tauri)	Left-click toggles popup	`Super+Shift+C`	`install.ps1` — needs Rust + Node
Windows (AppBar)	Click docked strip	—	`install-windows.ps1` — Python + PySide6 only
macOS	Left-click toggles popup	`Super+Shift+C`	—
KDE Plasma (Kubuntu, Arch, Fedora KDE)	Use the plasmoid	`Super+Shift+C`	—
Ubuntu GNOME / Arch GNOME	Left-click toggles popup	`Super+Shift+C`	Installer auto-installs AppIndicator extension; relogin required
Ubuntu MATE / XFCE / Cinnamon	Left-click toggles popup	`Super+Shift+C`	Native via StatusNotifierItem
Hyprland / Sway	Depends on bar	`Super+Shift+C`	`waybar` tray module or `eww` equivalent

Adaptive Thinking Workaround

If Claude feels "lazy" or gives shallow answers:

// ~/.claude/settings.json
{
  "effortLevel": "high",
  "env": {
    "CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING": "1"
  }
}

This forces full reasoning on every turn. Trade-off: consumes rate limit faster, but significantly better output quality.

Collector CLI

The collector supports several flags useful for diagnostics and testing:

# Verbose log of cookie discovery, decryption, and API calls
~/.local/bin/claude-usage-collector.py --verbose

# Structured health report (human-readable)
~/.local/bin/claude-usage-collector.py --health-check

# Same report as JSON for programmatic consumption
~/.local/bin/claude-usage-collector.py --health-check --json

# Preview each mascot state without touching the live data
~/.local/bin/claude-usage-collector.py --test-state=genius
~/.local/bin/claude-usage-collector.py --test-state=smart
~/.local/bin/claude-usage-collector.py --test-state=slow
~/.local/bin/claude-usage-collector.py --test-state=dumb
~/.local/bin/claude-usage-collector.py --test-state=braindead

--health-check distinguishes three failure modes: no browser profile, got cookies but API rejected them (session expired), and got cookies + API response but the collector itself crashed parsing it (bug — please report). Installers use it to decide between Live and Offline modes.

Uninstall

Linux (KDE plasmoid + Tauri tray, any DE)

cd claude-usage-widget
./uninstall.sh

Removes: collector binary, plasmoid, systemd timer, tray binary, autostart entry, and only the widget-owned files in ~/.claude/ (widget-data.json, widget-config.json, widget-status-prev.json). stats-cache.json belongs to Claude Code itself and is never touched.

Windows Tauri tray (installed via `install.ps1`)

.\uninstall.ps1

Windows AppBar widget (installed via `install-windows.ps1`)

.\uninstall-windows.ps1

Each Windows uninstaller targets only the artifacts its matching installer created.

Troubleshooting

First step: run the health check

~/.local/bin/claude-usage-collector.py --health-check

The report pinpoints the failing layer (browser profile missing, cookies not decryptable, session expired, or collector bug) and prints the exact next action. Installers use the same check and include its output in the post-install summary.

Widget shows `--` or no data

Run --health-check first (above) to pinpoint the cause
Run ~/.local/bin/claude-usage-collector.py --verbose for a detailed log
Make sure you're logged in to claude.ai in Firefox/Chrome

Widget shows `Offline` instead of `Live`

Your browser session may have expired — log in to claude.ai again
Visit claude.ai to refresh the cf_clearance cookie
If --health-check reports a collector bug (not an auth failure), please file an issue with the --verbose output

Chrome cookies not working (Linux)

GNOME: Ensure secret-tool is installed (sudo apt install libsecret-tools)
KDE / Wayland: ensure kwallet-query is available (sudo dnf install kwallet or sudo apt install kwalletmanager-5). If it is installed and cookies still don't decrypt, the KWallet entry may be stale — reset it with kwallet-query -w 'Chrome Keys' -f 'Chrome Safe Storage' kdewallet and restart Chrome. The collector also falls back to the "peanuts" (v10) scheme automatically when the XDG portal can't unlock the keyring.
The collector tries GNOME Keyring first, then KWallet, then the peanuts fallback

Firefox on Ubuntu Snap

If you see cookies=0 for Firefox, you're likely using the default Snap build whose sandbox blocks cookie reads. Install the native Firefox (Mozilla PPA) or use Chrome, then re-run --health-check.

Claude feels "dumb" or lazy

Check the Dumbness Score in the widget
Disable Adaptive Thinking (see workaround above)
Check status.claude.com for incidents
If session > 80%, wait for the 5h window to reset

Timer not running

systemctl --user status claude-usage-collector.timer
systemctl --user enable --now claude-usage-collector.timer

Tauri app: tray icon not visible (Linux)

On GNOME, install the AppIndicator extension: gnome-extensions install appindicatorsupport@rgcjonas.gmail.com
Use Super+Shift+C as alternative

Supported Plans

Plan	Features
Max (20x)	All features, full limits tracking
Max (5x)	All features, full limits tracking
Pro	Session %, weekly %, dumbness score
Free	Session %, dumbness score

Tech Stack

KDE Plasmoid: QML (Qt 6) + Kirigami + PlasmaComponents3
Tauri Tray App: Tauri v2 (Rust) + Vanilla JS + Vite + Canvas
Windows AppBar Widget: Python 3.10+ + PySide6 + pywin32 (SHAppBarMessage)
Data collector: Python 3.8+ (stdlib + cryptography for Chrome AES/peanuts decryption)
Sprite generator: Python 3 + Pillow
Scheduling: systemd user timer (Linux, 30s) or Scheduled Task (Windows, 60s)
Tests: tests/test_collector_paths.py (pytest, stdlib only)
APIs: claude.ai (authenticated), status.claude.com (public)

Security

All DOM rendering uses textContent/createElement (zero innerHTML)
CSP: default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' asset: tauri:
Tauri shell:default scope (open limited to http(s), mailto:, tel:) is the only runtime capability requested
JSON validation + 1MB size cap on widget-data.json before rendering
No API keys, tokens, or passwords stored on disk by the app
Browser cookies are read locally, decrypted in memory, and used only to call claude.ai and status.claude.com — never logged (verbose mode prints cookie names only) and never written back to disk
widget-data.json is written at mode 0600; credentials never leak into it

MIT License | Made by MrSchrodingers, guizzi-glitch & asm444

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
chrome-extension		chrome-extension
docs/superpowers		docs/superpowers
plasmoid		plasmoid
screenshots		screenshots
scripts		scripts
tauri-app		tauri-app
tests		tests
windows-widget		windows-widget
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install-windows.ps1		install-windows.ps1
install.bat		install.bat
install.ps1		install.ps1
install.sh		install.sh
uninstall-windows.ps1		uninstall-windows.ps1
uninstall.bat		uninstall.bat
uninstall.ps1		uninstall.ps1
uninstall.sh		uninstall.sh

Folders and files

Latest commit

History

Repository files navigation