PulseMeter

PulseMeter is a free local Windows tray app for OpenAI Codex usage limits. It shows rate-limit remaining, reset credits, account usage, local project usage estimates, and local token-burn attribution in a compact floating window.

PulseMeter is not affiliated with OpenAI.

Download the App

Download PulseMeter 0.6.3 for Windows, extract the ZIP, and run PulseMeter.exe.

• A matching .sha256 checksum file is attached to each GitHub release.
• Windows 10 or Windows 11, 64-bit.
• No .NET install required for the portable release ZIP.

Only run release zips you downloaded from a PulseMeter release page you trust. The Source code (zip) and Source code (tar.gz) links on GitHub Releases are automatic GitHub source archives for developers, not the portable Windows app.

New in 0.6.3

• Coding Runway now separates current runway confidence from the activity-qualified baseline, uses the modeled timing range for medium-confidence forecasts, and labels momentum differences as percentage points per hour.
• The chart legend now matches the rendered recorded usage, unmeasured gaps, forecast, sustainable pace, limit, and reset markers.
• Compact and expanded headers now offer a dedicated minimize action, and automatic foreground behavior respects a window the user intentionally minimized.
• The Windows taskbar keeps its live weekly usage badge while the notification-area icon remains the stable PulseMeter app icon; the exact weekly percentage remains available in its tooltip.
• Accessibility and regression coverage were expanded for the new forecast wording, header behavior, taskbar/tray presentation, and chart legend.

Version History

Version	Highlights
0.6.3	Honest runway confidence and ranges, clearer momentum units and chart legend, dedicated minimize behavior, and stable tray identity.
0.6.2	Persistent Return Notes, clearer Coding Runway and Block Planner decisions, live taskbar usage badges, and Open in Codex project actions.
0.6.1	Activity-qualified momentum, Return Note, quick access, support snapshots, project location actions, and tray confidence state.
0.6.0	Block Planner, recovery watching, state-aware Usage Momentum, and more resilient Coding Runway history and forecasting.
0.5.0	Graph-first Coding Runway for 5-hour and 7-day limits, statistical pace modelling, and persistent usage samples.
0.4.0	Project Health comparisons, clearer rate-limit guidance, and a redesigned analytical dashboard.
0.3.1	Fixed stale live usage after a reset credit cleared the short rolling limit.
0.3.0	More reliable live readings, reusable app-server connections, and improved navigation and window placement.
0.2.1	Clearer compact-tray limits, reset times, and action controls.
0.2.0	Burn Analysis, Needs Attention signals, Limit Runway, and Idle Drain diagnostics.
0.1.1	Apache 2.0 licensing and the public contribution and security foundations.
0.1.0	Initial public build with the floating HUD, tray controls, live usage sync, and local usage summaries.

See the full changelog for detailed changes or browse all GitHub releases.

Who This Is For

• Windows users who want Codex rate-limit and reset-credit visibility without opening extra dashboards.
• Codex CLI or Codex Desktop users who want a small always-available tray HUD.
• People who prefer local-first tools: no telemetry, no UI scraping, and no stored credentials.

Have feedback? Comment on the pinned issue: what Codex usage data should PulseMeter show next?

Want to help share PulseMeter? See DISCOVERABILITY.md.

Screenshots

PulseMeter keeps the most important usage signals, next steps, planning tools, and local diagnostics in one compact Windows dashboard.

Limits and planning

Needs Attention	Return Notes
Prioritized local signals with direct review actions.	Keep multiple handoff notes ready across app restarts.
Rate Limits	Weekly Pace
See remaining capacity, reset timing, and current status.	Understand the daily allowance needed to stay within the weekly limit.
Coding Runway	Block Planner
Compare current pace with a sustainable pace and estimated limit timing.	Test focused work blocks against the current forecast.
Reset Credits
Track available reset credits and approaching expiry dates.

Usage insights

Account Usage	Project Usage
Review account-level usage summaries and recent activity.	Compare privacy-safe local project estimates and trends.
Burn Analysis	Daily Usage
See which local projects lead the estimated 30-day token burn.	Compare recent daily activity with the longer-term median.

Local tools

Customize	Project Location
Choose exactly which dashboard sections stay visible.	Confirm the observed path before opening it in Codex, Explorer, or PowerShell.
Support Snapshot	Desktop Process Snapshot
Preview a redacted local diagnostic before copying it.	Measure PulseMeter-observed Desktop helper processes without reading task content.

Windows integration

Compact HUD	Taskbar percentage
Keep the essential limits visible in a small always-available HUD.	See the live weekly percentage without keeping the dashboard open.

Quick Start

1. Download PulseMeter-0.6.3-win-x64-portable.zip from GitHub Releases.
2. Extract the zip to a normal folder, for example Documents\PulseMeter.
3. Run PulseMeter.exe.
4. If Windows shows an unknown-publisher or SmartScreen warning, choose More info, then Run anyway.

Press F5 at any time to refresh usage immediately.

Minimum Requirements

• Windows 10 or Windows 11, 64-bit.
• No .NET install required for the portable release zip.
• Codex CLI installed and signed in for live usage sync.
• Internet access for Codex/OpenAI usage data.

Mock Mode works without Codex CLI and shows full showcase demo data, including alert states.

Unsigned App Notice

PulseMeter is currently unsigned. Windows may warn that the publisher is unknown because this alpha release does not use a paid code-signing certificate yet.

That warning is expected for this build. It is still a trust decision: only run the app if you downloaded it from the official release location you intended to use.

What It Shows

• Remaining 5-hour and weekly Codex rate limits.
• Compact tray reset times: local time for 5-hour limits and weekday plus time for weekly limits.
• Reset-credit count and expiry dates when available.
• Weekly Pace guidance showing the daily allowance needed to stay within the weekly limit.
• Account usage summary and recent daily usage.
• Project Health showing 7-day usage, change versus the prior 7 days, 30-day share, and focused project details.
• Burn Analysis ranking local projects by estimated token burn over the last 30 days.
• Needs Attention automatic alert signals for local usage and rate-limit risk.
• Runway Forecast estimates when the selected rate-limit pool may run out before reset.
• Activity-qualified Usage Momentum that learns from locally observed Codex activity or meaningful quota movement.
• Multiple persistent Return Notes for next steps you want to resume across PulseMeter restarts.
• Privacy-safe local support and Desktop process snapshots available from the tray.
• Confirmed Project location actions for opening the observed folder in Codex or Explorer, or starting Windows PowerShell there.
• Idle Drain Detector flags usage movement while Windows reports you were idle.
• Live, stale, unavailable, or mock sync status.
• Taskbar and notification-area icons with live weekly percentage and confidence state, plus show, hide, quick access, refresh, diagnostics, mock mode, and exit controls.

Project usage, Burn Analysis, automatic alert signals, Limit Runway, and Idle Drain Detector are local estimates and diagnostics, not billing-exact claims.

How Live Mode Works

PulseMeter talks to the local Codex CLI/app-server protocol. The Codex Desktop window does not need to be open, so it can also be useful for Codex CLI users.

PulseMeter looks for Codex CLI in this order:

• PULSEMETER_CODEX_PATH
• CODEX_CLI_PATH in %USERPROFILE%\.codex\config.toml
• %LOCALAPPDATA%\OpenAI\Codex\bin\codex.exe
• %USERPROFILE%\.codex\bin\codex.cmd
• codex on PATH

If Codex CLI is not found, is not signed in, or codex app-server is unavailable, PulseMeter stays open and shows an unavailable status. Mock data is only used when Mock Mode is enabled deliberately.

Privacy Short Version

• PulseMeter is local-only and has no telemetry.
• It does not modify Codex Desktop, scrape the UI, or use OCR.
• It does not ask for passwords, API keys, or tokens.
• In live mode it may read %USERPROFILE%\.codex\auth.json only to request reset-credit expiry metadata from OpenAI.
• It may read %USERPROFILE%\.codex\state_5.sqlite, %USERPROFILE%\.codex\sessions, and local rollout token_count records to estimate project usage and Burn Analysis shares.
• It does not parse or display Codex message text for project usage or Burn Analysis estimates.
• Burn Analysis groups local session token metadata by project and does not display chat titles or prompt text; project paths and thread IDs remain local attribution metadata.
• Automatic alert signals use local usage and rate-limit numbers; they do not read prompt text or Codex message content.
• Idle Drain alerts do not read prompt text or Codex message content.
• Local app settings and a bounded Runway Forecast observation history are stored under %LOCALAPPDATA%\PulseMeter. The history contains usage percentages, reset and observation times, and rate-limit labels only; it does not contain prompt or message content.
• User-created Return Notes persist locally across restarts. Their payload is protected for the current Windows user and is not uploaded; the app advises against entering secrets or customer data.

See PRIVACY.md and SECURITY.md for more detail.

Roadmap

• Code signing for Windows releases
• Better current-thread or current-project detection
• Optional in-app update check

Open Source

PulseMeter is open source under the Apache License 2.0, which allows commercial use, modification, redistribution, and private use under Apache-2.0 terms.

The license does not grant permission to imply official OpenAI/Codex affiliation or misuse the PulseMeter name, logo, or release assets.

Small bug fixes and documentation fixes are welcome. Larger features, dependency changes, architecture changes, and refactor-only work should start with an issue first. See CONTRIBUTING.md.

Uninstall

1. Exit PulseMeter from the tray menu.
2. Delete the extracted PulseMeter folder.
3. Optional: delete %LOCALAPPDATA%\PulseMeter to remove local settings, cached reset-credit countdowns, and Runway Forecast observations.

Current Limitations

• Live mode depends on the installed Codex CLI and signed-in Codex state.
• If live app-server access fails, PulseMeter shows unavailable or stale last-good live data.
• The rate-limit and usage parsers are defensive because app-server payloads may evolve.
• Exact current Codex Desktop thread detection is not implemented.
• Project usage and Burn Analysis are estimates, not billing-exact accounting. Raw local thread activity is used only for ranking/share and is scaled to account usage.
• Reset credit rows use HUD-local numbers in the UI. Real server credit IDs are not displayed or stored.
• If the reset-credit endpoint is unavailable, PulseMeter falls back to the previous count-based reset-credit display.

Visual Harness

The development-only visual harness opens the real PulseMeter window with showcase mock data and no command-line arguments:

dotnet build tools\PulseMeter.VisualHarness\PulseMeter.VisualHarness.csproj
tools\PulseMeter.VisualHarness\bin\Debug\net8.0-windows\PulseMeter.VisualHarness.exe

The harness must run from a worktree containing both PulseMeter.slnx and .git. It stores all settings and visual state under artifacts\visual-harness\state in that exact worktree, rejects reparse-point paths, and never falls back to %LOCALAPPDATA%.

Its dependency graph uses MockCodexUsageService from the first refresh and excludes live Codex/app-server, reset-credit HTTP, project-attribution, foreground-window, idle-time, clipboard, and production tray behavior. It is for local UI inspection only and is not part of the published PulseMeter app.