AGENTS.md for Codex: discovery, overrides and size limit

How Codex finds and merges AGENTS.md files: global, project and nested AGENTS.override.md, fallback filenames, the 32 KiB cap, and how to verify what loaded.

10 October 2026

To use AGENTS.md with Codex well, you need to know which files get loaded, in what order, and what silently drops out. This guide covers the discovery rules, the override file, fallback filenames and the size limit, based on the official Custom instructions with AGENTS.md guide, checked on 2026-10-10. The openai/codex repository doc on the same topic points to that guide as the reference, so confirm details there if behavior changes.

What AGENTS.md does in Codex

According to the Codex guide, Codex reads AGENTS.md files before doing any work. Layering global guidance with project-specific files means each task starts with the same expectations, whichever repository you open. The format itself has a home at agents.md, which the guide links as the place for more information.

Instructions in an AGENTS.md are plain Markdown for the model to read. Conventions the model should follow belong there. Checks that must run every time are a different job; for that kind of enforcement in another tool, see our Claude Code hooks examples. If you also work with that tool, Claude Code skills cover task-specific instructions that load on demand.

How Codex discovers and merges instruction files

Per the discovery section of the guide, Codex builds an instruction chain when it starts: once per run, and in the TUI usually once per launched session.

1. Global scope. In the Codex home directory (~/.codex unless you set CODEX_HOME), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. It uses only the first non-empty file at this level.
2. Project scope. Starting at the project root (typically the Git root), Codex walks down to the current working directory. If it cannot find a project root, it only checks the current directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. It includes at most one file per directory.
3. Merge order. Files are concatenated from the root down, joined with blank lines. Files closer to your current directory appear later in the combined prompt, so they override earlier guidance.

Codex skips empty files and stops adding files once the combined size reaches project_doc_max_bytes.

Example: global ~/.codex/AGENTS.md

From the guide’s global guidance steps:

mkdir -p ~/.codex

# ~/.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.

Then confirm it loads, from any directory:

codex --ask-for-approval never "Summarize the current instructions."

The guide expects Codex to quote these items before proposing work. For a temporary global change, use ~/.codex/AGENTS.override.md instead of editing the base file, and delete it afterwards to restore the shared guidance.

Example: repository root AGENTS.md and a nested AGENTS.override.md

The guide’s project layering example starts with a root AGENTS.md:

# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

and adds services/payments/AGENTS.override.md for a team with different rules:

# 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.

Start Codex from that directory:

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

Expected, per the guide: the global file first, the repository root AGENTS.md second, the payments override last. The layout looks like this:

AGENTS.md                      # repository expectations
services/
  payments/
    AGENTS.md                  # ignored: an override exists in this directory
    AGENTS.override.md         # payments service rules
    README.md
  search/
    AGENTS.md

Note the comment on services/payments/AGENTS.md: the guide’s own file tree marks it as ignored because an override exists. If you want the base text and a few extras in that directory, copy the shared lines into the override file. The override replaces the sibling; it does not extend it. Codex stops searching once it reaches the current directory, so place overrides as close to the specialized work as possible.

Fallback filenames and the 32 KiB limit

If a repository already uses another filename, list it in ~/.codex/config.toml (guide section):

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

Codex then checks each directory in this order: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Filenames not on the list are ignored for instruction discovery. Restart Codex or run a new command so the configuration loads.

project_doc_max_bytes defaults to 32 KiB. The 65536 above is the guide’s example of a larger limit, not a recommendation. Because Codex stops adding files once the cap is reached, the files that appear last are the ones at risk: these are the nested, most specific ones. If you hit the cap, raise the limit or split guidance across nested directories, as the guide suggests.

To point Codex at a different home directory, such as for a project-specific automation user, set CODEX_HOME:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

Verify what Codex loaded

The guide’s verification steps:

• From a repository root, run codex --ask-for-approval never "Summarize the current instructions.". Codex should echo guidance from global and project files in precedence order.
• Run codex --cd subdir --ask-for-approval never "Show which instruction files are active." to confirm nested overrides replace broader rules.
• To audit loaded files, opt into a plaintext TUI log with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log, or inspect the most recent session-*.jsonl file if you enabled session logging.
• If instructions look stale, restart Codex in the target directory. The chain is rebuilt on every run and at the start of each TUI session, so there is no cache to clear.

Troubleshoot: nothing loads, wrong guidance, truncation

From the guide’s troubleshooting list:

What to change in your setup

• Keep one short global ~/.codex/AGENTS.md for personal preferences, and use AGENTS.override.md there only as a temporary switch.
• Put repository-wide rules in the root AGENTS.md, and put team-specific rules in a nested file close to that code.
• Before adding an AGENTS.override.md, check whether the sibling AGENTS.md has content you still need; the guide marks that sibling as ignored.
• Audit for stray override files in parent directories and in your Codex home when guidance looks wrong.
• Keep critical rules in files that load early, and watch the combined size against project_doc_max_bytes.
• After any change, run the “Summarize the current instructions” check from the directory you work in.