Upstream proposal: stable machine-readable quota snapshot
Target: ndycode/codex-multi-auth
Context
Standalone quota UIs were intentionally kept outside the main repository in PRs #603 and #605. That boundary makes sense, but an external integration currently has no stable sanitized quota contract: status --json exposes account state without quota windows, while the useful percentages and reset timestamps remain in the internal cache or human-oriented check output.
Proposed surface
Preferred command name:
codex-multi-auth limits --json
codex-multi-auth limits --refresh --json
Alternative if the maintainer prefers a smaller command surface: add a quota object to each account in status --json and define an explicit refresh flag.
Cached output should perform no remote calls. --refresh should use the project's existing quota-probe/cache machinery, then return the same shape. The command should join configured accounts to cache entries internally so consumers never need to parse account storage or rely on cache keys/order.
Suggested fields per account:
{
"index": 0,
"label": "display-safe account label",
"enabled": true,
"current": true,
"quota": {
"updatedAt": 1790000000000,
"status": 200,
"planType": "plus",
"primary": {
"usedPercent": 12.5,
"windowMinutes": 300,
"resetAtMs": 1790003600000
},
"secondary": {
"usedPercent": 63,
"windowMinutes": 10080,
"resetAtMs": 1790604800000
},
"resetCreditsAvailable": 47
}
}The exact naming is open to maintainer preference. Consumers need numeric timestamps/percentages and window durations, not formatted countdown text. Missing provider fields should be null or omitted consistently and must not fail the full snapshot.
Reset-credit extension
The current response-header probe and QuotaCacheEntry do not expose banked reset credits. Current Codex clients obtain an available reset-credit count as part of their read-only usage response. If using that transport is acceptable for this project, the same refresh request could persist an optional resetCreditsAvailable value without adding another request. This endpoint/field is not a documented public OpenAI API, so transport stability and fallback behavior should be stated clearly.
Safety and compatibility
- Read-only; no account switching or reset redemption.
- No access or refresh tokens in output.
- Cached mode performs zero network requests.
- Live refresh retains existing sequential/bounded probe behavior.
- Existing commands and cache readers remain compatible through additive fields or a cache migration.
- Contract and redaction tests cover machine output.
Maintainer question
Would you prefer a dedicated limits --json command or additive quota fields in status --json? If this direction fits scope, we can submit focused tests and implementation in the repository's existing command/cache layers.
Upstream proposal: stable machine-readable quota snapshot
Target:
ndycode/codex-multi-authContext
Standalone quota UIs were intentionally kept outside the main repository in PRs #603 and #605. That boundary makes sense, but an external integration currently has no stable sanitized quota contract:
status --jsonexposes account state without quota windows, while the useful percentages and reset timestamps remain in the internal cache or human-orientedcheckoutput.Proposed surface
Preferred command name:
Alternative if the maintainer prefers a smaller command surface: add a
quotaobject to each account instatus --jsonand define an explicit refresh flag.Cached output should perform no remote calls.
--refreshshould use the project's existing quota-probe/cache machinery, then return the same shape. The command should join configured accounts to cache entries internally so consumers never need to parse account storage or rely on cache keys/order.Suggested fields per account:
{ "index": 0, "label": "display-safe account label", "enabled": true, "current": true, "quota": { "updatedAt": 1790000000000, "status": 200, "planType": "plus", "primary": { "usedPercent": 12.5, "windowMinutes": 300, "resetAtMs": 1790003600000 }, "secondary": { "usedPercent": 63, "windowMinutes": 10080, "resetAtMs": 1790604800000 }, "resetCreditsAvailable": 47 } }The exact naming is open to maintainer preference. Consumers need numeric timestamps/percentages and window durations, not formatted countdown text. Missing provider fields should be
nullor omitted consistently and must not fail the full snapshot.Reset-credit extension
The current response-header probe and
QuotaCacheEntrydo not expose banked reset credits. Current Codex clients obtain an available reset-credit count as part of their read-only usage response. If using that transport is acceptable for this project, the same refresh request could persist an optionalresetCreditsAvailablevalue without adding another request. This endpoint/field is not a documented public OpenAI API, so transport stability and fallback behavior should be stated clearly.Safety and compatibility
Maintainer question
Would you prefer a dedicated
limits --jsoncommand or additive quota fields instatus --json? If this direction fits scope, we can submit focused tests and implementation in the repository's existing command/cache layers.