82 lines
6.1 KiB
Markdown
82 lines
6.1 KiB
Markdown
---
|
|
status: resolved
|
|
parent: "[[057-pi-ui-customization-map]]"
|
|
blocked-by: []
|
|
resolved-at: "2026-07-31T23:58:11-04:00"
|
|
tags:
|
|
- ticket/research
|
|
---
|
|
|
|
# ChatGPT Codex quota research
|
|
|
|
## Question
|
|
|
|
Is there a reliable first-party API, local account state, or documented observable signal that can report remaining weekly ChatGPT Codex quota for the current account, and what authentication or privacy constraints would a Pi status integration need to respect?
|
|
|
|
## Findings
|
|
|
|
Pi supports ChatGPT Plus or Pro subscription authentication for OpenAI Codex through `/login`.
|
|
The providers docs list “ChatGPT Plus/Pro (Codex)” under subscription providers and state that OpenAI Codex requires a ChatGPT Plus or Pro subscription.
|
|
The OpenAI Codex provider implementation uses `https://chatgpt.com/backend-api` as its base URL and OAuth through `auth.openai.com`.
|
|
Sources: `docs/providers.md`; `node_modules/@earendil-works/pi-ai/dist/providers/openai-codex.js`; `node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js`.
|
|
|
|
Pi stores OAuth credentials in `~/.pi/agent/auth.json` and refreshes expired tokens automatically.
|
|
The providers docs describe auth storage for subscription providers, and the OpenAI Codex OAuth implementation returns an access token, refresh token, expiration time, and ChatGPT account id extracted from the access-token JWT.
|
|
Requests include `Authorization: Bearer <token>` and `chatgpt-account-id` headers.
|
|
Sources: `docs/providers.md`; `node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js`; `node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js`.
|
|
|
|
The installed Pi/OpenAI Codex integration does not expose a proactive “remaining weekly quota” API.
|
|
Searching the installed Pi and `@earendil-works/pi-ai` code found no quota, balance, or remaining-usage endpoint for OpenAI Codex.
|
|
The OpenAI Codex provider code has streaming request handling and OAuth, but no first-party quota read operation.
|
|
Sources: `node_modules/@earendil-works/pi-ai/dist/providers/openai-codex.js`; `node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js`; `node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js`.
|
|
|
|
Pi can detect some limit information only when the provider returns an error.
|
|
The OpenAI Codex response code treats error codes such as `usage_limit_reached`, `usage_not_included`, and `rate_limit_exceeded`, or HTTP 429, as usage-limit conditions.
|
|
If the error body includes `plan_type`, it includes that in a friendly message.
|
|
If the error body includes `resets_at`, it computes an approximate minutes-until-reset message.
|
|
This is useful for displaying “you are out” and reset time after a failing request, but it is not a reliable way to display remaining quota before the limit is hit.
|
|
Sources: `node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js` error handling.
|
|
|
|
Pi extensions can observe provider response status and normalized headers through `after_provider_response`, but header availability depends on provider and transport.
|
|
The docs show using this hook to inspect HTTP 429 and `retry-after`.
|
|
The OpenAI Codex transport uses both SSE and WebSocket paths, so relying on response headers for a stable weekly quota display would need live verification and may not work for all Codex requests.
|
|
Sources: `docs/extensions.md` section `after_provider_response`; `node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js`.
|
|
|
|
Authentication and privacy constraints are significant.
|
|
A quota integration that calls ChatGPT backend APIs directly would need access to the user's OAuth access token and ChatGPT account id.
|
|
Those are credentials and account identifiers.
|
|
Any status integration must avoid logging them, avoid exposing them through status rows or transcript entries, and should only call endpoints that are documented or already used by Pi's provider stack.
|
|
Sources: `docs/providers.md` auth storage description; `node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js`; `node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js` request headers.
|
|
|
|
## Answer
|
|
|
|
This research established only a narrower fact: Pi's installed OpenAI Codex provider and Pi's docs do not expose a documented proactive quota API.
|
|
That is not enough to conclude that no reliable quota source exists.
|
|
The user reported third-party applications that show this information, possibly including baby-menu, so the broader question remains open and is tracked in [[064-pi-ui-third-party-codex-quota-research]].
|
|
|
|
The reactive signal remains useful: a provider error can report that a usage limit was hit, and may include plan type and reset time.
|
|
A safe fallback can show:
|
|
|
|
- last known Codex limit error, if one occurs
|
|
- reset estimate from `resets_at`, when present
|
|
- `retry-after` from response headers, when present
|
|
- “quota unknown” otherwise
|
|
|
|
Do not rule out a proactive quota display until the third-party mechanism has been researched.
|
|
|
|
## Limitations
|
|
|
|
This research did not call ChatGPT backend APIs with the user's credentials.
|
|
That was intentional because probing undocumented authenticated endpoints has privacy and stability risks.
|
|
|
|
OpenAI may expose quota information in web UI internals or undocumented backend endpoints, but no first-party documented source was established here.
|
|
Treat that as an evidence gap rather than an implementation basis.
|
|
|
|
## Citations
|
|
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/providers.md`, “Subscriptions” and “OpenAI Codex”.
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`, section `after_provider_response`.
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-ai/dist/providers/openai-codex.js`.
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js`.
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js`.
|