codex-budget-mode

name

codex-budget-mode

description

Control Codex usage across a coding, research, or repository task with Saver, Balanced, Full Power, or custom soft budgets; reduce unnecessary context, searches, tool calls, retries, and delegation while preserving the verification needed for a trustworthy result; and write a resumable native Markdown usage report. Use when the user wants to conserve Codex limits, avoid waste, set a task budget, or understand what work was skipped. Do not use for prompt-only token estimates or rewrites.

Codex Budget Mode

Complete the user's real task while acting as a usage-aware execution controller. Choose the smallest workflow that can produce a trustworthy outcome, make expensive choices visible, and leave a resumable checkpoint if the task should stop before completion.

This is a soft budget, not a server-side quota. It cannot guarantee an exact token count, billing amount, or percentage of an account limit unless the host exposes reliable measurements. Never invent precision.

Non-negotiable rules

• Preserve the user's requested outcome, authorization boundaries, and acceptance criteria.
• Do not trade away correctness, security, data integrity, or essential verification to claim savings.
• Do not claim exact task consumption from an account-level usage delta. Other tasks, rounding, caching, and delayed reporting may affect it.
• Do not repeatedly poll usage. When a read-only usage tool is available, capture at most one start snapshot and one end snapshot unless the user explicitly requests monitoring.
• Never describe estimated savings as measured savings.
• Do not broaden the work because budget remains. FULL_POWER means thorough within scope, not unlimited exploration.
• Do not use subagents in SAVER. In other modes, use them only when the user explicitly requests delegation or another active workflow requires them.
• When the requested budget cannot support a safe result, narrow the target or stop with a checkpoint instead of pretending the task is complete.

Language and user experience

• Match the user's language for chat and the report unless they request another language.
• Keep progress updates short. Report only budget decisions that change scope, confidence, or the next step.
• Do not ask the user to configure every detail. Infer the mode and proceed when the request is clear.
• Ask at most one budget question only when a custom ceiling materially changes what can be delivered.
• Before substantive work, show a one-line contract:

Budget: SAVER | Scope: authentication regression | Measurement: unavailable | Strategy: focused inspection + one targeted verification

Load the operating references

• Read references/modes.md before selecting or applying a mode.
• Read references/report-schema.md before creating the final report or a resume checkpoint.

1. Select the budget contract

Honor an explicitly requested mode or custom budget. Otherwise infer:

• SAVER when the user asks to minimize usage, conserve limits, be cheap, be quick, or avoid unnecessary work.
• BALANCED when the user invokes the skill without a mode.
• FULL_POWER only when the user explicitly prioritizes maximum coverage or depth.
• CUSTOM when the user supplies measurable restrictions such as no web, no subagents, one test command, a maximum number of phases, or a target account percentage.

Record the objective, scope, restrictions, verification floor, expensive actions, stop condition, and checkpoint location. Treat a requested account percentage as a target, not a hard guarantee. If no reliable usage measurement exists, translate it into an explicit operational contract and disclose the substitution.

2. Establish the baseline cheaply

Use existing conversation context before reopening files or repeating commands. Inspect only enough evidence to locate the relevant surface:

• prefer targeted filename and text search over directory-wide file dumps;
• read narrow line ranges before entire large files;
• summarize large logs, diffs, datasets, or tool output instead of replaying them;
• reuse existing test results when they are current and trustworthy;
• avoid web research unless the task requires current or external facts;
• avoid loading optional references and unrelated project documentation.

If the host exposes a read-only account usage tool, capture the available windows and reset times. Label the snapshot ACCOUNT_LEVEL. Absence of the tool is normal and must not block the task.

3. Build a cost-aware execution plan

Separate the work into:

1. ESSENTIAL — required to satisfy the request safely.
2. CONDITIONAL — run only if evidence from the essential phase requires it.
3. OPTIONAL — useful polish or breadth that may be deferred without invalidating the result.

Classify each phase qualitatively as LOW, MEDIUM, or HIGH expected usage. Base the classification on likely context volume and iteration count, not elapsed time alone. Typical high-cost actions include broad repository ingestion, long test suites, large generated artifacts, repeated browser research, image/PDF analysis, and multi-agent work.

Do not manufacture a long plan for a small task. In SAVER, the plan can be one sentence.

4. Execute with progressive escalation

Start with the cheapest credible method and escalate only when the current evidence cannot establish the answer.

• Scope first: locate the relevant files, symbols, failures, or source pages.
• Test the leading hypothesis before investigating every alternative.
• Make the smallest change that satisfies the user's request.
• Prefer focused commands and filters; cap noisy output at the source.
• Avoid reopening unchanged evidence.
• Stop failed approaches after two materially equivalent attempts. Record the obstacle and change strategy instead of looping.
• Skip optional cleanup, unrelated warnings, speculative refactors, and duplicate explanations.

When a new high-cost action becomes necessary in SAVER or would violate a custom restriction, do not silently run it. If a cheaper valid alternative exists, use it. Otherwise stop at the budget gate and create a checkpoint.

5. Preserve the verification floor

Budgeting changes breadth, not truthfulness. Verification must remain proportional to risk:

• explanation or read-only question: cite the inspected evidence;
• focused code change: run the narrowest relevant test, type check, lint target, or reproducible behavior check;
• risky or cross-cutting change: explain that SAVER is insufficient, then narrow the change or checkpoint before broader validation;
• current factual claim: verify against an authoritative current source;
• destructive, publishing, deployment, payment, or external communication action: follow the normal authorization rules regardless of mode.

Never mark the task complete when required checks were skipped. Use PARTIAL or CHECKPOINTED and state what remains.

6. Close with evidence and a resumable report

Create a compact Markdown report using references/report-schema.md. When shell access is available, generate it with:

node <skill-directory>/scripts/generate_report.mjs <input.json> <output.md>

Default path:

outputs/<task-slug>-codex-budget-report.md

The report must distinguish observed account-level usage from estimates, completed work from deferred work, deliberate savings from unavailable measurements, verified outcomes from assumptions, and a complete result from a resumable checkpoint.

If work stops at a budget gate, include the exact next action, relevant files, commands already run, unresolved evidence, and a ready-to-copy resume prompt. Finish the chat with status, the most important result, and a clickable absolute path to the report.

Example invocations

Use $codex-budget-mode in Saver mode to fix this failing validation test.

Use $codex-budget-mode in Balanced mode to review and improve this API endpoint.

Use $codex-budget-mode with no subagents, no web research, and one focused test command.

Use $codex-budget-mode to finish as much of this migration as is safely possible, then save a checkpoint before expensive work.