A beautiful, standalone desktop widget for Windows, macOS, and Linux that displays your AI assistant usage statistics in real-time.
π― 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
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.
A toggleable usage history graph now sits below the main widget. Click the graph button in the toolbar to show or hide it.
- 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
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.
- βοΈ 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
Windows:
- Download the latest
Codex-Usage-Widget-{version}-win-Setup.exe(installer) orCodex-Usage-Widget-{version}-win-portable.exe(no install needed) from Releases - Run the installer or portable exe
- Launch "Codex Usage Widget" from the Start Menu (installer) or directly (portable)
macOS:
- Download the latest
Codex-Usage-Widget-{version}-macOS-arm64.dmg(Apple Silicon) orCodex-Usage-Widget-{version}-macOS-x64.dmg(Intel) from Releases - Open the DMG and drag the app to your Applications folder
- 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.appThen try launching the app again.
Linux:
- Download the latest
Codex-Usage-Widget-{version}-linux-x86_64.AppImage(Intel/AMD) orCodex-Usage-Widget-{version}-linux-arm64.AppImage(ARM) from Releases - Make it executable:
chmod +x Codex-Usage-Widget-*.AppImage - 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
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.AppImage2. 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
EOFNote: The
--no-sandboxflag 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/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- Launch the widget
- Click "Login to Codex" when prompted
- A browser window will open β log in to your AI assistant account
- The widget will automatically capture your session
- Usage data will start displaying immediately
- 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)
Right-click the tray icon for: Show/Hide, Refresh, Re-login, Settings, Exit.
| 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%)
- 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
"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 installIf issues persist, open a Support discussion with your OS, Node.js version, and full error output.
- 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
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