AGENTS.md for Codex: discovery, precedence, size limits and examples

What AGENTS.md does

AGENTS.md is a plain Markdown file that Codex reads before it starts working. Whatever is in it becomes part of the instructions for the whole session, so it is the place for things Codex should know on every task in a repository: how to build and test, which conventions to follow, and what not to touch.

It is not Codex-specific. AGENTS.md is a shared convention that several coding agents read, so one well-written file serves more than one tool. This guide covers how Codex in particular discovers, merges and limits these files.

How Codex finds AGENTS.md files

Codex builds an instruction chain once per run (in the interactive CLI, once per launched session). Discovery happens in two layers.

1. Global scope. In your Codex home directory (~/.codex unless you set CODEX_HOME), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. Only the first non-empty file at this level is used.

2. Project scope. Starting at the project root (normally the Git root), Codex walks down to your current working directory. In each directory on that path it checks, in order:

1. AGENTS.override.md
2. AGENTS.md
3. any names listed in project_doc_fallback_filenames

It includes at most one file per directory. If Codex cannot find a project root, it only checks the current directory.

Merge order. Files are concatenated from the root down, separated by blank lines. Because files closer to your working directory appear later, their guidance takes precedence over broader files. Empty files are skipped.

Here is how that plays out in a repository with a payments override:

repo/
├── AGENTS.md                      # loaded second
└── services/
    ├── payments/
    │   ├── AGENTS.md              # ignored: an override exists in this directory
    │   └── AGENTS.override.md     # loaded last when you work in services/payments
    └── search/
        └── AGENTS.md              # loaded only when you work under services/search

Starting Codex in services/payments gives you ~/.codex/AGENTS.md, then repo/AGENTS.md, then services/payments/AGENTS.override.md. Starting it at the repository root gives you only the first two: Codex stops at the working directory and does not read files in subdirectories below it. Start Codex where the work is, or use codex --cd services/payments.

The size limit

Codex stops adding files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default. Content past the limit is not included, and the files at the end of the chain (the most specific ones) are the ones at risk.

You can raise the cap, and add fallback names if your repository already uses a different filename:

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

With that config each directory is checked for AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md and .agents.md, in that order. Restart Codex after changing it.

Raising the limit is rarely the right fix. Every byte of AGENTS.md is in context on every task, including tasks it has nothing to do with. A root file of 30 to 150 lines is a sensible target; if yours is longer, look for sections that only matter to one kind of task and move them into skills.

What to put in it

Write for a capable engineer on their first day who will not ask questions. Include what they would get wrong without being told:

• Commands. Exact install, build, test, lint and type-check commands, including how to run a single test. Codex runs these to verify its work.
• Layout. Where the important code lives, which directories are generated, which are vendored.
• Conventions that differ from the default. Your error-handling pattern, naming rules, the logging library you use and the one you migrated away from.
• Boundaries. Files or directories not to edit, actions that need confirmation (new dependencies, migrations, anything touching billing).
• Definition of done. For example: tests pass, types check, no new lint warnings, changelog entry added.

Leave out what Codex can infer from the code, general programming advice, long background documents and anything that applies only to one kind of task. Formatting rules your linter already enforces are wasted bytes; let the linter catch them.

Example: a TypeScript web app

# AGENTS.md

## Commands
- Install: `pnpm install` (never npm or yarn)
- Dev server: `pnpm dev`
- All tests: `pnpm test`; one file: `pnpm vitest run src/lib/cart.test.ts`
- Before finishing: `pnpm lint && pnpm typecheck && pnpm test`

## Layout
- `src/app/` Next.js App Router routes; `src/lib/` shared logic; `src/components/ui/` generated by shadcn, do not hand-edit.

## Conventions
- Server data access only through `src/lib/db/`; components never import Prisma directly.
- Validate request bodies with the Zod schemas in `src/lib/schemas/`.

## Boundaries
- Ask before adding a production dependency or changing `prisma/schema.prisma`.
- Never edit `.env*` files or commit secrets.

Example: a Python service

# AGENTS.md

## Setup and checks
- `uv sync` installs everything. Run tools through `uv run`.
- Tests: `uv run pytest -q`; one test: `uv run pytest tests/test_orders.py::test_refund -q`
- Lint and types: `uv run ruff check . && uv run mypy src`

## Rules
- Database changes go through Alembic: `uv run alembic revision --autogenerate -m "..."`, then review the generated file.
- Public functions in `src/orders/` need type hints and a docstring.
- Do not call external APIs in tests; use the fakes in `tests/fakes/`.

Example: a monorepo with nested files

Keep the root file about the whole repository, and put package rules next to the package:

# AGENTS.md (repo root)
- Workspace tool: pnpm workspaces + Turborepo. Run tasks with `pnpm turbo run <task> --filter <package>`.
- Each package has its own AGENTS.md with its commands. Read it before editing that package.
- Shared types live in `packages/types`; change them in a separate commit.

# packages/billing/AGENTS.override.md
- Tests: `pnpm turbo run test --filter billing`
- Money is integer cents everywhere. Never use floats for amounts.
- Any change to `src/webhooks/` needs a test with a recorded Stripe payload.

The agents-md-monorepo skill structures this for large repositories.

Your global file

~/.codex/AGENTS.md applies to every repository you open. Keep it about you, not about any codebase: how much explanation you want, whether to ask before committing, the package manager you prefer when a project does not say. Use ~/.codex/AGENTS.override.md for a temporary change without deleting the base file; remove the override to go back.

Generate a first draft

In the Codex CLI, /init creates an AGENTS.md scaffold in the current directory. Treat it as a draft: delete anything generic, check every command by running it, and add the boundaries only you know about. The agents-md-authoring skill does a stricter version of this, preferring short, verified rules.

Check what Codex loaded

From the repository root, ask Codex to report its instructions without making changes:

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

For an exact view of what the model sees, codex debug prompt-input renders the model-visible prompt input as JSON. You can also enable a plaintext log with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log.

If guidance looks wrong:

• Nothing loads: confirm you are inside the repository you expect and the file is not empty.
• Wrong guidance: look for an AGENTS.override.md higher in the tree or in ~/.codex.
• Fallback names ignored: check spelling in project_doc_fallback_filenames and restart.
• Truncated: shorten the files or split them into nested directories.
• Different home: run echo $CODEX_HOME; a custom value points Codex at another directory.

There is no cache to clear. Codex rebuilds the chain at the start of every run.

Code review rules

If you use Codex code review on GitHub, add a ## Code Review Rules section to the AGENTS.md closest to the code the rules govern. State the behavior to flag and the safe alternative, and leave formatting to CI:

## Code Review Rules
- Flag any query in `src/reports/` that filters on a column without an index; suggest the index.

AGENTS.md compared with skills

Both are Markdown, both shape behavior, and they are easy to confuse.

	AGENTS.md	Skill
When it loads	Every session, before any work	Body loads only when the task matches or you mention it
Context cost	Full file, always	Name and description always; body on demand
Good for	Short rules that apply to every task	Long procedures for one kind of task
Scope	Directory chain from root to working directory	Repo, user, admin or system skill folders
Can bundle scripts	No	Yes, in scripts/

If your AGENTS.md has a 60-line section on how to cut a release, move it into a release skill and leave one line behind: “To cut a release, use $release.” The comparison guide covers MCP and plugins as well.

Keep it current

Treat AGENTS.md as a feedback loop. When Codex makes the same mistake twice, add a rule. When you leave the same review comment twice, add a rule. When Codex reads too many files to find the right one, add a line pointing to it. When you correct Codex during a session, ask it to update AGENTS.md so the next session inherits the fix, and review that change like any other code.