Codex Optimization Tips
Best practices for getting the most out of OpenAI Codex on the GPT-5 family (current flagship: gpt-5.5) — without burning through tokens or trust.
AGENTS.md Hygiene
AGENTS.md is loaded on every session. Every kilobyte you put here is a tax on every future request. Treat it like the table of contents — not the encyclopedia.
Cap each AGENTS.md at ~200 lines
Beyond ~200 lines, split into a nested subdir/AGENTS.md or extract a workflow into a Skill. Codex caps total AGENTS.md content at ~32 KiB by default (project_doc_max_bytes).
Use AGENTS.override.md for subdirs
When a specific area (e.g. services/payments/) needs rules that contradict the root, use AGENTS.override.md. Codex merges files closer to your CWD over earlier guidance.
Push procedures into Skills
If a section of AGENTS.md describes how to do a multi-step task, it belongs in a Skill — not in always-on instructions. Skills are progressively disclosed; they only enter context when needed.
Designing Skills
Skills follow the open AgentSkills standard. Codex reads only the description field at session start and loads the rest on demand.
Write descriptions like search queries
"Run the project's full test suite, summarize failures, and propose a fix plan. Use when the user asks for tests, verification, or coverage." — clear, action-oriented, name the trigger words.
One Skill, one outcome
A Skill that does three things will be a Skill that does none of them well. Split. The cost of a short Skill is near zero — Codex only loads it when needed.
Cite inputs and outputs
Every Skill should declare what it expects (inputs) and what it produces (outputs). This makes Codex's plan auditable and turns Skills into building blocks for larger workflows.
Match Reasoning Effort to the Task
Reasoning effort is the single biggest knob for Codex cost and quality. The default is fine for most edits, but use high or xhigh when the problem genuinely requires it.
minimal / low
Classification, formatting, simple Q&A, log scans.
medium (default)
Edits, refactors, small features, normal debugging.
high
Architecture decisions, hard debugging, multi-file refactors.
xhigh
Math proofs, complex algorithms, security-critical analysis. Only when evals justify it.
Promote, don't default
Don't Confuse .rules Files With Instructions
Codex has two separate concepts that both get called "rules" in casual conversation. Keep them straight:
AGENTS.md (instructions)
Markdown guidance Codex reads at session start. Lives at ~/.codex/AGENTS.md, project root, and nested directories. This is where your Learner Brain rules belong.
.rules files (sandbox policy)
An experimental DSL using prefix_rule() to control which shell commands Codex can run outside the sandbox. Lives in ~/.codex/rules/ or <repo>/.codex/rules/. Not for instructions.
When to use .rules files
.rules when you want to allow, prompt, or forbid specific shell command prefixes (e.g. always prompt before gh pr view, always forbid rm -rf outside the sandbox). Test rules with codex execpolicy check before committing them. See the official Rules docs for the full DSL.Use Approval Modes Intentionally
Approval mode is the speed/safety dial. Match it to your trust in the task and the codebase.
Suggest (read-only)
Best when learning an unfamiliar codebase, reviewing risky changes, or pairing with junior devs. You apply every diff manually.
Auto-Edit (default for daily work)
Codex writes files but asks before running shell commands. The right default once you trust the AGENTS.md and Skills.
Full Auto (sandboxed)
Use for well-scoped tasks with strong tests (e.g. "add this CRUD endpoint and make all tests pass"). Network is disabled by default. Never use Full Auto for tasks you can't verify.
Compensating for Session-Only Memory
Codex doesn't persist conversation memory between sessions. That's a feature, not a bug — your AGENTS.md, Skills, and git history are your persistent memory. The trick is keeping them current.
The Brain Harvest habit
Common Mistakes
Treating AGENTS.md like a wiki
AGENTS.md should be terse, durable, and load-cheap. If you're writing paragraphs of prose, it belongs in a Skill or a separate doc the Skill links to.
Always running on xhigh effort
Latency and cost compound fast. If medium gets the right answer in one shot, that's the right setting.
Full Auto with weak tests
Full Auto + no tests = a confident agent shipping confident bugs. Either invest in tests or stay in Auto-Edit.
Never harvesting
Codex is stateless between sessions. Without a harvest habit, every Monday starts from scratch.
This template was last reviewed in April 2026 against the official OpenAI Codex docs. Spot something out of date? Let us know.