Give Codex your repository rules with AGENTS.md

AGENTS.md is a Markdown file that tells a coding agent how to build the project and which rules to follow, kept apart from the human-facing README. This guide covers where and in what order Codex reads it, and what to put in it.

[1] Check the installed version. The behavior below follows the official docs; this version's binary also contains the strings AGENTS.override.md, project_doc_max_bytes and project_doc_fallback_filenames.

$ codex --versioncodex-cli 0.163.0

[2] Learn the read order. Codex builds the instruction list once, when a run starts.

• Global: in the Codex home (~/.codex, or CODEX_HOME), it uses AGENTS.override.md if present and non-empty, otherwise AGENTS.md. Only the first non-empty file at this level counts.
• Project: from the project root (usually the Git root) down to the current directory, it checks AGENTS.override.md, then AGENTS.md, then project_doc_fallback_filenames in each directory and uses at most one file. With no project root, only the current directory is checked.
• Merge: files are joined from the root downward, separated by blank lines. Files closer to the working directory come later and take precedence. Empty files are skipped.

[3] Create the file at the repository root. Keep it short: build and test commands, things not to do, code rules. It is plain Markdown with no required fields.

# AGENTS.md+## Commands- Install: `npm ci`- Test: `npm test` (add tests for code you change)- Lint: `npm run lint`+## Do not- Read or edit `.env` or `secrets/`.- Edit `package-lock.json` by hand.+## Code rules- Keep TypeScript strict.- Use single quotes and no semicolons.

[4] Put rules for one subfolder in that folder's own AGENTS.md. To override temporarily in the same folder, add AGENTS.override.md; it wins, and only one of the two is read per folder.

$ mkdir -p services/payments$ printf '# payments\n- Handle money as integer cents.\n' > services/payments/AGENTS.md

[5] Ask Codex which instruction files it loaded, from the target folder. This needs a login, so it was not run here. The command is the example from the official docs.

$ codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

[6] Settings go in ~/.codex/config.toml. The combined instructions are capped at 32 KiB by default (project_doc_max_bytes); Codex stops adding files once the cap is reached. If a repository uses another file name, register it as a fallback.

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]project_doc_max_bytes = 65536

[7] Relation to other tools: AGENTS.md is a shared format read by many tools. Claude Code reads it when no CLAUDE.md exists (v2.1.277 or later; if a CLAUDE.md exists, only that is read), and Gemini CLI reads it once "context": { "fileName": "AGENTS.md" } is set in .gemini/settings.json. One file can serve several tools.

References: Codex AGENTS.md guide · agents.md · Claude Code memory docs