Monitor Token is a lightweight, always-on-desktop Codex Token usage floating window, supporting Windows and macOS. The problem it solves is: Codex's session records and weekly quota information are scattered in different places, and Monitor Token organizes them into a floating window that does not interrupt work.
Main capabilities
- Today, this week, and this month Token statistics
- Codex main weekly quota used percentage and reset time
- Three display styles: gauge card, minimalist status bar, lightweight card
- Four number formats: plain, thousands separator, smart abbreviation, fixed M
- Interaction methods: drag to move, double-click to refresh, right-click for all configuration
How to use Before running, please install and log in to Codex CLI first. The program will automatically read the local ~/.codex/sessions and attempt to obtain the main weekly quota through the local Codex service. When the server-side quota is temporarily unavailable, you can right-click to set a manual weekly Token quota. Right-click the window to switch styles, statistics period, number format, or set a manual weekly quota.
Requirements: Windows 10/11 or macOS 12+, Python 3.9+, a logged-in Codex CLI. When activating the virtual environment on macOS, use the corresponding command (the specific command content is not provided in the materials).
Technical implementation
- Incrementally scan new Token events in ~/.codex/sessions to avoid reading everything in full each time.
- Aggregate today's, this week's, and this month's usage by local time zone.
- Call the local Codex app-server in the background to obtain the main weekly quota, and fall back to the most recent local session snapshot on failure.
- PySide6 is only responsible for rendering the floating window; scanning and quota requests will not block the interface.
Applicable scenarios Suitable for developers who need to know Codex Token consumption and remaining weekly quota at any time, and view usage through a desktop floating window without interrupting work.
Limitations and notes
- The current installation package has not yet undergone commercial code signing. Windows may show a SmartScreen prompt; on macOS, on first launch you can right-click the app in Finder and select "Open". Only download the app from this repository's Releases.
- The local Token count comes from the session files retained on the current device; the weekly quota percentage comes from the Codex service. The two use different bases, so the statistics are not exactly the same as what you see on the web page.
- The current Release only provides Windows and macOS; Linux support is on the roadmap.
- More complete accessibility and high-DPI adaptation, as well as Windows/macOS code signing, are still planned.
The project welcomes Issues or Pull Requests. For development instructions, see CONTRIBUTING.md; for version history, see CHANGELOG.md.
