8000 GitHub - ericrihm/claude-usage-monitor: Desktop widget for monitoring AI assistant rate limits and token usage, costs, and cache efficiency. Electron, cross-platform. Β· GitHub
[go: up one dir, main page]

Skip to content

About

Desktop widget for monitoring AI assistant rate limits and token usage, costs, and cache efficiency. Electron, cross-platform.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Β 
Β 

Latest commit

Β 

History

183 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Codex Usage Widget

A beautiful, standalone desktop widget for Windows, macOS, and Linux that displays your AI assistant usage statistics in real-time.

Codex Usage Widget - Main


Features

🎯 Real-time Usage Tracking β€” Monitor both session and weekly usage limits πŸ“Š Visual Progress Bars β€” Clean, gradient progress indicators with configurable warning thresholds ⏱️ Countdown Timers β€” Circular timers showing time elapsed in the current session window πŸ”„ Auto-refresh β€” Updates every 5 minutes automatically, with animated refresh indicator πŸ“ˆ Usage History Graph β€” Toggleable 7-day chart showing session and weekly trends over time 🌍 Currency Support β€” Extra usage displays your account's billing currency (€, Β£, $) 🎨 Modern UI β€” Sleek, draggable widget with dark and light themes πŸ”’ Secure β€” Encrypted credential storage πŸ“ Always on Top β€” User-controlled, stays visible across all workspaces πŸ’Ύ System Tray β€” Minimizes to tray for easy access βš™οΈ Settings Panel β€” Persistent preferences for startup, theme, tray, thresholds, and date/time formats πŸ”” Usage Alerts β€” Desktop notifications when usage crosses configurable warn/danger thresholds πŸ”” Update Notifications β€” Automatic check for new releases on startup πŸ• Configurable Date & Time Formats β€” 12h/24h time, and flexible weekly reset date display πŸ“ Compact Mode β€” Minimal view for when you just need a quick glance


What's New in v1.7.0

🎨 Dynamic Threshold Colors

All usage bars (Session, Weekly, and Extra Usage) now respect your configured warning and danger thresholds:

  • Green below warning threshold
  • Amber at or above warning threshold
  • Red at or above danger threshold

Changes apply immediately when thresholds are adjusted in Settings.

πŸ“ˆ Usage History Graph

A toggleable usage history graph now sits below the main widget. Click the graph button in the toolbar to show or hide it.

Codex Usage Widget - Graph

  • Displays up to 7 days of session and weekly usage history
  • History persists across restarts β€” no need to keep the app running continuously
  • Sonnet and Extra Usage lines appear automatically when those sections are relevant
  • Adaptive x-axis labels β€” shows times for short spans, weekday+hour for medium spans, and dates for longer spans
  • Respects your 12h/24h time format setting
  • Hover tooltip shows exact timestamp and value

🌍 Currency Support

The Extra Usage row now displays the correct currency symbol based on your account's billing currency β€” €, Β£, or $.

For full release history, see the Releases page.


Screenshots

Settings Panel

Codex Usage Widget - Settings

Settings Options

  • βš™οΈ Launch at startup β€” Auto-start with Windows or macOS login
  • πŸ“Œ Hide from taskbar β€” Tray-only mode
  • 🎨 Theme selector β€” Dark / Light / System
  • ⚠️ Warning thresholds β€” Configurable amber and red levels for usage bars
  • πŸ”” Usage alerts β€” Desktop notifications at warn/danger thresholds
  • πŸ• Time format β€” 12h or 24h
  • πŸ“… Date format β€” Controls how the weekly reset date is displayed
  • πŸ“ Compact mode β€” Minimal two-bar view

Installation

Download Pre-built Release

Windows:

  1. Download the latest Codex-Usage-Widget-{version}-win-Setup.exe (installer) or Codex-Usage-Widget-{version}-win-portable.exe (no install needed) from Releases
  2. Run the installer or portable exe
  3. Launch "Codex Usage Widget" from the Start Menu (installer) or directly (portable)

macOS:

  1. Download the latest Codex-Usage-Widget-{version}-macOS-arm64.dmg (Apple Silicon) or Codex-Usage-Widget-{version}-macOS-x64.dmg (Intel) from Releases
  2. Open the DMG and drag the app to your Applications folder
  3. Launch "Codex Usage Widget" from Applications

⚠️ macOS Security Notice: Because this app is not yet notarized with Apple, macOS Gatekeeper may show a "damaged or can't be opened" warning. To fix this, run the following command in Terminal after installing:

xattr -cr /Applications/Codex\ Usage\ Widget.app

Then try launching the app again.

Linux:

  1. Download the latest Codex-Usage-Widget-{version}-linux-x86_64.AppImage (Intel/AMD) or Codex-Usage-Widget-{version}-linux-arm64.AppImage (ARM) from Releases
  2. Make it executable: chmod +x Codex-Usage-Widget-*.AppImage
  3. Run it: ./Codex-Usage-Widget-*.AppImage

Note: AppImage runs without installation on most Linux distributions. On Ubuntu 22.04+, you may need to install a dependency first:

sudo apt install libfuse2

Linux: Desktop Launcher & Autostart (optional)

By default the AppImage runs from wherever you put it. To get a clickable icon in your app launcher (and optionally launch at login), follow these steps.

1. Place the AppImage somewhere permanent:

mkdir -p ~/.local/bin
mv Codex-Usage-Widget-*.AppImage ~/.local/bin/codex-usage-widget.AppImage
chmod +x ~/.local/bin/codex-usage-widget.AppImage

2. Create a desktop entry:

cat > ~/.local/share/applications/codex-usage-widget.desktop << EOF
[Desktop Entry]
Name=Codex Usage Widget
Comment=Monitor AI assistant usage
Exec=$HOME/.local/bin/codex-usage-widget.AppImage --no-sandbox
Icon=$HOME/.local/bin/codex-usage-widget.AppImage
Terminal=false
Type=Application
Categories=Utility;
StartupNotify=true
EOF

Note: The --no-sandbox flag is required for Electron-based AppImages on most Linux systems due to sandbox namespace restrictions. This is an Electron/Chrome limitation, not specific to this widget.

3. Register the entry:

update-desktop-database ~/.local/share/applications/

The widget should now appear in your application launcher. Test it by launching from your app menu before proceeding to autostart.

4. Autostart at login (optional):

mkdir -p ~/.config/autostart
cp ~/.local/share/applications/codex-usage-widget.desktop ~/.config/autostart/

Build from Source

Prerequisites:

  • Node.js 18+ (Download)
  • npm (comes with Node.js)
git clone https://github.com/SlavomirDurej/codex-usage-widget.git
cd codex-usage-widget
npm install
npm start

Usage

First Launch

  1. Launch the widget
  2. Click "Login to Codex" when prompted
  3. A browser window will open β€” log in to your AI assistant account
  4. The widget will automatically capture your session
  5. Usage data will start displaying immediately

Widget Controls

  • Drag β€” Click and drag the title bar to move the widget
  • Refresh β€” Click the refresh icon to update data immediately
  • Graph β€” Click the graph icon to toggle usage history
  • Minimize β€” Click the minus icon to hide to system tray / dock
  • Close β€” Click the X to minimize to tray (doesn't exit)

System Tray

Right-click the tray icon for: Show/Hide, Refresh, Re-login, Settings, Exit.


Understanding the Display

Current Session & Weekly Limit

Column Description
Session Used Progress bar showing usage from 0–100%
Elapsed Circular timer showing how far through the window you are
Resets In Countdown until the window resets
Resets At Actual local clock time / date when the window resets

Color Coding:

  • 🟣 Purple: Normal usage (below warning threshold, default 75%)
  • 🟠 Orange: High usage (above warning threshold)
  • πŸ”΄ Red: Critical usage (above danger threshold, default 90%)

Privacy & Security

  • Credentials stored locally only using encrypted storage
  • No data sent to any third-party servers
  • Only communicates with the official Codex API
  • Logout clears all session data, cookies, and Electron session storage

Troubleshooting

"Login Required" keeps appearing β€” Session may have expired. Click "Login to Codex" to re-authenticate.

Widget not updating β€” Check internet connection, click refresh manually, or try re-logging in from the tray menu.

Build errors β€” Clean reinstall resolves most issues:

rm -rf node_modules package-lock.json
npm install

If issues persist, open a Support discussion with your OS, Node.js version, and full error output.


Roadmap

  • macOS support
  • Linux support
  • Settings panel
  • Remember window position
  • Custom warning thresholds
  • Configurable date & time formats
  • Update notifications
  • Usage alerts at thresholds
  • Compact mode
  • Usage history graph
  • Currency support
  • Organization/Teams support
  • Keyboard shortcuts

Contributors

Special thanks to these contributors who have improved the widget:

  • @cwil2072 - macOS minimize/restore fix, usage history graph
  • @dion-jy - Login flow architecture improvements
  • @goooseman - Login window security improvements
  • @sergkuzn - Linux desktop launcher & autostart documentation

Built with Electron Β· Releases Β· Discussions

About

Desktop widget for monitoring AI assistant rate limits and token usage, costs, and cache efficiency. Electron, cross-platform.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0