Codex AGENTS.md: where it goes, the order it loads, and what to write

Where Codex looks for AGENTS.md, in load order

Codex builds the instruction chain once when it starts (in the terminal UI, once per session). Files are joined from the top of this table down, so instructions closer to your working directory come later and win.

How to set up AGENTS.md for Codex

1. Create global defaults

   Run mkdir -p ~/.codex and write ~/.codex/AGENTS.md with preferences you want in every repository. Check it loaded by asking Codex to summarize its instructions.

   # ~/.codex/AGENTS.md
   
   ## Working agreements
   
   - Always run `npm test` after modifying JavaScript files.
   - Prefer `pnpm` when installing dependencies.
   - Ask for confirmation before adding new production dependencies.

2. Add a project file, and overrides where teams differ

   Put an AGENTS.md at the repository root for shared setup. In a folder with different rules, add AGENTS.override.md: it replaces that folder's AGENTS.md, which Codex then ignores.

   # AGENTS.md (repository root)
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.
   
   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use `make test-payments` instead of `npm test`.
   - Never rotate API keys without notifying the security channel.

3. Confirm what loaded

   Start Codex in the folder you care about, for example codex --cd services/payments, and ask it to list the instruction sources it loaded. It should list the global file, then the root file, then the folder's file.

4. Reuse an existing file name, or raise the limit

   If your repository already keeps instructions in another file, add it to project_doc_fallback_filenames in ~/.codex/config.toml. Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default.

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

5. Add rules for Codex code review

   For @codex review on GitHub, add a ## Code Review Rules section to the AGENTS.md closest to the code it governs. Say what to flag and the safe alternative; leave formatting and lint to CI.

   ## Code Review Rules
   
   ### Experiment cohorts
   
   - Do not filter treatment comparisons on post-exposure behavior.
     Safe path: build cohorts from assignment or exposure.

Source: Codex docs, Custom instructions with AGENTS.md

AGENTS.md best practices

• Keep it to what Codex can't work out: exact build, test and lint commands (including how to run one test), traps in the codebase, and decisions that aren't written down.
• Put the most specific rules closest to the code: a nested AGENTS.md in services/payments/ beats a long root file with a payments section.
• Mind the 32 KiB budget: files are added from the root down and the rest is cut off, so split long files into nested ones or raise project_doc_max_bytes.
• Use AGENTS.override.md for temporary changes, globally or in one folder, and delete it to go back.
• An empty AGENTS.md is skipped, and the search for that directory moves on to the next file name.
• Use a separate CODEX_HOME for automation users so their global instructions don't mix with yours.

AGENTS.md in Codex vs Claude Code and others

AGENTS.md is an open format that many agents read, which makes it the best place for instructions you want to share. Claude Code has its own file, CLAUDE.md; see the CLAUDE.md guide for the details.

AGENTS.md tells Codex how. Crewmark tells it what's next.

A good AGENTS.md makes every Codex session start informed; the session still waits for your prompt. Crewmark turns a Codex, Claude Code, DeepSeek Harness or OpenCode session into an AI employee with a role, a goal and working hours, and wakes it on a heartbeat to take the next issue from a board.

1. Keep AGENTS.md in the repository

   The employee's Codex session reads it like yours, so conventions and test commands come along.

2. Let the heartbeat start the work

   During working hours the employee wakes every 15, 30 or 60 minutes in the same conversation; see how to make Codex proactive.

3. Mix agents on one board

   One AGENTS.md can serve Codex and Claude Code employees side by side; compare them in Claude Code vs Codex.

Codex AGENTS.md FAQ