Codex Context Budget skill for Codex

A session is lean when the fixed preamble (instructions, skills catalog, tool schemas) is a small fraction of the window, every file read answers a specific question, and compaction happens at a clean checkpoint instead of in the middle of a fix.

Know where the tokens go

Bucket	Loaded when	Control
Built-in and developer instructions	Every turn	developer_instructions, model_instructions_file (rarely worth changing)
AGENTS.md chain	Session start, every turn after	Keep files short; nest per package; project_doc_max_bytes (default 32 KiB) caps the total
Skills catalog (name, description, path)	Every turn	Default budget 2% of the window; skills.max_context_tokens (max 10000); disable unused skills with [[skills.config]]
MCP tool definitions	Every turn, per enabled server	enabled = false, enabled_tools, disabled_tools per server
Tool output (commands, file reads)	When produced, stays in history	Read narrowly; tool_output_token_limit; per-MCP-tool tools.<tool>.output_token_limit
Conversation history	Grows each turn	/compact, model_auto_compact_token_limit, new chat with a handoff note

Workflow

- [ ] 1. Measure the fixed preamble
- [ ] 2. Trim always-on context
- [ ] 3. Read the repo surgically
- [ ] 4. Isolate exploration from the main thread
- [ ] 5. Compact or restart at checkpoints

1. Measure

• In a session: /status shows token usage and remaining context; /mcp verbose shows which servers and tools are loaded.
• Before a session, render exactly what the model will see on its first turn:

codex debug prompt-input "hello" > /tmp/prompt.json
jq -r '.[] | "\(.role // .type)\t\(tostring | length)"' /tmp/prompt.json   # chars per item
wc -c AGENTS.md $(git ls-files '*AGENTS*.md')                              # instruction files

Divide characters by about 4 for a rough token count. If the preamble is more than roughly 10% of the model’s window, trim it before starting a long task.

2. Trim always-on context

• AGENTS.md: keep the root file to commands, conventions and hard rules. Move package-specific rules into that package’s AGENTS.md, which only loads when Codex runs from inside it. Move long reference material to docs/ and link it.
• MCP servers: disable servers the task does not need, or allowlist tools:

[mcp_servers.github]
enabled_tools = ["get_pull_request", "list_pull_request_files"]

[mcp_servers.browser]
enabled = false            # re-enable per run: -c mcp_servers.browser.enabled=true

• Skills: a large personal skill library shortens every description and can drop skills from the catalog. Disable ones irrelevant to this machine:

[[skills.config]]
path = "/Users/me/.agents/skills/legacy-deploy/SKILL.md"
enabled = false

• Scope the run: start Codex in the package you are changing (codex -C packages/api) so only the relevant nested AGENTS.md files load and the workspace is smaller.

3. Read the repo surgically

Rules for the agent:

• Locate before reading: rg -n "createSession" src/, rg --files -g '*.sql' | head, git ls-files | wc -l.
• Read ranges, not files: sed -n '120,200p' src/auth/session.ts. Check size first with wc -l and never cat a file over ~400 lines whole.
• Never read lockfiles, generated code, minified bundles, snapshots, dist/, or vendored dependencies unless the task is about them.
• Cap command output: npm test 2>&1 | tail -n 80, git log --oneline -20, rg -c pattern before rg pattern.
• Summarize what was learned after a big read (“session.ts: tokens refreshed in refresh() at L140, no locking”) so later turns rely on the note, not the raw dump.
• Prefer git diff --stat then targeted git diff -- <path> over a full diff.

4. Isolate exploration

Need	Use
A quick question that should not pollute the main thread	/side <question> (CLI) or /side (IDE)
Broad search across many files, only the conclusion matters	A subagent (multi-agent is on by default); ask it to return paths and findings only
A different approach to compare	/fork
Unrelated next task	/new (keeps the terminal) or /clear

5. Compact or restart at checkpoints

• Run /compact after a milestone is verified (tests green, commit made), not halfway through a failing fix: the summary then describes a stable state.
• Before compacting, ask for the facts that must survive: file paths, decisions, commands, open problems. They will be carried in the summary.
• Auto-compaction triggers at model_auto_compact_token_limit (unset uses the model default). Lower it only if quality degrades before auto-compaction fires.
• When a session has compacted several times and still drifts, write a handoff note and start a new chat from it (see agent-handoff-notes).

Gotchas

• A bloated AGENTS.md is paid on every turn of every session; a long file read is paid once but stays in history until compaction.
• project_doc_max_bytes truncates silently from the end of the chain: the most specific nested file can be the one that gets cut.
• Each enabled MCP server adds its tool schemas even if never called.
• Raising skills.max_context_tokens makes the catalog fit but costs tokens every turn; disabling unused skills is usually better.
• Images and screenshots are expensive; attach only the ones the task needs.
• Compaction is lossy. Exact error strings, line numbers and command flags are the first casualties; write them into a note or the plan before compacting.

Verification

• /status shows lower usage at the same point of a comparable task.
• codex debug prompt-input output shrinks after trimming (record before/after bytes).
• The agent still follows the rules that moved into nested AGENTS.md files when run from those directories.

Output template

## Context budget report
| Item | Before | After | Change made |
|---|---|---|---|
| Prompt preamble (chars) | 92,400 | 38,100 | Disabled 3 MCP servers, nested AGENTS.md |
| Root AGENTS.md (bytes) | 21,000 | 4,800 | Moved API rules to services/api/AGENTS.md |
| Skills in catalog | 74 | 31 | Disabled unused personal skills |
Reading rules adopted: rg first, line ranges, output capped with tail.