AGENTS.md for Codex: The Complete Config Guide (2026)
AGENTS.md is Codex's (OpenAI Codex CLI) persistent instruction file, read automatically before it works in a repo. Codex looks for it in a fixed search order (global, then git-root down to your current directory), concatenates everything it finds, and caps the combined size at 32 KiB - go over that and the rest gets silently dropped. One thing worth remembering: Codex does not read CLAUDE.md. This guide covers the mechanics: search order, how files merge, the size cap, and a real AGENTS.md you can copy.
- Codex's AGENTS.md mechanics move fast; the details below were cross-checked against the official docs at the time of writing (Aug 2026) - verify the live docs before you depend on them.
What AGENTS.md does in Codex (and the CLAUDE.md line)
AGENTS.md is the persistent instruction file Codex loads into context every time you open a session - project conventions, test/build commands, and rules it must not break, so you're not repeating them in every prompt. Per the official learn.chatgpt.com/codex/agent-configuration/agents-md docs, Codex finds and loads AGENTS.md files through a fixed mechanism - but that same page never once mentions CLAUDE.md. To be direct: as of now, Codex does not read CLAUDE.md, even though CLAUDE.md and AGENTS.md serve the exact same idea.
One line to avoid confusion: AGENTS.md (Codex's config file) is different from AgentKit (the kit that runs inside Codex/Claude Code, agentkit.best) and from OpenAI AgentKit (OpenAI's Agent Builder/ChatKit).
If you also run Claude Code and want to know whether a long context file actually helps, see AGENTS.md vs CLAUDE.md - and whether long files even help - that piece covers the research; this one is about Codex's own config mechanics.
Where Codex looks for AGENTS.md - the exact search order
Codex doesn't read a single AGENTS.md file - it walks multiple levels, in this exact order (per the official docs):
- Global level: Codex checks
~/.codex/AGENTS.override.mdfirst; if it exists, Codex uses it instead of~/.codex/AGENTS.md. No override, it reads~/.codex/AGENTS.md. - Directory level (walking from git-root down to your current directory): Codex finds the git repo root, then walks down each directory level to
cwd(wherever you're running Codex from). At every level, it applies the same override rule: anAGENTS.override.mdat that level wins; otherwise it usesAGENTS.md.
Example: you're in ~/projects/shop/apps/web, and the git root is ~/projects/shop. Codex checks, in order: global (~/.codex/) → ~/projects/shop/AGENTS.md (git-root) → ~/projects/shop/apps/AGENTS.md (if it exists) → ~/projects/shop/apps/web/AGENTS.md (cwd). Anything missing is simply skipped - no error.
What the override file is actually good for: keep a shared AGENTS.md committed to git for the whole team, while dropping personal or machine-specific tweaks into an .override.md at the same level - without touching the file everyone shares.
Worth remembering: this is not "closest file wins, the rest get ignored" - every file found gets merged together (next section), not just one picked.
How files merge - root-down concatenation, closer file wins
Once Codex finds them, it doesn't pick one file - it concatenates everything it found into one context block, in the same order as the search: global first, then git-root, then each subdirectory, separated by blank lines. Because a file closer to cwd gets appended last, it lands at the end of the context - and when two instructions conflict, the one that appears later (closer to cwd) is usually what the agent follows.
A 3-file example, and which one wins on conflict:
~/.codex/AGENTS.md(global): "Always run the full test suite before committing."~/projects/shop/AGENTS.md(git-root): "Use pnpm, not npm."~/projects/shop/apps/web/AGENTS.md(cwd): "Only run unit tests (pnpm test:unit) when editing this directory - the full suite is too slow to iterate against."
These three don't fully contradict each other, but rule 3 genuinely conflicts with rule 1. Because rule 3 is appended last, Codex tends to follow it while working inside apps/web. That's exactly why the file closest to you should carry specific, local instructions, while the global/root file should stick to broad, stable conventions. Practically, this also means a subdirectory AGENTS.md can't fully "unset" a global rule - it can only add a later, more specific instruction that the agent tends to weigh more heavily in that context.
The 32 KiB cap - project_doc_max_bytes
The combined size of every AGENTS.md file found (not each file individually) is capped by project_doc_max_bytes, which defaults to 32 KiB. Per the config-advanced docs, Codex skips empty files and stops adding content the moment the combined size hits the cap - anything past that point never makes it into context, with no error or warning in the TUI.
To raise the limit, add this to ~/.codex/config.toml:
project_doc_max_bytes = 65536(65536 bytes = 64 KiB is just an example - set it to what you actually need. Don't bump it "just in case": the longer the file, the more the agent tends to over-act on every line - see the lean example below.)
| Setting | Value |
|---|---|
| Default | 32 KiB (applies to all AGENTS.md files combined) |
| Configured via | project_doc_max_bytes in ~/.codex/config.toml |
| Over the cap | Stops adding content - no error, no warning |
| Empty files | Skipped, don't count toward the total |
The silent-truncation gotcha (a real bug report)
This is the part most other guides skip. GitHub Issue #7138 (opened 2025-11-22, closed as "not planned") documents exactly this: a user's combined AGENTS.md ran to roughly 40 KB, and Codex silently cut it down to 32 KB - no warning in the TUI, none in /stats either. The issue explicitly contrasts this with Claude Code, which does warn when a context file goes over budget.
Note: as of writing, this issue is closed "not planned" - meaning the Codex team has no plan to add a warning. Re-check the issue's status before citing it; trackers change.
The practical fix: don't stuff every convention into one giant root AGENTS.md. Split by directory - keep the global file for broad conventions, and let each subdirectory carry only what's relevant to it - which both keeps you under the 32 KiB cap and matches what the AGENTS.md/CLAUDE.md research already found: long files don't help, they just cost more.
project_doc_fallback_filenames and CODEX_HOME
Two smaller settings worth knowing if you customize deeply:
project_doc_fallback_filenames: an array of alternate filenames Codex accepts at a directory level when no AGENTS.md exists there - useful if your team already has aTEAM_GUIDE.mdand isn't ready to rename it. Set it in~/.codex/config.toml:project_doc_fallback_filenames = ["TEAM_GUIDE.md"].CODEX_HOME: the environment variable pointing to Codex's config directory, default~/.codex. It holdsconfig.toml,auth.json, andhistory.jsonl- change it if you want to split Codex config per profile or machine (for example, a separateCODEX_HOMEper CI runner so automated sessions never touch your personalauth.json).
A real, lean AGENTS.md you can use
Here's the root AGENTS.md I actually run for a Node/TypeScript repo - deliberately short, because a longer file doesn't make Codex perform better (see the gotcha above and the context-file research):
# Build & test
- Install: `pnpm install`
- Unit tests: `pnpm test` - e2e: `pnpm test:e2e` (Playwright, slow, run only when needed)
- Build: `pnpm build`
- Before committing: `pnpm lint && pnpm typecheck`
# Must not break
- Don't change the public API in `src/sdk/` without a major version bump.
- Never commit `.env*` files.
- Don't touch `infra/` (Terraform) outside a reviewed PR.
# Key paths
- API routes: `src/api/`
- Shared types: `src/types/`
- DB migrations: `db/migrations/` (never edit an applied migration, always add a new one)15 lines. No "project overview," no explanatory prose. Every line is either a runnable command or a specific must-not-break rule - exactly the part the research on AGENTS.md vs CLAUDE.md found agents actually act on.
AGENTS.md sets the rules - AgentKit adds the skills
AGENTS.md is free config that Codex reads natively - nothing to install. It answers "what to do / what not to do." What it doesn't bring is packaged skills or workflows - that's what AgentKit (agentkit.best, the ak CLI) adds, running on top of Codex, not replacing AGENTS.md.
Installing the kit for Codex: ak kit init engineer --target codex --global (add --global to use it across every repo), then inside a new Codex session run $ak:cook ... (note the $ak: syntax on Codex, vs /ak: on Claude Code - Codex delivery is currently native-only: skills, rules, agent dispatch, partial hooks; kit commands aren't active there yet, and there's no status line).
To be straight about the free/paid line: AGENTS.md costs nothing. AgentKit is a paid add-on (Engineer Kit around $99, the store often runs -20% down to roughly $79.20 at the time of writing - verify the live price). New to Codex? See what OpenAI Codex is first; want to know what SKILL.md actually is (different from AGENTS.md - an on-demand capability, not always-loaded context), see Codex Skills explained; want the walkthrough of running AgentKit inside Codex, see AgentKit in Codex.
Want packaged skills running on top of a lean AGENTS.md? The AgentKit Engineer Kit adds prebuilt workflows/skills for Codex and Claude Code - your AGENTS.md still does the basic rule-setting job.
Frequently asked questions (FAQ)
Does Codex read CLAUDE.md?
No. Per the official docs, Codex only searches for and loads AGENTS.md (and AGENTS.override.md) files - there's no mechanism that reads CLAUDE.md. If you run both Claude Code and Codex on the same repo, keep both files (or symlink one to the other).
What's the AGENTS.md size limit in Codex?
32 KiB by default, applied to the combined total of every AGENTS.md file found (not each file individually), via project_doc_max_bytes. Anything over the cap is silently dropped - no error, no warning. You can raise the limit in ~/.codex/config.toml.
Which file wins if I have global, repo-root, and subdirectory AGENTS.md files?
None of them "wins" outright - Codex merges all of them, in order from global to git-root down to your current directory. Because the file closest to your current directory is appended last, its instructions are usually what gets followed when something conflicts.
What is AGENTS.override.md for?
When present at a level (global or a directory), AGENTS.override.md is used instead of AGENTS.md at that same level. It's useful for keeping a team-shared AGENTS.md in git while adding personal overrides without touching the shared file.
Does Codex warn me if my file is too long?
No, at least as of writing. GitHub Issue #7138 documents a 40 KB file getting silently cut to 32 KB with no TUI warning, and it's closed as not planned. Claude Code, by contrast, does warn when a context file goes over budget - a difference worth remembering.
Where does Codex store its config?
Inside the CODEX_HOME directory, default ~/.codex - holding config.toml, auth.json, and history.jsonl. You can point CODEX_HOME at a different directory via the environment variable.
Conclusion
Codex's AGENTS.md mechanics come down to three things: a fixed search order (global, then git-root down to cwd), root-down concatenation where the file closest to you wins on conflict, and a 32 KiB cap that silently drops the overflow - and none of it ever touches CLAUDE.md. Write it lean, split it by directory instead of stuffing one giant root file, and you dodge both the gotcha and the wasted cost. For why long files don't help in the first place, see AGENTS.md vs CLAUDE.md - and whether long files even help.