Your Codex quota, visible before you open the menu.
A local, open-source companion that adds remaining usage and reset information to the existing Codex account row.
Download the latest release · Security · Privacy · Architecture · Configuration
Important
QuotaPin is an unofficial community project. It is not affiliated with, endorsed by, or supported by OpenAI.
Codex already knows your usage limit. The annoying part is having to open the account menu whenever you want to check it.
QuotaPin keeps the useful part visible in the account row, so checking quota becomes a glance instead of an interruption.
- Glanceable by default. A fresh install adds only the remaining percentage.
- Native-feeling interaction. Short-click the row for the normal Codex menu; hold it for QuotaPin.
- Configurable when you want it. Add reset time, countdowns, status colors, token totals, and custom layouts.
- Local-first. No product telemetry, no account database, and no patching of the official Codex package.
- Fail closed. If QuotaPin cannot identify one unambiguous account row, it renders nothing rather than guessing.
Latest stable: v1.3.1.
2.x beta line: v2.0.0-beta.3. It develops multi-surface placement and account-wide quota forecasting, and never replaces the stable Latest channel until it passes beta acceptance.
| Platform | Status |
|---|---|
| Windows 11 x64 | ✅ Stable / verified on a signed-in machine |
| Windows 10 x64 (2004+) | ✅ Supported baseline · real-device reports welcome |
| Windows 11 ARM64 | 🧪 x64 emulation · CI acceptance pending |
| Windows 10 ARM64 | ❌ Not supported · Windows 10 cannot emulate the x64 Codex package |
| macOS 13+ · Apple silicon / Intel | 🧪 Public package / CI validated; signed-in real-Mac acceptance still pending |
Open the latest stable release.
- Windows: run the versioned
.exeinstaller. - macOS: open the universal
.dmg, then double-click QuotaPin Installer.
Installation is per-user. Windows does not require elevation; macOS does not require sudo, Homebrew, or a separate runtime. Installing or updating never closes or restarts a running Codex session. If QuotaPin cannot attach safely, it waits for the next normal Codex launch.
Note
Upgrading from QuotaPin 1.1.2 or earlier on Windows: run the installer or Quick Start once. The updater in those builds can fail before the update process starts, so it cannot reliably install its own fix. This one-time repair keeps your settings and leaves the running Codex session open. Updates started from QuotaPin are supported again from 1.2.1 onward.
If you prefer a one-command bootstrap, the scripts are public and can be inspected first: install.ps1 · install-macos.sh.
Windows — PowerShell
irm https://raw.githubusercontent.com/WSL043/QuotaPin-for-Codex/main/install.ps1 | iexmacOS — Terminal
curl -fsSL https://raw.githubusercontent.com/WSL043/QuotaPin-for-Codex/main/install-macos.sh | bashThe bootstrap resolves a published immutable GitHub Release, verifies the GitHub SHA-256 digest and package identity, then installs the platform package for the current user. If your threat model requires the bootstrap itself to be immutable too, pin its raw URL to an exact release tag instead of main. Version selection and rollback examples are in configuration.
On Windows, the command install uses the quiet watcher without a tray icon. The guided EXE installer enables the tray companion. Both use the same platform package.
Installing from an existing clone on Windows
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1This also works when the normal PowerShell execution policy is Restricted.
The default keeps the original Codex avatar and account name and adds only the remaining percentage.
Default thresholds are 30% for warning and 10% for critical; both are editable.
Optional pace and runway modules, kept in the same account row.
You can independently show, hide, and reorder:
- remaining percentage;
- responsive account-wide burn pace plus a compact stable runway; the complete uncertainty range stays in the hover;
- status dot and a quota line that can follow the quota modules or span the account row;
- time left and second-by-second countdown;
- reset date and reset time;
- today's token total from this device;
- settled account lifetime token total.
Compact time (4d 8h) works in every UI language. A separate worded module follows the selected language (4 days 8 hours, 4天8小时, or 4日8時間). Hover details expose exact values and make device-local scope explicit where it matters.
Save useful combinations as named views and switch between them without rebuilding the row.
Short-click the account row and Codex behaves normally. Hold the same row to open QuotaPin. Press it again—or click outside—to close the open panel. The native help button, avatar, account name, and normal account menu stay in place.
In the 2.x placement beta, the interaction moves with the visible quota surface: hold anywhere in that surface and the editor opens beside it. The title center, workspace top, composer toolbar, and account row share the same drag, collision, and alignment behavior. The experimental composer side slots were removed rather than leaving inconsistent hit areas.
Drag modules left, right, or into the center; neighboring items make room as you move.
- Quick chooses the usage window, visible modules, and layout.
- Customize controls colors, thresholds, hover text, avatar shape, appearance, and motion.
- Code exposes the validated configuration surface, with reset available if an experiment goes sideways.
QuotaPin integrates with Codex Desktop through a Chromium DevTools Protocol (CDP) endpoint bound to a random port on 127.0.0.1.
CDP is a powerful renderer-control interface. Software attached through it can inspect or modify renderer content, so this is a real trust boundary, not something QuotaPin tries to hand-wave away. If that boundary is outside your threat model, do not run QuotaPin.
The implementation reduces exposure by:
- binding CDP to loopback only and choosing a new ephemeral port per launch;
- attaching only to the exact Codex main-page URL;
- keeping the rate-limit App Server on
stdio; - accepting the app-managed Codex command on Windows only when its Authenticode signature identifies OpenAI;
- not logging tokens, cookies, prompts, or page content;
- sending no QuotaPin product telemetry;
- never patching the official Codex package;
- terminating the Agent after the Codex endpoint closes.
QuotaPin does not claim to defend against malware already running as the same OS user. The full threat model, release integrity checks, SBOM/attestation details, and reporting process are documented in SECURITY.md. Data handling is documented separately in PRIVACY.md.
QuotaPin checks after a successful result no more than once every six hours. A temporary network failure keeps the last verified result and retries sooner, beginning after 15 minutes. Nothing is installed without confirmation, Codex is never restarted, and saved views and preferences survive repair or update.
Codex can change its UI over time. QuotaPin deliberately refuses to render when it cannot identify the account row unambiguously. Observed compatibility and recovery options are documented in compatibility and configuration.
The universal DMG contains Apple silicon and Intel builds. GitHub Actions exercises the final image on native runners under macOS 15 and macOS 26, including install, staged LaunchAgent validation, update, configuration preservation, and uninstall paths. Launch through the signed official Codex runtime remains part of real-Mac acceptance.
What CI cannot prove is the current signed-in Codex account row and real Gatekeeper behavior on a user's Mac. That acceptance step is still open. See the macOS implementation and acceptance boundary, or send a sanitized compatibility report.
- Found a bug? Open an issue with reproduction steps and environment details.
- Have an idea? Search existing requests, vote with 👍, or submit a feature request.
- Want to send code? Read CONTRIBUTING.md first.
- Security issue? Use GitHub's private vulnerability reporting flow described in SECURITY.md.
Windows
Use Start > QuotaPin > Uninstall QuotaPin, or run:
& "$env:LOCALAPPDATA\QuotaPin\unins000.exe"macOS
"$HOME/Library/Application Support/QuotaPin/uninstall.sh"QuotaPin removes its own files and shortcuts. Codex stays untouched.
QuotaPin is released under the MIT License.