Languages / 语言： English · 简体中文

Codex Quota

A local CLI for managing multiple Codex accounts, comparing quota at a glance, and switching Codex Desktop credentials without repeating the full logout-and-login flow.

Credentials stay on your machine under ~/.codex-quota/. Codex Desktop continues to use ~/.codex/auth.json as usual.

Purpose

This project focuses on two everyday problems when you run more than one Codex account:

1. Which account should I use next?
   With two or more accounts, it is easy to lose track of what is left on each plan. codex-quota status shows reset times, remaining quota (5-hour and weekly windows), available rate-limit resets, plan, and auth warnings so you can pick the right account quickly.

2. Switching accounts in Codex Desktop is tedious.
   The usual path is logout, authenticate a new account, complete 2FA, then jump back to Desktop. This tool compresses that flow to quitting Codex Desktop, activating the next stored account, and reopening Desktop:

   quit Codex Desktop  →  activate next account  →  reopen Codex Desktop
   

Important

Always quit Codex Desktop before activate, then reopen or refresh Desktop after switching. If Desktop is still running, use activate --force only when you accept that credentials may not apply until restart.

Prerequisites

• macOS
• Codex CLI (codex) on your PATH
• bash, jq, and curl

Get started

1. Clone the repository

git clone <repository-url> codex-quota
cd codex-quota

2. Add the CLI to your PATH

Append the project bin directory to your shell profile:

# zsh (~/.zshrc)
export PATH="/path/to/codex-quota/bin:$PATH"

Reload your shell, then verify:

codex-quota --help

The first command creates storage under ~/.codex-quota/.

Use cases

Add an account

Register a local account name. This only creates a profile directory; it does not log in.

codex-quota add work_plus
codex-quota add personal_free
codex-quota list

For CLI-only profiles (isolated CODEX_HOME, not for Desktop switching):

codex-quota add lab_cli --cli-isolated

Log in to an account

Run device-auth login and store credentials under that profile only. Desktop is not switched automatically.

codex-quota login work_plus

After login on a Desktop-oriented profile, activate it when you want Desktop to use that account.

Alternative: if you already logged into the target account in Codex Desktop, capture the live credential without logging out:

codex-quota import-active work_plus --create

Check accounts' status

Show auth state, plan, subscription expiry, quota windows, and warnings for every registered account:

codex-quota status

Example output (illustrative values):

Codex Account Quota
Local time: 2026-06-16 21:42 CST

ACCOUNT       EMAIL                 ACTIVE  MODE                AUTH  ACCESS  REFRESH  PLAN  SUB EXPIRES  5H LEFT  5H RESET     WEEKLY LEFT  WEEKLY RESET  AVAIL RESET  WARN
work_plus     user.work@example.com yes     desktop_preserving  yes   yes     yes      plus  2026-06-22   86%      06-17 02:08  23%          06-18 11:05   1            desktop-running
personal_free personal@example.com  no      desktop_preserving  yes   yes     yes      free  2026-07-03   99%      06-17 02:42  34%          06-18 14:33   1            
team_shared   team@example.com      no      desktop_preserving  yes   yes     yes      plus  2026-07-08   45%      06-17 05:15  12%          06-21 11:42   0            

Example columns:

Column	Meaning
5H LEFT / 5H RESET	Short-window quota remaining and reset time
WEEKLY LEFT / WEEKLY RESET	Weekly quota remaining and reset time
AVAIL RESET	Available rate-limit reset credits (matches Desktop “可用重置”)
WARN	Comma-separated compact warning labels (see below)

Quota is fetched from the Codex usage API when credentials allow. Missing values appear as - rather than guessed numbers.

WARN labels

When several issues apply to one account, labels are joined with commas (for example no-auth,quota-stub).

Label	Meaning	What to do
no-auth	Profile has no auth.json, or it has no usable access token.	Run codex-quota login <account> or import-active <account>.
corrupt-auth	auth.json exists but is not valid JSON.	Restore from backup or log in again.
active-drift	active.json says this account is active, but live ~/.codex/auth.json no longer matches the profile. ACTIVE shows ?.	Run import-active <account> if Desktop is on that account, or activate <account> to switch intentionally.
desktop-running	Codex Desktop is running. Added to every row while the app process is detected.	Quit Desktop before activate; reopen afterward so credentials apply.
jq-unavailable	jq is not installed. Token fields may show ?; quota cannot be parsed.	Install jq and rerun status.
curl-unavailable	curl is not installed. The usage API cannot be called.	Install curl and rerun status.
quota-unavailable	Quota lookup failed: missing OAuth fields, network/proxy error, or usage API error after refresh.	Check network/proxy, log in again, then run import-active <account>.
quota-partial	Plan or subscription expiry was read from the ID token, but usage quota is unavailable (often expired credentials).	Log in again and run import-active <account>.
quota-stub	No profile auth.json to query; quota columns stay at -.	Log in or import credentials for that account.

After the table, status may also print summary lines when every account lacks quota data, or when some accounts hit quota-partial.

Activate an account for Codex Desktop

Switch Desktop to a stored profile. A timestamped backup of the current ~/.codex/auth.json is created first.

# 1. Quit Codex Desktop
codex-quota activate work_plus

# 2. Reopen Codex Desktop and confirm the expected account

If Desktop was still running:

codex-quota activate work_plus --force

Logout and delete auth

Remove stored credentials for one account:

# Run codex logout in the account profile and remove its auth.json
codex-quota logout work_plus

# Or delete stored auth.json only (no codex logout call)
codex-quota delete-auth work_plus

Remove the account registry entry and profile directory entirely:

codex-quota remove work_plus

Note

logout and delete-auth do not change ~/.codex/auth.json unless it still matches the profile copy. Desktop keeps using whatever is currently in ~/.codex/auth.json.

Typical workflows

First account from Desktop (already signed in):

codex-quota import-active main --create
codex-quota status

Add a second account and switch Desktop to it:

codex-quota add backup
codex-quota login backup
# quit Codex Desktop
codex-quota activate backup
# reopen Codex Desktop
codex-quota status

Run Codex CLI as a specific profile without touching Desktop:

codex-quota use lab_cli -- codex --help

Storage layout

~/.codex-quota/
  accounts/<account>/auth.json    stored profile credentials
  accounts/<account>/profile.json account metadata (mode, email, …)
  active.json                     last imported/activated profile
  backups/                        auth.json backups before activate

~/.codex/auth.json                live Desktop / default CLI credential

Configuration

Variable	Default	Description
CQ_HTTP_PROXY	http://127.0.0.1:7897	HTTP proxy for quota and token refresh. Set to 0, off, or false to disable.
CQ_QUOTA_USAGE_URL	ChatGPT wham usage API	Override the usage endpoint.

Command reference

codex-quota add <account> [--cli-isolated]
codex-quota import-active <account> [--create]
codex-quota login <account>
codex-quota activate <account> [--force]
codex-quota logout <account>
codex-quota delete-auth <account>
codex-quota remove <account>
codex-quota list
codex-quota status
codex-quota use <account> -- <command...>

Run codex-quota --help for full option text.

Security

• Access tokens, refresh tokens, and ID tokens are never printed.
• Each account keeps its own credential files; profiles are not merged into one shared token store.
• Activation always backs up the previous live auth.json before replacing it.