AI Usage Tray

Windows tray icons for local Claude Code and Codex CLI usage.

The app runs four notification-area icons:

• Claude 5-hour window
• Claude weekly window
• Codex 5-hour window
• Codex weekly window

Each icon shows percentage left. Clicking any icon opens the native stats dashboard with today's totals, Claude and Codex API-value estimates, model split, top projects/tools, activity heatmap, and recent daily totals.

Use Python 3.11+ on Windows.

git clone https://github.com/LLRHook/usage-widget.git
cd usage-widget
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe .\tray.py --install-startup

The installer writes a current-user Run registry entry named AI Usage Tray and launches the tray immediately. It also removes legacy Startup-folder shortcuts from older builds.

.\.venv\Scripts\pythonw.exe .\tray.py

Right-click any tray icon for Refresh now, Open dashboard, or Quit.

.\.venv\Scripts\python.exe .\tray.py --uninstall-startup

To remove the old Windows widget package from previous builds, run:

Get-AppxPackage -Name AIUsageWidget | Remove-AppxPackage

• Claude data is read from %USERPROFILE%\.claude\projects.
• Codex data is read from %USERPROFILE%\.codex\sessions.
• Claude plan percentages come from probe_claude.py, which uses Claude Code's local OAuth credentials and caches rate-limit headers in %TEMP%\claude_ratelimits.json.
• Codex percentages and API-value estimates come from local Codex token_count payloads. Cost estimates use OpenAI list prices for the detected model and treat cached input at the cached-input rate when available.

No telemetry is sent by this app except the optional Claude rate-limit probe to Anthropic when probe_claude.py refreshes its cache. Cost figures are local estimates for comparison, not billing statements.