Version 0.5.1Public Beta

Install Codex Usage

Native macOS menu bar companion, terminal CLI, and local browser dashboard for checking your OpenAI Codex limits, resets, and remaining quota.

Option 1 · Native Mac App

macOS Menu Bar Companion

Unsigned Public BetamacOS 13+Apple Silicon arm64Unnotarized

Download Beta (ZIP)

Companion Features

Menu-bar-only companion with live quota visibility in your macOS status bar
Tracks every Codex limit reported by your account, including additional named limit buckets
Pressure Check highlighting your most pressured window and pace relative to reset
Current 5-hour and weekly quota remaining percentages and reset countdowns
Refreshes every 60 seconds automatically, plus manual Refresh anytime
Observed session pace and exhaustion runway (calculated after at least 4 successful samples, 3 minutes, and 2 percentage points of observed usage)
Weekly survival/on-pace status once sufficient observations accumulate
Banked reset count and earliest expiration date when reported by Codex
One-click shortcut to open the local browser dashboard for banked-reset redemption confirmation
Optional native macOS notifications (disabled by default)
Launch at Login toggle for continuous companion access
Privacy-safe diagnostics snapshot export
Optional QuotaLint task-fit check that judges whether a task you describe is likely to fit the quota you have left, using your current quota state automatically

Banked Resets: The menu bar app surfaces your banked reset count and expiration, but does not redeem resets directly. Reset redemption and verification remain in the local browser dashboard (codex-usage --web) confirmation flow, which the companion can open.

Prerequisites: The native app bundles its own codex-usage helper, so a separate helper CLI install is no longer required. Python 3 and OpenAI Codex CLI (codex login) are still required on your Mac; OpenAI Codex CLI is not bundled.

First-Launch Gatekeeper Steps (Unsigned Beta)

Because this beta release is unsigned and unnotarized, macOS Gatekeeper blocks opening on first double-click until approved in System Settings. You only need to approve it once:

Download and extract Codex-Usage-macOS.zip.
Move Codex Usage.app to ~/Applications or /Applications.
Ensure OpenAI Codex CLI and Python 3 are installed (Codex CLI is not bundled; the native app bundles its own codex-usage helper).
Try opening Codex Usage.app.
If Gatekeeper blocks it, open System Settings > Privacy & Security.
Find the Codex Usage security message.
Click Open Anyway.
Confirm Open.

Option 2 · Terminal & Local Web

CLI & Local Browser Dashboard

Install the lightweight CLI companion to inspect quotas from your terminal or launch a local browser dashboard.

Installation Command

$curl -fsSL https://www.codexusage.dev/install.sh | sh

Installs to ~/.local/bin/codex-usage without sudo.

Run without installing

If you already have Node and npm, you can run Codex Usage directly from npm without installing it globally.

$npx @codex-usage/codex-usage

npm is only the launcher. Python 3, the OpenAI Codex CLI, and an authenticated Codex account are still required.

View @codex-usage/codex-usage on npm

Available Commands

codex-usage

Terminal view of current 5-hour and weekly quota, remaining percentages, and reset times

codex-usage --web

Localhost browser dashboard with 60-second refresh, session pace/runway, and banked-reset redemption confirmation flow

codex-usage --json

Normalized schemaVersion 1 JSON output for scripting and custom terminal integrations

codex-usage --diagnostics-json

Sanitized diagnostics snapshot for troubleshooting local Codex client connectivity

QuotaLint: The optional QuotaLint task-fit check is available both here on the website and inside the 0.5.1 menu bar app above, where your current quota state is filled in automatically. It is optional and idle until you use it: the app makes an external request only after you open QuotaLint, enter a task, and press Check task. Only that task description and coarse quota state are sent. Repository contents, file paths, Codex history, credentials, diagnostics, and account identifiers are not. Normal quota monitoring stays entirely local.

System Requirements

Operating System

macOS 13+

Architecture

Apple Silicon (arm64)

Python

Python 3

Codex CLI

Installed (not bundled)

Codex Auth

Active session (codex login)

Frequently Asked Questions

Does Codex Usage need root or sudo privileges?

No. The installer places the CLI into ~/.local/bin and never requests administrative or sudo access.

Can the menu bar app redeem banked resets directly?

No. The native menu bar app displays your available banked reset count and earliest expiration date, but does not redeem resets directly. Reset redemption and verification remain in the local browser dashboard (codex-usage --web) confirmation flow, which the menu bar app can open with one click.

How are session pace and runway calculated?

Session pace requires at least 4 successful samples, at least 3 minutes, and at least 2 percentage points of observed usage during the current running session. Pace and runway reflect observed pace in the current session only; they are not an entitlement or guarantee.

What are the platform requirements?

macOS 13 or newer on Apple Silicon (arm64). Python 3, the official OpenAI Codex CLI installed, and an active login (codex login) are required for quota retrieval. The native app bundles its own helper, so a separate helper CLI install is not required (OpenAI Codex CLI itself is not bundled).

Privacy and Architecture

Quota monitoring has no telemetry, no analytics, no Codex Usage cloud account, and no third-party backend. It runs entirely on your machine.

✓RAM-only session data: Usage observations and session pace history remain in memory only. There is no persistent usage history written to disk.
✓Preferences: Notification opt-in preferences and compact notification deduplication keys are persisted locally on your device.
✓Authenticated Codex client: Codex Usage queries your existing authenticated local Codex client. That client communicates directly with OpenAI using your existing authenticated session.
✓QuotaLint is the one exception: it is optional, and the app contacts codexusage.dev only after you open QuotaLint, enter a task, and press Check task. The task text you type is held in memory for that window only and is never written to disk.