winget install --id=aesgalexis.CodexUsageMeter -e A small, privacy-friendly Windows tray application that reads local Codex usage and task-state metadata. It displays weekly and rolling five-hour limits through widgets, a tray icon and a multi-display taskbar indicator without account credentials, analytics, or telemetry.
A small, privacy-friendly Windows tray application that shows your latest Codex usage limit at a glance.
> [!IMPORTANT] > This is an early development version. The app reads rate-limit snapshots written by Codex to local session files. That file format is not a documented public API and may change in future Codex versions.
Codex is not an installer dependency. If Codex is absent, the meter stays idle and reports that no usage data is available. It starts reading automatically after Codex creates a local session. If Codex is later removed, the meter returns safely to the same idle state. The Codex extension for Visual Studio Code is compatible because it writes the same local session data.
The optional widget can use a detailed normal card or a minimal compact usage bar. Both designs use the weekly limit for their percentage and progress, show the five-hour reset countdown, and can be shown temporarily or pinned and dragged anywhere on the desktop.
The separate usage-bar option adds a non-interactive weekly-limit line immediately above the Windows taskbar. It starts at the left edge, shortens from the right as weekly availability falls, and places a short white marker at the rolling five-hour availability. It can remain enabled while either widget design is used for tray hover. Its thickness can be set from one to five pixels, and it can follow the notification area automatically, target a specific detected display, or appear on every display.
| Normal | Compact |
|---|---|
 |  |
The tray menu and usage displays support English and Spanish, with immediate switching from the language submenu.
Download CodexUsageMeter-Setup-win-x64.exe from Releases and run it. The installer works per user, does not require administrator privileges, and keeps a stable location for future upgrades.
The portable CodexUsageMeter-win-x64.zip remains available for users who prefer not to install the app.
Published builds are self-contained: the destination PC does not need the .NET runtime installed.
The package is being prepared for the Windows Package Manager community catalog. Once Microsoft accepts the submission, installation and upgrades will use:
winget install --id aesgalexis.CodexUsageMeter --exact
winget upgrade --id aesgalexis.CodexUsageMeter --exact
Interactive installer builds offer English and Spanish. Portable and silent WinGet installations use the Windows display language on first run. The language can always be changed later from the tray menu and is preserved across upgrades.
The app has no main window. After starting it, look for the circular indicator next to the Windows clock; it may initially appear under the hidden-icons arrow.
If the icon reports that no data is available, run at least one Codex task and select Update now.
Codex writes session events below %USERPROFILE%\.codex\sessions. The app searches recent .jsonl session files, reads only their tail, and extracts the latest rate_limits snapshot. It does not read the files to reconstruct conversations.
Codex local sessions
↓
CodexSessionUsageProvider
↓
UsageSnapshot
↓
Windows tray indicator
The provider compares event timestamps across recent sessions rather than trusting file modification order. It reads both primary and secondary rate-limit windows and identifies them by duration. The tray indicator, widgets, taskbar line and notifications use the weekly window consistently, while the rolling five-hour window is exposed separately through its taskbar marker and widget countdown. Temporary read failures retain the last valid value and mark it as stale.
The reader is isolated behind an IUsageProvider interface so it can be replaced if OpenAI publishes a suitable supported API.
Run registry key.%LOCALAPPDATA%\CodexUsageMeter\settings.json.See SECURITY.md for vulnerability reporting.
For a published build:
For development:
Clone and run:
git clone https://github.com/aesgalexis/codex-usage-meter-windows.git
cd codex-usage-meter-windows
dotnet run --project .\src\CodexUsageMeter.App\CodexUsageMeter.App.csproj
Build and verify:
dotnet build .\CodexUsageMeter.sln --configuration Release
dotnet run --project .\tests\CodexUsageMeter.Tests\CodexUsageMeter.Tests.csproj --configuration Release
Create a self-contained portable build:
dotnet publish .\src\CodexUsageMeter.App\CodexUsageMeter.App.csproj `
-p:PublishProfile=win-x64 `
--output .\artifacts\win-x64
src/
CodexUsageMeter.App/ WPF application and tray integration
CodexUsageMeter.Core/ Stable models and provider contract
CodexUsageMeter.Infrastructure/ Local Codex session reader
tests/
CodexUsageMeter.Tests/ Dependency-free parser/provider checks
Ideas and contributions are welcome. Read CONTRIBUTING.md before opening a pull request.
This is an independent open-source project and is not an official OpenAI product. Codex and OpenAI are trademarks of OpenAI.
Distributed under the MIT License.