CodexPeek – Codex Usage Monitor for Windows

Languages: English (default) · 한국어 · Español · Português (Brasil) · Bahasa Indonesia · 日本語 · हिन्दी · Deutsch · Français · Tiếng Việt · Türkçe · العربية

Codex Usage Monitor is a small native Windows widget for checking your Codex usage at a glance. It shows the primary and secondary rate-limit windows in the taskbar, a floating widget, and the system tray.

Highlights

• Shows primary and secondary Codex usage windows, including reset times.
• Estimates when each window may be exhausted from recent successful observations and shows the estimate in the usage details and taskbar tooltip.
• Keeps update checks inside the app: current, failed, and available-release results are shown in an owned dialog, and a newer release opens only after confirmation.
• Opens the Codex browser authorization flow reliably, including when the default account is logged out.
• Uses the installed Codex CLI's app-server interface instead of parsing authentication files.
• Lets you manually choose among as many as eight isolated usage profiles.
• Supports showing the widget on every taskbar or only on the primary monitor.
• Falls back safely to a floating widget and tray icon when taskbar attachment is unavailable.
• Supports manual refresh, automatic refresh intervals, Windows startup, diagnostics, and localized UI.

Release note: local usage forecasts

The monitor now keeps a small local history of successful usage observations so it can estimate the exhaustion time for each profile and rate-limit window. The estimate is rounded to useful time units, is never uploaded or synchronized, and is only an approximation; it does not promise or change OpenAI's actual limit policy. Forecasting is enabled by default. Use the tray menu's Usage forecasting submenu to disable it or choose Clear usage forecast history. The clear action removes all stored samples; deleting a managed profile removes that profile's samples.

The widget's upper-left dot summarizes the displayed window's current usage pace: green means comfortable, amber means moderate, and red means the current pace may exhaust the limit before reset. Hover details explain the rating using recent observation time, usage increase, and approximate hourly rate. Loading or unavailable measurements use gray; a refresh error keeps the red exclamation mark.

Release note: Windows integration fixes

CodexPeek 0.3.6 fixes two Windows-specific issues. Update checks now initialize the configured native TLS provider and keep network failures in the normal localized error path instead of terminating the app. Browser sign-in now initializes COM on the shell worker before opening the authorization page, so the default account can start the normal login flow even when it is not currently signed in.

How it works

The monitor starts codex app-server --stdio as a local child process and exchanges JSONL messages over standard input and output. The installed Codex CLI handles its own authentication and may contact OpenAI under its existing configuration and network policy.

The monitor requests only the signed-in state and usage windows needed for display. It does not start a Codex task or call codex exec.

Usage profiles

The non-removable Default Codex account system profile uses the Codex home inherited when CodexPeek starts, or the CLI default when CODEX_HOME is not set. You can add managed profiles, each with a separate Codex home under %APPDATA%\CodexPeek\profiles. The limit is eight profiles in total, including the system profile.

Profile labels are names you provide. CodexPeek does not inspect account email addresses or IDs, so confirm the intended ChatGPT account in the browser when adding or signing in again. Selecting a profile changes only the usage that CodexPeek polls and displays. It does not change sign-in for terminals, IDEs, the Codex app, WSL, Remote SSH, or Dev Containers.

Selection is always manual. CodexPeek does not rotate profiles automatically, select one from its remaining limit, or route Codex work through a profile. Deleting a managed profile permanently removes its local profile data, including the separate CLI credentials stored there; check the confirmation carefully.

See Account and credential storage for the exact on-disk layout, legacy-path migration rules, deletion behavior, and security limitations.

Profile manager

You may rename the system profile, but you cannot log it out or delete it. A custom system-profile label changes only what CodexPeek displays; it is not an account identity. Only the profile manager marks that profile as the default account.

The Usage profiles tray submenu lets you select a profile and open Manage usage profiles; it has no add command. Add profiles only with the + below the manager list. There is no bottom Close or Add button: use the window X or Escape to close the manager.

Requirements

• Windows 10 or Windows 11, x64.
• A signed-in Codex CLI with support for account/read and account/rateLimits/read.

Download and run

First verify that Codex CLI is installed and signed in:

codex --version
codex login status

Installer (recommended)

1. Download CodexPeek-Setup-v<version>-x64.exe from the latest GitHub Release.
2. Run setup and follow the prompts. Administrator access is not required.
3. Start Codex Usage Monitor from the Start Menu.

Portable

1. Download codex-peek-v<version>-windows-x86_64-portable.zip from the latest release.
2. Extract the ZIP completely to a writable folder.
3. Run codex-peek.exe from the extracted folder.

Build from source

This option requires Rust 1.85 or later, Visual Studio 2022 C++ Build Tools, and a Windows SDK. It runs the app from the cloned repository and does not create a Start Menu shortcut or an uninstaller.

git clone https://github.com/lch5518/CodexPeek.git
Set-Location .\CodexPeek
.\scripts\build-release.ps1
.\target\release\codex-peek.exe

In PowerShell, run the script from the repository root. Use -Clean for a full rebuild or -Run to launch the freshly built executable:

.\scripts\build-release.ps1
.\scripts\build-release.ps1 -Clean -Run

If PowerShell blocks local scripts, invoke it explicitly:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-release.ps1

From Command Prompt, or by double-clicking from File Explorer, use the .cmd wrapper:

scripts\build-release.cmd
scripts\build-release.cmd -Clean -Run

The wrapper builds target\release\codex-peek.exe; -Run starts that executable after a successful build. Close any running CodexPeek instance before using -Clean.

To check the build and Codex CLI connection without opening the UI:

.\target\release\codex-peek.exe --diagnose

Ask Codex to install it

Copy the prompt below into Codex. It prefers the verified Installer and falls back to a source build only when compatible Release assets are unavailable.

Install CodexPeek on this Windows x64 computer and complete the verification for me.

1. Confirm that this is Windows x64, then run `codex --version` and `codex login status`.
2. Use only the official repository and its Releases:
   https://github.com/lch5518/CodexPeek
3. Prefer the latest `CodexPeek-Setup-v<version>-x64.exe`. Download it together with
   `SHA256SUMS.txt`, find the exact Installer entry in that file, calculate the
   Installer's SHA-256, and continue only if the hashes match. Do not disable security
   controls or run a file whose checksum is missing or different.
4. Install it for the current user without requesting administrator access. Preserve
   existing CodexPeek settings and do not stop a running app or unrelated process;
   tell me if I need to close the app myself.
5. Only if compatible Release assets are unavailable, clone the official repository
   into a new user-writable directory and run `cargo build --release`. If Git, Rust
   1.85+, Visual Studio 2022 C++ Build Tools, or a Windows SDK must be installed, first
   explain exactly what will change and ask for my approval.
6. Never read or print the contents of `%USERPROFILE%\.codex\auth.json`. Authentication
   must be handled only through the installed Codex CLI.
7. After installation or build, run the resulting `codex-peek.exe --diagnose`. If it
   succeeds, launch CodexPeek.
8. Report the selected installation method, installed version, executable location,
   checksum result, and diagnostic result. If anything fails, stop safely and explain
   the exact blocker without exposing sensitive information.

The Installer and Portable editions use %APPDATA%\CodexPeek\settings.json, so settings are shared if you switch between them. The installer adds a Start Menu shortcut but does not enable Windows startup by default.

If the new data root does not exist, CodexPeek moves an existing %APPDATA%\CodexUsageMonitor directory to %APPDATA%\CodexPeek without opening or copying the profile authentication files. If both roots already exist, the new root wins and no automatic merge is attempted.

Initial releases are not code-signed and may trigger Microsoft Defender SmartScreen. Download only from the official release and verify the file against SHA256SUMS.txt.

See the detailed installation guide (Korean) for hash verification, updates, uninstall behavior, diagnostics, and troubleshooting.

Using the monitor

Use the tray menu to refresh usage, choose a 1/5/10/15/30-minute refresh interval, and show or hide the widget. It also provides Windows startup, startup view, authentication refresh, automatic authentication refresh, language, and diagnostics settings. Choose Widget: all monitors or Widget: primary monitor only to control multi-monitor placement; the selection is remembered across restarts.

By default, the UI language follows the Windows locale when it matches a supported language. You can also choose a language manually from the tray menu. Supported languages are Korean, English, Spanish, Brazilian Portuguese, Indonesian, Japanese, Hindi, German, French, Vietnamese, Turkish, and Arabic.

The taskbar widget uses the Windows light/dark system theme for its text and lets the native taskbar material show through its background.

Only one usage request runs at a time. Failed requests retry with increasing delays while the last successful values remain visible.

When forecasting is enabled, successful polls are recorded locally in %APPDATA%\CodexPeek\usage-history.json. The details and taskbar tooltip show a forecast only after enough recent data from the same profile, window, and reset cycle is available. New or stale data is labelled as collecting or stale rather than presented as a current estimate.

If the taskbar widget cannot be attached after an Explorer restart or taskbar layout change, the tray icon remains available and the monitor retries safely.

Privacy and security

The monitor never reads or parses the contents of %USERPROFILE%\.codex\auth.json. Diagnostics check only whether that path exists.

Raw RPC responses are processed only long enough to extract the login type and the displayed rate-limit fields. Tokens, account IDs, email addresses, authentication-file contents, and proxy values are not stored or written to logs.

CodexPeek never reads, parses, or copies any profile's auth.json. For a managed profile, only the corresponding child codex app-server process receives its isolated CODEX_HOME and the file credential-store override. Windows environment variables, the system profile, CLI/IDE configuration, and default authentication files are not changed. Diagnostics report aggregate profile counts and result categories only; they do not include labels, internal profile IDs, paths, or account details.

Settings are stored in %APPDATA%\CodexPeek\settings.json. A bounded diagnostic log is stored in %TEMP%\codex-peek.log.

Forecast history is a separate local JSON file at %APPDATA%\CodexPeek\usage-history.json. It contains only the internal profile ID, Primary or Secondary, usage percent, an optional reset timestamp, and the timestamp of a successful observation. It does not contain email, account ID, profile label or root path, tokens, authentication-file contents, conversation or prompt text, proxy settings, or raw RPC payloads. The history is never sent to a server or synchronized. Samples are retained for at most 30 days and 1,000 samples per profile/window; repeated values and observations less than five minutes apart are skipped to limit disk writes. A corrupt history file is quarantined or reset without preventing normal usage display.

The Usage forecasting tray setting can disable both recording and display. Clear usage forecast history asks for confirmation and deletes every stored sample. Removing a managed profile also removes its forecast history. Installer and Portable uninstall preserve the entire %APPDATA%\CodexPeek directory, so history may remain after the application is removed; use the tray action before uninstall or delete that file/folder manually when a complete cleanup is needed.

For the full data-handling and vulnerability-reporting guidance, see SECURITY.md.

Troubleshooting

Problem	What to do
Codex CLI is not found	Run codex --version and where.exe codex, then ensure Codex CLI is on PATH.
The CLI is unsupported	Update Codex CLI. Required RPC support matters more than the displayed version number.
Logged out or authentication expired	Complete the normal login flow in Codex CLI, then choose Refresh authentication in the tray menu. On CodexPeek 0.3.6 and later, signing in from the tray opens the browser authorization flow even for the logged-out default account.
A managed usage profile needs login	Open Usage profiles, choose the profile, and start login again. Confirm the intended account in the browser. Cancelling leaves the profile available for retry or explicit deletion.
Update check closes or shows no result	Update to CodexPeek 0.3.6 or later, then use Check for updates again. The result appears in a single owned dialog; an available release opens only after you confirm.
One profile cannot refresh	Select another profile if needed. Each profile keeps independent last-good usage and retry state, so one failure does not clear the others.
The taskbar widget is on the wrong monitor	Choose Widget: all monitors or Widget: primary monitor only from the tray menu.
The taskbar widget is missing	Use the floating widget or tray icon, restart Explorer if needed, and select the preferred widget monitor mode.
More detail is needed	Run --diagnose or open Diagnostics from the tray menu.

Development

Source builds require Rust 1.85 or later, Visual Studio 2022 C++ Build Tools, and a Windows SDK. Build and validate from the repository root:

git clone https://github.com/lch5518/CodexPeek.git
Set-Location .\CodexPeek
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets
cargo build --release

Automated checks do not replace the Windows, DPI, multi-monitor, and Explorer recovery scenarios in the release checklist.

❤️ Support

If CodexPeek saves you time, consider supporting its development.

• ⭐ Star this repository
• ❤️ Sponsor on GitHub

Every sponsorship helps keep the project actively maintained.

License

This project is available under the MIT License. See THIRD_PARTY_NOTICES.md for third-party notices.