codex auth forecast - Codex Multi-Auth

Analyze all accounts and recommend the best one for your next API session based on health scores, quota availability, rate limits, and risk factors.

Usage

codex auth forecast [--live] [--json] [--model <model>]

--live

boolean

default:"false"

Perform live quota probes for all accounts before scoring.

--json

boolean

default:"false"

Output machine-readable JSON instead of human-friendly text.

--model

string

default:"gpt-5-codex"

Model to use for live quota probes (only with --live).

How It Works

Load accounts - Read all enabled accounts from storage
Score health - Calculate health score (0-100) per account
Check rate limits - Factor in cooldown timers
Probe quota (if --live) - Fetch real-time usage
Evaluate risk - Low/medium/high risk per account
Rank accounts - Sort by readiness and risk
Recommend best - Output top choice with reasoning

Example Output

Default Mode (No Live Probe)

Forecast (4 accounts evaluated)

Recommended account:
  → [email protected] (index 1)
  Reason: Ready, low risk, health 100

All accounts:
  1. [email protected]      Ready     Low risk      Health: 100
  2. [email protected]           Ready     Medium risk   Health: 85
  3. [email protected]     Delayed   Medium risk   Health: 70
  4. [email protected]          Blocked   High risk     Health: 20

Live Mode

Forecast (4 accounts evaluated with live probe)

Recommended account:
  → [email protected] (index 1)
  Reason: Ready, low risk, health 100, quota 5h:95% 7d:87%

All accounts:
  1. [email protected]      Ready     Low risk      5h:95% 7d:87%  Health: 100
  2. [email protected]           Ready     Medium risk   5h:45% 7d:67%  Health: 85
  3. [email protected]     Delayed   Medium risk   5h:12% 7d:34%  Health: 70
  4. [email protected]          Blocked   High risk     rate-limited   Health: 20

JSON Output

codex auth forecast --live --json

{
  "evaluatedAt": 1709337600000,
  "totalAccounts": 4,
  "liveProbe": true,
  "model": "gpt-5-codex",
  "recommendation": {
    "index": 0,
    "accountId": "user-abc123",
    "email": "[email protected]",
    "availability": "ready",
    "riskLevel": "low",
    "healthScore": 100,
    "quota5h": 95,
    "quota7d": 87,
    "reasoning": "Ready, low risk, health 100, quota 5h:95% 7d:87%"
  },
  "accounts": [
    {
      "index": 0,
      "email": "[email protected]",
      "availability": "ready",
      "riskLevel": "low",
      "healthScore": 100,
      "quota5h": 95,
      "quota7d": 87
    },
    {
      "index": 1,
      "email": "[email protected]",
      "availability": "ready",
      "riskLevel": "medium",
      "healthScore": 85,
      "quota5h": 45,
      "quota7d": 67
    }
  ]
}

Availability States

ready

availability

Account is immediately available for use.

delayed

availability

Account is usable but may have delays (low quota, cooldown ending soon).

blocked

availability

Account is unavailable (rate-limited, disabled, or broken).

Risk Levels

low

risk

Healthy account with high quota, no recent failures.

medium

risk

Account with moderate quota or minor issues (expired token but refresh works).

high

risk

Account with low quota, recent failures, or impending issues (broken refresh token).

Scoring Factors

Health Score (0-100)

100 - Never failed, always refreshes successfully
80-99 - Occasional refresh failures (1-2)
50-79 - Multiple failures or warnings
0-49 - Consistent failures, near flagging threshold

Quota Impact (Live Probe Only)

5h window - Short-term burst capacity (weight: 60%)
7d window - Long-term sustained usage (weight: 40%)

Rate Limit Penalties

Active rate limit (429): Availability = blocked
Cooldown < 10 minutes: Availability = delayed
Cooldown > 10 minutes: Availability = blocked

Disabled/Flagged

Disabled accounts: Excluded from forecast
Flagged accounts: Not in main pool (use verify-flagged)

Examples

Quick forecast

codex auth forecast

Live forecast with quota

codex auth forecast --live

Forecast for specific model

codex auth forecast --live --model gpt-5-turbo

Machine-readable forecast

codex auth forecast --json

Extract recommended index

BEST=$(codex auth forecast --json | jq -r '.recommendation.index + 1')
codex auth switch $BEST

Automation: Switch to best account

#!/bin/bash
FORECAST=$(codex auth forecast --live --json)
AVAILABILITY=$(echo $FORECAST | jq -r '.recommendation.availability')

if [ "$AVAILABILITY" = "ready" ]; then
  INDEX=$(echo $FORECAST | jq -r '.recommendation.index + 1')
  codex auth switch $INDEX
  echo "Switched to account $INDEX"
else
  echo "No ready accounts available"
  exit 1
fi

Performance

Default Mode

Speed: ~100-200ms for 10 accounts
Network: No API calls (uses cached data)
Accuracy: Based on last health check

Live Mode

Speed: ~2-3 seconds per account
Network: 1 API request per account
Accuracy: Real-time quota and rate limit status

For 10 accounts with --live: ~30 seconds total.

When to Use Each Mode

Default Mode

Good for:

Fast lookups during active sessions
Pre-request account selection
High-frequency automation

Live Mode

Good for:

Pre-session planning (morning check)
After long idle periods
When quota matters (batch jobs)
Debugging rate limit issues

Exit Codes

exit code

Forecast completed (even if no ready accounts)

exit code

Forecast failed (no accounts, storage error)

Troubleshooting

No Ready Accounts

Recommended account:
  → None (all accounts blocked or delayed)

Check account status:

codex auth check --live
codex auth verify-flagged

Live Probe Times Out

Increase timeout:

CODEX_AUTH_FETCH_TIMEOUT_MS=30000 codex auth forecast --live

Recommendation Doesn’t Match Usage

Clear session affinity:

rm ~/.codex/multi-auth/session-affinity.json
codex auth forecast --live

Stale Quota Data

Force refresh:

rm ~/.codex/multi-auth/quota-cache.json
codex auth forecast --live

codex auth check - Update health scores
codex auth switch - Switch to recommended account
codex auth report - Detailed analysis
codex auth status - Current account state

Integration Examples

Pre-commit hook

#!/bin/bash
# .git/hooks/pre-commit
codex auth forecast --live --json > /tmp/forecast.json
READY=$(jq -r '.recommendation.availability' /tmp/forecast.json)

if [ "$READY" != "ready" ]; then
  echo "Warning: No ready accounts for code review"
fi

CI/CD pipeline

# .github/workflows/test.yml
steps:
  - name: Check account forecast
    run: |
      codex auth forecast --live --json | jq '.recommendation.availability == "ready"'

Monitoring dashboard

# Cron: Every 15 minutes
*/15 * * * * codex auth forecast --live --json > /var/www/html/forecast.json

Commands

Configuration

Dashboard

​Usage

​How It Works

​Example Output

​Default Mode (No Live Probe)

​Live Mode

​JSON Output

​Availability States

​Risk Levels

​Scoring Factors

​Health Score (0-100)

​Quota Impact (Live Probe Only)

​Rate Limit Penalties

​Disabled/Flagged

​Examples

​Quick forecast

​Live forecast with quota

​Forecast for specific model

​Machine-readable forecast

​Extract recommended index

​Automation: Switch to best account

​Performance

​Default Mode

​Live Mode

​When to Use Each Mode

​Default Mode

​Live Mode

​Exit Codes

​Troubleshooting

​No Ready Accounts

​Live Probe Times Out

​Recommendation Doesn’t Match Usage

​Stale Quota Data

​Related Commands

​Integration Examples

​Pre-commit hook

​CI/CD pipeline

​Monitoring dashboard

Build docs developers (and LLMs) love

Usage

How It Works

Example Output

Default Mode (No Live Probe)

Live Mode

JSON Output

Availability States

Risk Levels

Scoring Factors

Health Score (0-100)

Quota Impact (Live Probe Only)

Rate Limit Penalties

Disabled/Flagged

Examples

Quick forecast

Live forecast with quota

Forecast for specific model

Machine-readable forecast

Extract recommended index

Automation: Switch to best account

Performance

Default Mode

Live Mode

When to Use Each Mode

Default Mode

Live Mode

Exit Codes

Troubleshooting

No Ready Accounts

Live Probe Times Out

Recommendation Doesn’t Match Usage

Stale Quota Data

Related Commands

Integration Examples

Pre-commit hook

CI/CD pipeline

Monitoring dashboard