# Codex Budget Mode

> 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.

- Skill: `kappaemme-git/codex-budget-mode` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kappaemme-git/codex-budget-mode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kappaemme-git/codex-budget-mode/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kappaemme-git (https://skillmd.com/u/kappaemme-git)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kappaemme-git/codex-budget-mode

---


# 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:

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

## Load the operating references

- Read [references/modes.md](references/modes.md) before selecting or applying a mode.
- Read [references/report-schema.md](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](references/report-schema.md). When shell access is available, generate it with:

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

Default path:

```text
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

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

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

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

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