Why does Codex ignore my AGENTS.md?

How do I check what Codex loaded?

Before you rewrite a line, find out whether Codex saw it. Two checks, from quick to exact:

• /status in a session has an Agents.md row listing the files it loaded, or <none>. It can lag: issue #37704 (open) shows <none> after /init has just written the file.
• codex debug prompt-input "hi" prints, as JSON, exactly what the model would receive from the folder you run it in. Each loaded file appears under a heading # AGENTS.md instructions for <folder>. If your rule is not in that output, the model never saw it.

Run the second one from the folder where you usually start Codex, not from the repository root. That difference is the first cause below.

Why is Codex not loading my AGENTS.md?

• It is below the folder you started in. Codex finds the project root (the nearest .git), then reads one file per folder from the root down to your working directory. The docs: “Codex stops searching once it reaches your current directory.” Start at the root, and Codex does not load services/payments/AGENTS.md (tested), not even later, when the agent edits files there; the agent would have to open the file itself. Issue #12115, asking for nested files to load on demand, has 119 reactions and has been open since 2026-02-18.
• It was cut off. All project files share one 32 KiB budget, spent from the root down. The file that crosses it is truncated mid-text and the rest are dropped, with a line in a log file as the only sign. Details in the size section below.
• The project is marked untrusted. Since Codex 0.150.0 (2026-08-26), “Untrusted projects no longer supply project-level AGENTS.md instructions”. It takes an explicit trust_level = "untrusted" entry for the project in ~/.codex/config.toml; a project with no entry still loads its files (tested both ways). Your global ~/.codex/AGENTS.md still loads, and nothing tells you the project files were skipped.
• An empty override sits next to it. In each folder Codex takes the first of AGENTS.override.md and AGENTS.md that exists, then drops it if it is empty. So an empty AGENTS.override.md hides the AGENTS.md beside it (tested). The docs only say empty files are ignored.
• It has another name. CLAUDE.md or agent.md are read only if you list them in project_doc_fallback_filenames, as a top-level key in the config. Placed under a table, it does nothing (#22454).
• The root is not where you think. With no .git above you, Codex checks only the current folder, and it never reads above the root (#28903). Inside a git submodule, the submodule is the root (#30789). In a desktop project with several folders, only the primary one is searched.

Is AGENTS.md enforced in Codex?

No. Codex sends the files to the model as a user message (tested), and their order is the only precedence there is. The docs say files closer to your folder “override earlier guidance because they appear later in the combined prompt.” That is a position in a prompt, not a rule engine. When a user reported in #8601 that Codex ignored a file it had loaded, an OpenAI engineer answered, “What you're seeing here is model behavior.”

OpenAI's own customization guide says the same thing in its own way: pair AGENTS.md “with infrastructure that enforces those rules: pre-commit hooks, linters, and type checkers”.

Does Codex reread AGENTS.md during a session?

The global file, yes. Project files, only when the working folder or the project's trust level changes. Edit AGENTS.md mid-session in the same folder and the session keeps the old version. OpenAI's advice, from an engineer on #16403: “If you decide to modify AGENTS.md, you should create a new thread.”

Compaction does not drop it. After /compact, Codex puts its initial context, instructions included, back in on the next turn. So when a rule held early and slipped later, check whether it is still in the prompt before assuming Codex lost it.

What happens when two AGENTS.md files disagree?

Codex concatenates them, global first, then the root, then each folder down to yours. Nothing is merged or removed, so both sides of a contradiction reach the model, and the later one has the better position. If your root file says webhook handlers acknowledge with a 200 and enqueue, and an old services/payments/AGENTS.md still says to process inline, delete the old line. A third rule explaining which one wins is one more thing to weigh.

Is my AGENTS.md too long for Codex?

Over 32 KiB of project instructions, yes, and you will not be told. The default project_doc_max_bytes is 32 KiB for all project files together, spent from the root down. We tested it with a 33.6 KB root file and a short services/AGENTS.md: Codex kept the start of the root file, lost its last line, and dropped the services file entirely. Nothing appeared in the terminal. The source logs one warning, project doc exceeds remaining budget; truncating, and only to a log file. Issue #13386 asks for a visible warning and has been open since 2026-03-03.

Two fixes. Raise the cap in ~/.codex/config.toml, which brought both files back in our test:

project_doc_max_bytes = 65536

Or cut. OpenAI's best-practices guide says “A short, accurate AGENTS.md is more useful than a long file full of vague rules,” and the prompt behind /init asks for 200 to 400 words. Note that the docs disagree with themselves here: one page calls the cap per file, another the combined total. The code counts the total.

Causes, checks, and fixes

How do I make Codex always follow a rule?

Move it out of the prompt. Codex has two places a rule can actually stop a command. The first is rules files, which are experimental. A prefix_rule with decision = "forbidden" blocks a matching command without asking:

# ~/.codex/rules/default.rules
prefix_rule(
    pattern = ["git", "push", ["--force", "-f"]],
    decision = "forbidden",
    justification = "Force push is off in this repo. Open a PR instead.",
    match = ["git push --force origin main", "git push -f"],
    not_match = ["git push origin main"],
)

codex execpolicy check tests a command against it before you rely on it. It matches a prefix, so git push origin main --force slips past this one. Project rules in .codex/rules/ load only once the project is explicitly trusted. See Codex rules.

The second is hooks. A PreToolUse hook sees the whole command and can refuse it by exiting 2 or returning permissionDecision: "deny". Codex runs a hook only after you review and trust it. How hooks compare across Codex, Claude Code and Cursor is in Claude Code hooks.

Everything else stays prose, and prose works best short, concrete and current: “Run pnpm test before committing”, not “test your changes”, in the folder it is about, and deleted the day it stops being true. The Claude Code side of the same problem is in why Claude ignores CLAUDE.md.

Where Harbor fits

Several causes above come from one design: a file per folder, read once, under a byte cap, where the folder you happened to start in decides what the agent knows. Harbor serves Codex the decisions your team approved through Codex's own hooks, picking the ones that apply to the task, so a rule about payments webhooks reaches a session started at the root. Codex will not run a hook it has not trusted, so harbor init records that trust and harbor doctor says when a hook is installed but not trusted. Each rule shows how often it was served and how often an answer cited it. A cite is evidence that a rule was used, not proof that it was obeyed; the method is in served vs cited.