Codex

Codex Provider

The Codex provider tracks usage limits for Codex / OpenAI via the official Codex CLI authentication.

Supported Plans

All OpenAI plans accessible through Codex CLI (Plus, Pro, Team, etc.) are supported.

Authentication

Codex uses OAuth tokens from the official codex CLI. You have two options:

Option 1: Codex CLI (Recommended)

opentracker login codex

This runs codex login interactively. After authentication completes:

opentracker fetch codex

Option 2: Environment Variables

If you already have a Codex access token:

export OPENTRACKER_CODEX_ACCESS_TOKEN="your-access-token"
export OPENTRACKER_CODEX_ACCOUNT_ID="your-account-id"  # optional
opentracker fetch codex

Token Storage

When using codex login, tokens are stored by the Codex CLI at:

~/.codex/auth.json

OpenTracker reads this file automatically. The CODEX_HOME environment variable is respected if set.

Usage

Fetch Usage Data

# Fetch current usage (cached for 90 seconds)
opentracker fetch codex

# Force refresh (skip cache)
opentracker fetch codex --force

Example Output

[
  {
    "provider": "codex",
    "usage": {
      "plan": "pro",
      "primary": {
        "usedPercent": 42,
        "remainingPercent": 58,
        "windowSeconds": 18000,
        "resetsAt": "2025-10-09T08:53:20Z"
      },
      "secondary": {
        "usedPercent": 10,
        "remainingPercent": 90,
        "windowSeconds": 604800,
        "resetsAt": "2025-10-15T12:00:00Z"
      },
      "creditsRemaining": 150.0,
      "updatedAt": "2025-10-09T03:53:20Z",
      "source": "codex-oauth"
    }
  }
]

Output Fields

Field	Type	Description
plan	string	OpenAI plan type (e.g., plus, pro, team)
primary	object	Short-term rate limit window (typically 5 hours)
secondary	object	Long-term rate limit window (typically 7 days)
creditsRemaining	number	Current credit balance
updatedAt	string	ISO 8601 timestamp of when the data was fetched
source	string	Always "codex-oauth"

Rate Window Object

Field	Type	Description
usedPercent	integer	Percentage of limit used
remainingPercent	integer	Percentage of limit remaining
windowSeconds	integer	Length of the rate limit window in seconds
resetsAt	string	ISO 8601 timestamp when the window resets

Troubleshooting

"Codex auth not configured"

Run codex login first, or set OPENTRACKER_CODEX_ACCESS_TOKEN.

"Codex authentication expired or unauthorized"

Your token has expired. Run opentracker login codex again to refresh.

"no such file or directory: codex"

The codex CLI is not installed or not in your PATH. Install it first:

npm install -g @openai/codex