Codex Budget Mode

Make Codex complete the task without wasting the rest of your usage limit.

Codex Budget Mode is a usage-aware execution policy for coding, repository work, and research. It reduces unnecessary context, broad scans, repeated commands, speculative work, web searches, and delegation while preserving the checks required for a trustworthy result.

It does not pretend to install a magical server-side quota. It creates a visible soft budget, works within it, and leaves a resumable checkpoint when safe completion would require more.

Quick start

Install the skill:

npx --yes codex-budget-mode@latest

Then ask Codex:

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

The three modes

| Mode | Best for | Default behavior | |---|---|---| | Saver | Small fixes, focused research, low remaining usage | Narrow inspection, no subagents, minimal output, one targeted verification path | | Balanced | Normal implementation, diagnosis, and review | Relevant surrounding context, focused verification, limited escalation | | Full Power | Explicitly requested depth or broad coverage | Wider evidence and validation while still respecting scope and stop conditions |

You can also define a custom contract:

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

How it works

flowchart LR
    U[Your task] --> B[Budget contract]
    B --> S[Smallest credible inspection]
    S --> E[Essential work]
    E --> V[Verification floor]
    V --> C{Safe and within budget?}
    C -->|Yes| R[Native Markdown report]
    C -->|No| P[Resumable checkpoint]

At the beginning, Codex declares the operating contract:

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

It then separates the work into:

• Essential: required to complete the task safely.
• Conditional: performed only when the evidence demands it.
• Optional: polish or breadth that can be deferred.

What it reduces

• loading entire repositories when targeted search is enough;
• reopening unchanged files and replaying large logs;
• speculative refactors and unrelated cleanup;
• repeated web searches and redundant sources;
• unnecessary subagents and duplicated investigations;
• full test suites for isolated, low-risk changes;
• retry loops that repeat the same failed approach;
• long progress narration and oversized final responses.

The skill does not blindly avoid expensive work. When a broad test or deeper inspection is necessary for correctness, it either performs it within the selected mode or checkpoints honestly before proceeding.

Verification is never optional

Budgeting changes coverage, not truthfulness.

A focused code change still needs a relevant test or observable behavior check. Current factual claims still need authoritative sources. Risky, destructive, publishing, deployment, payment, and external communication actions still follow the normal authorization rules.

If the selected budget cannot support safe verification, the result is marked PARTIAL or CHECKPOINTED—never falsely reported as complete.

Account usage snapshots

When the Codex host exposes a read-only usage tool, the skill may capture one account snapshot at the beginning and one at the end. It records the available windows, percentages, and reset times.

Those numbers remain account-level observations. They may include rounding, delayed reporting, caching, or activity from other tasks, so the skill never presents the difference as an exact per-task token bill.

When snapshots are unavailable, the skill converts the requested budget into observable workflow restrictions instead of inventing a percentage.

Native Codex report

Every run produces a compact Markdown decision record:

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

The report contains:

• selected mode and objective;
• scope, restrictions, and verification floor;
• completed phases and evidence;
• observed, estimated, or unavailable usage measurement;
• verification commands and results;
• deliberately deferred work;
• an exact resume prompt when work stops at a budget gate.

See the synthetic demo report.

More prompts

Conserve usage during a small implementation:

Use $codex-budget-mode in Saver mode to add validation to this endpoint.

Keep an ordinary refactor controlled:

Use $codex-budget-mode in Balanced mode to refactor this hook without changing behavior.

Finish only what can be verified cheaply:

Use $codex-budget-mode to complete the essential part of this migration and checkpoint before broad integration testing.

Create an explicit operational ceiling:

Use $codex-budget-mode with one discovery pass, no browser research, and at most two verification commands.

Difference from a prompt optimizer

A prompt optimizer reduces the size or ambiguity of one prompt before execution.

Codex Budget Mode governs the entire task: discovery, context loading, tool calls, implementation breadth, retries, verification, reporting, and resumption. The two workflows can complement each other, but they solve different problems.

Important limitations

• A skill cannot change OpenAI's account limits or enforce a server-side hard cap.
• Exact task-level usage may not be available to the agent.
• The skill cannot silently change the current model or reasoning setting when the host does not expose that control.
• Smaller scope can reduce coverage; the report makes that boundary explicit.
• Full Power mode increases depth but cannot guarantee a perfect result.
• Usage policies and available host tools may change over time.

Development

Generate the demo report and run the tests:

npm run demo
npm test

License

MIT