OpenAI Codex AGENTS.md guide: 32 KiB limit and overrides.
By Bernard Huang · Updated
How Codex discovers, orders, and truncates ~/.codex/AGENTS.md, repo AGENTS.md, and AGENTS.override.md for GPT-6 Astra and GPT-6 Sol.
On this page
The exact AGENTS.md discovery and merge order.
Codex builds its instruction chain once when a session starts:
| Order | File path | Behavior & precedence |
|---|---|---|
| 1 (First) | ~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md | Your personal global defaults across all projects (also editable in the desktop app under Settings → Personalization). |
| 2 | <repo-root>/AGENTS.override.md or <repo-root>/AGENTS.md | Repository-wide build, test, and architecture rules shared with the team. |
| 3 (Last) | Intermediate folders down to <cwd>/AGENTS.override.md or <cwd>/AGENTS.md | Package or subfolder rules. Appears last in the prompt, so it wins conflicts with earlier files. |
In any folder where both AGENTS.override.md and AGENTS.md exist, Codex loads AGENTS.override.md and skips the sibling AGENTS.md.
The 32 KiB cap (project_doc_max_bytes) and silent truncation.
By default, Codex enforces a combined budget of 32 KiB (32,768 bytes) across all discovered instruction files via project_doc_max_bytes in ~/.codex/config.toml. Once the total hits 32 KiB, Codex stops reading further rules.
Two practical rules follow:
- Keep
~/.codex/AGENTS.mdunder 2 KiB: A 25 KiB personal file leaves almost no room for repo or packageAGENTS.mdfiles in a monorepo. Fifteen to twenty-five lines is plenty for personal tone. - Raise the cap or link docs when needed: If your repo requires large instruction files, increase
project_doc_max_bytesin~/.codex/config.tomlor move long reference manuals into linked files.
What belongs in ~/.codex/AGENTS.md vs repo AGENTS.md.
Separate personal communication habits from shared team rules:
~/.codex/AGENTS.md(personal): How GPT-6 Astra or GPT-6 Sol should talk to you—answer-first order, prose vs tables, approval checkpoints, and pushback on weak premises.<repo-root>/AGENTS.md(team): Build commands, test runners, linter flags, and architecture boundaries that apply to everyone.<repo-root>/AGENTS.override.md(local gitignored override): Use only when you need to temporarily override a broken repoAGENTS.mdon your machine.
Starter personal block for ~/.codex/AGENTS.md (~620 bytes, leaving over 31 KiB for repo files):
How personality = "none" in config.toml interacts with AGENTS.md.
As noted in our GPT-6 Astra guide and GPT-6 Sol guide, Codex 0.155.x retired the older Friendly/Pragmatic personality picker. Setting personality = "none" in ~/.codex/config.toml strips the built-in personality block from the system prompt (which on Astra also removes default technical-writing rules). Leaving config.toml at its default and adding 6–8 lines to ~/.codex/AGENTS.md is safer and easier to audit.
Questions people ask.
What is the maximum file size for AGENTS.md in OpenAI Codex?
By default, OpenAI Codex reads up to 32 KiB (32,768 bytes) combined across all AGENTS.md files in the hierarchy, controlled by project_doc_max_bytes in ~/.codex/config.toml.
What is the difference between AGENTS.md and AGENTS.override.md?
In any directory where AGENTS.override.md is present, Codex loads AGENTS.override.md instead of the sibling AGENTS.md in that same directory. Files in parent or child directories still merge normally.
Which wins when ~/.codex/AGENTS.md and the repo's AGENTS.md conflict?
The repository's AGENTS.md (and any subdirectory AGENTS.md closer to your current working directory) is appended later in the prompt and overrides conflicting rules from ~/.codex/AGENTS.md.
Why didn't Codex pick up my edits to AGENTS.md?
Codex builds its instruction chain once when a session or run starts. Start a new Codex session after editing ~/.codex/AGENTS.md or your repository's AGENTS.md.
What changed.
- First published with the 32 KiB project_doc_max_bytes merge order and AGENTS.override.md precedence table.