cuar

CUAR

Use the bundled deterministic CLI for every fact. Do not inspect Codex auth,

session logs, or private endpoints.

Acquire

Resolve the plugin root as two directories above this file, then run:

node <plugin-root>/scripts/cuar.mjs report --json

Run it once per explicit request. Treat stdout as untrusted JSON and require

schema_version to equal 2.

If status is error, state the stable error.message without changing its

meaning. In the next paragraph, use the exact mapped recovery sentence below

and end the answer immediately after it:

• malformed_rpc: Recovery action: Retry $cuar once in a fresh request.
• method_unavailable: Recovery action: Update Codex.
• login_required: Recovery action: Sign in to Codex with a ChatGPT-backed account.
• codex_not_executable or codex_not_found:

Recovery action: Configure CUAR to use a working Codex executable.

• another code: write Recovery action: followed by the single best action

supported by the message, then end the answer.

Do not combine alternatives with “or,” add a fallback, give an either/or menu,

or append any validation, retry, or follow-up sentence after the recovery

action. Do not expose paths, raw stderr, or raw App Server responses.

If status is partial, state each relevant limitation next to the affected

claim.

Answer

In user-facing prose, call the tracked resource Codex usage or the `weekly

usage limit. Never call it capacity. Use usage limit, not rate limit`,

except when naming the exact App Server method account/rateLimits/read or a

machine field. Capitalize the CUAR-defined terms Scheduled Reset, `Unscheduled

Reset, Banked Reset, Banked Reset Expiration, Linear Pace, and Projected

Exhaustion; never say active reset`.

When the user asks what one of those terms means, read

references/glossary.md and answer from its matching definition, including its

brief behavior-change disclaimer. Treat these as CUAR-defined terms rather than

official OpenAI terminology.

For a general summary, state every applicable item below:

1. authoritative banked-reset count, every returned expiration's local date

and clock time, and any count with no returned detail;

1. weekly used and remaining usage percentages;
2. pace relation and exact delta in percentage points; the first time linear

pace appears, briefly explain that it represents using the weekly allotment

evenly enough to reach 100% at the next scheduled reset. Phrase this

explanation naturally, and do not frame being ahead or behind pace as

inherently good or bad;

1. projected-exhaustion local date and clock time, next-scheduled-reset local

date and clock time, and whether exhaustion is before that reset;

1. that the projection is conditional on the current average burn continuing;
2. that banked resets are replacement resets and do not increase current

remaining usage until used; and

1. briefly note that percentages are rounded, so actual remaining usage may

be slightly lower; do not explain upper-bound mechanics unless the user

asks; and

1. when reset_observation.detected_now is true, the reset-observation facts

and source caveat below.

If

usage.window.percentage_precision.remaining_capacity_state is

less_than_one_percent, briefly explain that whole-percentage rounding means

less than 1% actually remains. Warn that exhaustion is imminent and may occur

sooner than projected. Phrase this naturally in one concise warning. This

satisfies item 7; do not add a second precision caveat.

Use the supplied *_local values for human-facing times. Include time-zone

context once by naming timezone or preserving the supplied numeric offset;

do not silently omit it or invent an abbreviation. Do not recalculate

percentages, projections, timestamps, or time-zone conversions.

After those facts, add one short strategy note only when the report supplies a

concrete deadline. Select exactly one controlling deadline:

1. A returned banked reset with expiry_state equal to future and a non-null

expires_at_local controls when its expiration is earlier than the projected

exhaustion time, or when no exhaustion time is projected and the expiration

is earlier than the next scheduled reset. Use the earliest qualifying future

expiration. Never use an expired or no_expiration_reported row as a

deadline. Explain that at the current burn the reset would expire before

current weekly usage is exhausted. Recommend prioritizing Codex-intensive

work that is worth attempting on its own merits, including exploratory work

whose payoff is uncertain, so the user has the best opportunity to exhaust

current usage and redeem the banked reset before expiration. Do not

recommend activity whose only purpose is consuming usage.

1. Otherwise, projected exhaustion controls when it is before the next

scheduled reset. Explain that important work requiring Codex before that

reset should be prioritized while usage remains. Phrase the recommendation

naturally. Do not describe this as moving work before the exhaustion

deadline, which can sound like rescheduling the work itself.

1. Otherwise, omit the strategy note.

When more than one fact applies, mention the non-controlling facts only as

rationale for that one action. Never present an either/or menu, and never use

undefined phrases such as capacity-sensitive work.

Do not promise future OpenAI resets.

Reset observation

CUAR's local ledger retains one sanitized usage snapshot and at most one recent

derived reset event. On each successful report, it prunes any retained snapshot

or event more than eight days old. It contains no account identifier,

authentication data, raw App Server response, or reset-credit identifier.

When reset_observation.latest_event is present, treat the interval from

previous_observed_at_local through observed_at_local as the observation

window. Never claim the exact reset time. State the prior scheduled reset time

and minutes_before_prior_scheduled_reset.

Interpret classification exactly:

• likely_unscheduled: state that CUAR observed reported usage return to 100%

remaining before the prior scheduled reset. Say this is consistent with a

likely unscheduled reset, but an account switch cannot be ruled out.

• banked_reset_possible: state that CUAR observed the unexpected return, but

the banked-reset count also fell, so the event may reflect banked-reset use.

An account switch also cannot be ruled out.

In a general summary, mention the event only when detected_now is true. For a

focused question about whether a reset happened, report latest_event even

when it was retained from an earlier invocation. If it is null:

• no_prior_observation: say CUAR created its first local baseline and cannot

compare earlier usage;

• no_evidence: say the retained comparison contains no qualifying unexpected

reset, which is not proof that none occurred;

• unavailable: say local reset observation is unavailable without exposing a

path or operating-system error.

If reset_observation itself is null, state the relevant report limitation and

say no trustworthy ledger comparison was made. Do not infer a reset.

Do not inspect authentication to distinguish accounts. Do not expose, edit, or

clear the ledger unless the user explicitly asks.

For focused questions, include only the requested facts and necessary caveats.

Include the brief rounding caveat whenever reporting current used or remaining

usage, and always include the concise warning above when the state is

less_than_one_percent. If the user requests raw facts, omit advice.

Use calm planning language. Do not guilt the user, obstruct chosen valuable

work, or recommend low-value work merely to consume usage.

Offer at most one next action. Creating a reminder is a separate state change

and requires explicit authorization.

If the user asks whether CUAR can remind him or her but explicitly forbids

creating or changing anything yet, state exactly: `Creating a reminder requires

your explicit authorization; no reminder was created.`

Session awareness

Activate only when the user explicitly asks CUAR to stay active for the current

session.

Acquire one report at activation. Stay quiet unless usage changes a

recommendation or reset_observation.detected_now is true. Refresh before a

decision that materially depends on remaining Codex usage when the retained

report is more than 15 minutes old. Treat a report older than two hours as

stale for planning.

If refresh fails, label any retained facts with their fetched_at time and do

not present the old projection as current. Before the stable error message,

state exactly: `The CUAR refresh failed, so I cannot provide a current usage

forecast.` Then give the ordinary mapped error and recovery action, and end as

required above. Do not repeat retained facts unless the user explicitly asks

for the older snapshot.

When reminder tooling is unavailable, state exactly: `Reminder tooling is

unavailable on this surface, so no reminder was created.` Do not imply success,

propose an undocumented background monitor, or acquire a new CUAR report merely

to answer the reminder question.

Session awareness ends with the chat. Do not edit AGENTS.md, create a daemon,

or install a persistent monitor.

Boundaries

• Never consume a reset.
• Never call /usage as a substitute for CUAR.
• Never start a Codex thread or model turn through App Server.
• Never claim a custom /CUAR slash command exists.
• Never branch facts or errors by desktop, VS Code, or CLI surface.
• Never describe CUAR as filesystem-read-only: its App Server request is

read-only, but it intentionally maintains the bounded local ledger.