Codex Limits

Install a Codex skill that checks Codex reset credits, rate-limit windows, local usage metadata, and read-only online usage/profile data.

npx codexlimits

Restart Codex, then ask:

Use $codex-usage to check my Codex usage.

Commands

npx codexlimits              # install or update the Codex skill
npx codexlimits doctor       # verify the installed skill and Python runtime
npx codexlimits reset        # remove the installed skill
npx codexlimits run resets   # run the bundled reporter directly

For non-standard Codex homes:

npx codexlimits --codex-home /path/to/.codex

What Gets Installed

codexlimits writes a self-contained skill to:

~/.codex/skills/codex-usage/
  SKILL.md
  bin/codex_usage.py
  scripts/run-codex-usage.ps1
  scripts/run-codex-usage.sh

The installed skill bundles the Python reporter, so users do not need to clone this repository manually. The wrappers enable UTF-8 output and run the reporter on Windows, macOS, or Linux.

Requirements

• Node.js 18 or newer for the installer.
• Python 3.10 or newer for the reporter.
• A Codex login at ~/.codex/auth.json for online reset and rate-limit checks.
• Local Codex state under ~/.codex for local usage summaries.

No OpenAI API key or third-party Python package is required.

Privacy

Codex Limits reuses the existing Codex login file at ~/.codex/auth.json. It does not ask for or store an OpenAI API key.

Online checks use read-only GET requests to undocumented ChatGPT/Codex backend endpoints. Sensitive fields such as tokens, account IDs, emails, cookies, secrets, and session values are redacted before display or export.

Local usage mode reads metadata and counters from ~/.codex; it avoids prompt text, assistant text, command text, diffs, transcripts, and secret contents.

Notes

This is not an official OpenAI or Codex tool. It does not redeem credits, buy credits, change account settings, upload local transcripts, or change your Codex configuration.

The backend endpoints are undocumented and may change. Treat the report as operational information, not a contractual billing statement.

Development

Run local checks:

python -m py_compile internal/reporter/codex_usage.py
node internal/cli/codexlimits.mjs doctor
npm pack --dry-run

Test an install without touching your real Codex home:

node internal/cli/codexlimits.mjs --codex-home ./tmp-codex-home
node internal/cli/codexlimits.mjs doctor --codex-home ./tmp-codex-home
node internal/cli/codexlimits.mjs reset --codex-home ./tmp-codex-home

License

MIT. See LICENSE.