pi-codex-status

ChatGPT Codex quota/status checker for pi. Adds a /status command and a standalone pi-codex-status CLI so you can see Codex 5-hour limits, weekly limits, credits, and reset times before you hit a rate-limit error.

Why

This replicates Codex' /status info that you otherwise can't see by default in pi. It also provides the data so you can put it in your statusline or anywhere else you want to use it:

• In pi — /status renders a boxed, themed quota summary and updates a compact footer status.
• In scripts — pi-codex-status statusline prints a one-line summary suitable for prompts or status bars.
• For automation — pi-codex-status json returns normalized JSON for custom tooling.

Features

• Shows the main Codex 5-hour and weekly windows
• Shows credits balance and reset times in local time
• Shows additional named/per-model limits when the backend reports them
• Reads existing pi or Codex CLI OAuth credentials; no separate login flow
• Self-caches status data for fast statusline calls
• Opportunistically refreshes the cache from x-codex-* provider response headers

Requirements

• Node.js 20.6 or newer
• pi with the openai-codex provider, or Codex CLI, already authenticated
• A ChatGPT plan/account that can use Codex models

In pi, run /login, choose the ChatGPT Plus/Pro / OpenAI Codex login, then select an openai-codex model. See pi's provider docs: OpenAI Codex.

Install

Install as a pi extension:

pi install npm:pi-codex-status

Or install directly from GitHub:

pi install https://github.com/lhl/pi-codex-status

Install the standalone CLI globally:

npm install -g pi-codex-status

Quick Start

/status              # boxed quota summary in pi
/status statusline   # compact one-line output in pi
/codex-status        # alias if another extension claims /status

pi-codex-status statusline
pi-codex-status json | jq '.defaultLimit.primary.leftPercent'

Example boxed output:

╭────────────────────────────────────────────────────────────────────────────────────────╮
│ >_ Codex usage                                                                         │
│                                                                                        │
│ Visit https://chatgpt.com/codex/settings/usage for up-to-date                          │
│ information on rate limits and credits                                                 │
│                                                                                        │
│ Account:                    user@example.com (Pro)                                     │
│ Updated:                    5/6/2026, 12:34:56 PM                                      │
│                                                                                        │
│ 5h limit:                   [███████████████████░] 95% left (resets 18:43)             │
│ Weekly limit:               [███████████████████░] 97% left (resets 19:18 on 12 May)   │
│ Credits:                    553 credits                                                │
│                                                                                        │
│ GPT-5.3-Codex-Spark limit:                                                             │
│   5h limit:                 [████████████████████] 100% left (resets 20:26)            │
│   Weekly limit:             [██████████████████░░] 88% left (resets 17:27 on 9 May)    │
╰────────────────────────────────────────────────────────────────────────────────────────╯

Example statusline:

Codex 5h:95% left 7d:97% left pro reset:18:43 credits:553

Pi Commands

/status              # boxed quota summary
/status refresh      # bypass the local cache
/status json         # normalized JSON
/status raw          # raw backend usage response
/status statusline   # compact one-line output
/codex-status        # alias if another extension claims /status

In interactive pi, /status renders as a themed custom message instead of a plain markdown code block. The extension also sets a compact footer status and refreshes the local cache from Codex rate-limit headers when provider responses include them.

CLI

pi-codex-status
pi-codex-status status
pi-codex-status statusline
pi-codex-status json
pi-codex-status raw

Options:

--auth-source auto|pi|codex
--auth-file PATH
--endpoint URL
--cache-file PATH
--max-age SECONDS
--no-cache
--timeout SECONDS
--no-box

statusline is self-cached through ~/.cache/pi-codex-status/usage.json so it is safe to call frequently from prompts and status bars.

How It Works

Primary status data comes from ChatGPT's private Codex usage endpoint:

https://chatgpt.com/backend-api/codex/usage

The endpoint returns server-reported used_percent, reset_at, limit_window_seconds, plan, credits, and additional named limits. pi-codex-status normalizes that into display fields:

• leftPercent = 100 - used_percent
• Reset timestamps are converted from Unix seconds to local time
• Window durations are preserved as seconds
• Credit balance is displayed as whole credits in the status box/statusline
• Additional limits are rendered from additional_rate_limits[]

The pi extension also listens to provider responses and opportunistically parses x-codex-primary-used-percent, x-codex-secondary-used-percent, and related x-codex-* headers to refresh the local cache without an extra endpoint call. A codex.rate_limits event parser is included for compatibility with Codex's websocket shape.

The endpoint is private and may change. The official fallback is ChatGPT Codex usage settings.

Auth and Cache

Auth lookup order:

1. ~/.pi/agent/auth.json (openai-codex OAuth entry)
2. ~/.codex/auth.json (Codex CLI OAuth entry)

Access tokens may be refreshed using the stored refresh token. Tokens are not printed, logged, or stored in the status cache.

Default cache path:

~/.cache/pi-codex-status/usage.json

Development

git clone https://github.com/lhl/pi-codex-status
cd pi-codex-status
npm install
npm run check
npm test
pi install .

Release checklist: docs/PUBLISH.md.

License

MIT