codex-quota

A utility for managing isolated Codex CLI profiles and monitoring quota usage across multiple Codex environments.

Includes JSON output for automation and a live terminal dashboard.

Note: This is an independent community tool. It is not affiliated with or endorsed by OpenAI.

Requirements

• Python 3.11+
• Official Codex CLI available as codex

Install Codex CLI:

npm install -g @openai/codex

or

brew install codex

Tested with codex-cli 0.136.0.

Installation

Install from PyPI:

pip install codex-quota

Install from source:

git clone https://github.com/ssh-den/codex-quota.git
cd codex-quota
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

Quick Start

# Initialize (creates config and profiles directory)
codex-quota init

# Add a profile and log in
codex-quota profile add personal --login

# Check quota status
codex-quota status

# Force an auth keepalive refresh for CI or cron
codex-quota wake

# Launch the live terminal dashboard
codex-quota tui

Security

Authentication is fully delegated to the official Codex CLI. codex-quota never reads, stores, or transmits credentials. It sets CODEX_HOME and calls codex on your behalf.

Profile and config directories are created with 0700 permissions on POSIX systems so auth.json and related state are not exposed by a weak umask on multi-user machines.

Script filesystem layout

~/.codex-quota/profiles/
├── personal/
├── work/
└── testing/

~/.config/codex-quota/
└── config.json

The filesystem is the source of truth. Profiles are discovered dynamically. The configuration file stores application settings only and does not maintain a profile registry.

Configuration

Default configuration:

{
  "profiles_dir": "~/.codex-quota/profiles",
  "codex_bin": "codex",
  "default_model": "gpt-5.4-mini",
  "reasoning_effort": "low",
  "refresh_seconds": 30.0
}

Edit ~/.config/codex-quota/config.json to change model defaults or reasoning effort.

On successful status-time auth keepalive, codex-quota also stores a per-profile auth_refresh map in this same config file using UTC ISO-8601 timestamps ending in Z. This state is created lazily, preserves unknown config keys, and never inspects or modifies auth.json.

Initialization

codex-quota init

Behavior:

• Create config directory if missing
• Create profiles directory if missing
• Create config.json if missing
• Preserve existing configuration
• Verify Codex CLI installation
• Print detected Codex version
• Discover existing profiles by scanning ~/.codex-quota/profiles/*

Overwrite configuration:

codex-quota init --overwrite-config

Run bootstrap plus quota verification (--check is an alias):

codex-quota init --verify

Profile management

List profiles:

codex-quota profile list

Add profile:

codex-quota profile add personal

Create and login immediately:

codex-quota profile add personal --login

Create and force device-code auth on headless or remote machines:

codex-quota profile add personal --login --device-auth

Print profile path:

codex-quota profile path personal

Remove profile:

codex-quota profile remove personal

Force remove (non-interactive):

codex-quota profile remove personal --yes

Profile names are validated. Path traversal, path separators, absolute paths, whitespace, and suspicious characters are rejected.

Login

codex-quota login personal

Equivalent to:

CODEX_HOME="$HOME/.codex-quota/profiles/personal" codex login

Use device authorization instead of the local browser callback flow:

codex-quota login personal --device-auth

Create the profile automatically if missing:

codex-quota login personal --create

Combine both when bootstrapping a remote profile in one step:

codex-quota login personal --create --device-auth

Status

All profiles:

codex-quota status

Single profile:

codex-quota status personal

JSON output:

codex-quota status --json

Status collection opportunistically performs an auth keepalive through the official Codex App Server before reading rate limits. When the last successful refresh for a profile is 4 hours old or older, codex-quota calls account/read with refreshToken=true. This refresh is best-effort:

• Auth-related failures are classified as AUTH_REQUIRED
• Transient refresh failures do not block a later successful rate-limit read
• No separate maintenance command is required for normal operation

Example human-readable output:

Profile   Status   5h Left   Week Left
personal  OK       99%       69%
work      AUTH_REQUIRED

Default JSON is safe for CI logs and automation:

• No absolute profile paths
• No raw rateLimits payload
• No plan or credits metadata unless explicitly requested

Machine-readable status output includes these stable top-level fields per profile:

• status for explicit classifications such as AUTH_REQUIRED
• error for the raw internal/backend error string when present
• rate_limits for normalized quota data

Opt in to the extra fields only when you need them:

codex-quota status --json --json-paths --json-raw

Quota lockout detection uses rateLimitReachedType != null. The tool does not infer lockout solely from usedPercent == 100.

Check command

Automation-oriented health check:

codex-quota check

Single profile:

codex-quota check personal

Exit codes:

Wake command

Force the official auth keepalive even when the last successful refresh is still recent:

codex-quota wake

Single profile:

codex-quota wake personal

This is mainly useful for scheduled CI or cron jobs that want to keep managed auth warm proactively. wake follows the same login_status() -> account/read(refreshToken=true) -> account/rateLimits/read pipeline as check, prints the same human-readable table, and exits with the same codes.

Exec

Run Codex under a selected profile:

codex-quota exec personal "Reply with exactly: ok"

Disable forced JSON output:

codex-quota exec personal "Say hello" --raw

exec now respects the user's existing Codex config and rules by default instead of disabling them.

TUI

Launch:

codex-quota tui

Custom refresh interval:

codex-quota tui --refresh 15

The TUI uses Textual and dynamically discovers profiles from the filesystem.

Available commands:

refresh
login <profile> [--device-auth]
exec <profile> <prompt>
quit

Internal quota API

Status collection launches:

CODEX_HOME=<profile-home> codex app-server --stdio

Then performs the following JSON-RPC sequence:

1. initialize
2. initialized
3. account/read {"refreshToken": true} when auth refresh is due
4. account/rateLimits/read

Responses are normalized for display and safe JSON output. Human-readable tables show AUTH_REQUIRED for auth failures instead of large backend payloads. Raw rateLimits values are available only through explicit --json-raw, while raw backend error strings remain available in JSON output.

License

MIT License