Skip to content

Codex should expose agent-accessible quota/status and support automatic graceful stop policies #24927

@DeathPhoenix22

Description

@DeathPhoenix22

What variant of Codex are you using?

Codex within IntelliJ

What feature would you like to see?

Product area:
Codex / Codex IDE integration / JetBrains IntelliJ plugin / AGENTS.md behavior / quota handling

Problem:
Codex can mutate a local repository while operating under usage limits. When a user has low remaining quota, for example 5%, Codex may still begin a multi-step task, inspect files, apply edits, and then exhaust quota before validation or cleanup. This can leave the user with a partial, unvalidated, or broken diff.

This makes the final portion of quota practically unsafe to use. Users are incentivized to stop using Codex before reaching zero because the last quota slice may create codebase risk and force them to spend future quota repairing or reverting partial work.

Current limitation:
The user can manually check quota/status through available UI or slash-command surfaces where supported, but Codex does not appear to have a reliable agent-accessible status API that it can call from an IntelliJ AI Chat task or from AGENTS.md-governed workflows.

Requested feature:
Expose an internal, free, agent-accessible quota/status capability that Codex can query during task execution.

This could be something like:

  • an internal tool: get_usage_status()
  • a machine-readable status object
  • an agent-callable equivalent of /status
  • a read-only local command/API exposed by the Codex plugin/runtime

This status check should not consume user quota because it is internal account/session metadata, not model reasoning.

Minimum useful fields:

  • remainingQuotaPercent
  • quotaWindowResetTime
  • currentUsageBucket
  • isNearLimit
  • canSafelyContinue
  • recommendedMode: NORMAL, LOW_QUOTA, HANDOFF_ONLY, PATCH_ONLY, READ_ONLY
  • optional estimatedBudgetClass for the current request, if available

Desired behavior:
Codex should be able to use AGENTS.md policies such as:

"If quota is below 10%, do not mutate files. Switch to patch-only or handoff mode."

"If quota is below 5%, stop broad exploration and produce a recovery summary."

"If the task cannot likely be completed and validated before quota exhaustion, stop before editing."

Suggested AGENTS.md policy support:
Allow users to write project-local safety policies like:

Quota Safety Policy

At the start of every task and before mutating files, check the Codex quota/status API if available.

If remaining quota is low:

  • do not perform broad repository exploration;
  • do not start multi-file refactors;
  • prefer read-only planning;
  • prefer patch-only output;
  • stop before editing when validation cannot be completed safely;
  • produce a handoff with inspected files, intended edits, validation command, rollback command, and exact resume prompt.

If quota is exhausted or near exhaustion:

  • do not continue editing;
  • produce a recovery handoff instead of leaving the user with an unexplained partial state.

Ideal UI setting:
Add an official Codex setting in IDE plugins and Codex app/CLI:

"Low quota safety mode"

Options:

  • Off
  • Warn only
  • Planning only below X%
  • Patch-only below X%
  • No file mutation below X%
  • Require confirmation before editing below X%
  • Always produce handoff before stopping

Why this matters:
Codex is not only a chat assistant; it is an agent that can modify a developer's repository. Quota exhaustion should not behave like abruptly unplugging the tool mid-edit. It should behave like a controlled stop boundary.

Business/user value:
This would make quota consumption more efficient and trustworthy. Users could safely use more of their quota instead of avoiding the final 5–10% to protect their repo. It would reduce repair/revert loops, reduce frustration, and make AGENTS.md policies much more powerful.

Expected result:
When Codex detects low quota, it should either:

  1. continue safely if enough quota remains;
  2. switch to patch-only/read-only mode;
  3. or stop before mutation with a clear handoff:

"I am near my usage limit. I should not start this edit because I may not be able to finish and validate safely. Here is the next exact prompt to resume when quota resets."

Impact:
This would directly address partial-work risk, improve user trust, and make Codex quota handling significantly more predictable in professional development workflows.

Additional information

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestrate-limitsIssues related to rate limits, quotas, and token usage reporting

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions