Skip to content
How it learnsFrom coding sessions, reviews, Slack and docs.Only what fitsEach session gets the few rules its task needs.Pull request reviewEvery PR checked against your team’s rules.Keep it trueA gate, conflicts, disputes and stale rules, handled.HandoffsCarry the work to another session or a teammate.SecurityWhat it sends, what it changes and how to leave.
Engineering teamsOne agent or several: what one person learns, every session uses.PR review onlyInstall the GitHub App. Nothing on anyone’s machine.Teams that mix agentsClaude Code, Cursor, Codex and Copilot, the same rules.On your ownYour corrections follow you across repos, machines and agents.Book a call30 minutes with Roei, if you want a hand. Never required.
DocsPricingSign in
Connect your agents →
For teamsOn your ownPR review onlyHow it learnsOnly what fitsPull request reviewKeep it trueSecurityDocsPricingSign inConnect your agents →
Home/Blog

Blog

AGENTS.md, Cursor rules and Copilot instructions

  • AGENTS.md vs CLAUDE.md
  • Sync rules across repos
  • Why Codex ignores it
  • Keep rule files in sync
  • 3,905 files checked
  • Why Copilot ignores it
  • Cursor Team Rules
  • Cursor rules
  • copilot-instructions.md
  • Claude Code and AGENTS.md
  • AGENTS.md research

CLAUDE.md and context engineering

  • Why Claude ignores it
  • Test a CLAUDE.md rule
  • One CLAUDE.md for all projects
  • Context engineering, Claude 5
  • CLAUDE.md length
  • Which rules got used
  • Context rot, stale rules
  • Growing CLAUDE.md
  • Claude Code best practices
  • Karpathy CLAUDE.md
  • Committing CLAUDE.md

Built-in agent memory

  • Agent memory compared
  • Claude Code auto memory
  • GitHub Copilot Memory
  • Make Claude Code remember
  • Claude Tag vs Claude Code
  • Codex memories
  • Cursor memories
  • Memory or documentation?

Team knowledge and shared conventions

  • Claude Code team memory
  • Who owns CLAUDE.md
  • Claude Code second brain
  • Shared memory across agents
  • Stop repeated mistakes
  • Hand off between agents
  • Company brain
  • Slack decisions
  • Memory poisoning
  • Karpathy's LLM wiki
  • ADRs for agents

Skills, hooks and permissions

  • Rules vs skills
  • Claude Code hooks
  • Codex skills
  • Auto mode
  • CLAUDE.md vs skills vs hooks
  • Claude Code skills

AI code review and PR guardrails

  • PR review against AGENTS.md
  • Review comments to rules

Memory tools and alternatives

  • Best company brain tools
  • Unblocked alternatives
  • claude-mem alternatives
  • Supermemory alternatives
  • Mem0 alternatives
  • claude-mem
  • Best MCP memory servers
  • Supermemory Company Brain alternatives

Blog

Why does Codex ignore my AGENTS.md?

Published October 6, 2026 · Updated November 17, 2026

Usually Codex never saw the rule. It reads AGENTS.md from the repository root down to the folder you started in, never below it. It cuts project instructions past 32 KiB, with a warning only since Codex 0.168.0, and it skips projects marked untrusted. When the rule did load, it is text the model weighs, not a setting Codex enforces.

The rest of this note takes each cause, shows how to check for it, and says which fix holds. Loader facts are from the Codex 0.169.0 source and OpenAI's AGENTS.md docs, checked on 17 November 2026. The ones marked tested were run on Codex 0.155.1 in a scratch repository, and the code behind each is unchanged in 0.169.0.

How do I check what Codex loaded?

Before you rewrite a line, find out whether Codex saw it. Three checks, the first two 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.
  • codex -c log_dir=./.codex-log is the audit OpenAI's docs give. It turns on a plaintext log, ./.codex-log/codex-tui.log, where you can check which instruction files the session loaded.

Run them from the folder where you usually start Codex, not from the repository root. That difference is the first cause below. Before a session, the free rule-file checker also says which agents load your file from where it sits.

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 129 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. Codex 0.168.0 and later warn in the session when that happens. Older versions only wrote a line to a log file. 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.

Does Codex read AGENTS.md, and where do global instructions go?

Yes, with no setup. The docs: “Codex reads AGENTS.md files before doing any work.” Global instructions go in ~/.codex/AGENTS.md, or in the folder CODEX_HOME points to if you set it. That file loads first in every project, untrusted ones included, and the project files follow it from the root down. If Codex seems to read a different global file than the one you edited, run echo $CODEX_HOME.

What does AGENTS.override.md do in Codex?

It replaces the AGENTS.md in the same folder. In each folder, and in ~/.codex, Codex checks AGENTS.override.md first, then AGENTS.md, then your fallback names, and takes one file at most. It replaces only its own folder: files above and below still load. The docs suggest it for a temporary change, since deleting the override brings the shared file back. A forgotten one is also why the wrong rules show up.

It is not an ignore file. OpenAI's docs describe no .codexignore. To keep Codex from reading a path, give it deny in a permission profile, a beta feature. The docs' own example is "**/*.env" = "deny"; see permissions.

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, the project's trust level or, since 0.168.0, the byte cap 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 before Codex 0.168.0 you were not 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 on 0.155.1, where the only sign was a line in a log file, project doc exceeds remaining budget; truncating.

Codex 0.168.0 (2026-11-13) added a warning in the session. It names the truncated file and how many of its bytes were loaded, names the first file it skipped, and tells you to trim or raise project_doc_max_bytes. We read this in the source and have not re-run the test on it. Issue #13386, which asked for a visible warning, is still open, since 2026-03-03. The cap applies to project files only, not to the global file.

It is not rare. About 2.6 percent of public AGENTS.md files are over 32 KiB on their own: see how many AGENTS.md files are too big for Codex.

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

CauseHow to checkWhat holds
File is below your working foldercodex debug prompt-input from where you startStart Codex in that folder, or move the rule up
Over the 32 KiB budgetA warning on 0.168.0 and later. Is the last line in the prompt?Raise project_doc_max_bytes, or cut
Project marked untrustedtrust_level for the project in ~/.codex/config.tomlMark it trusted if you trust it
Empty AGENTS.override.mdls -a in each folder on the pathDelete the empty file
Edited mid-session/status, then compare with the fileStart a new thread
Two files contradictRead every file on the path togetherDelete one side
Loaded and still not followedIs the rule in the prompt, and did it lose to the task?A rule file or a hook, not prose

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. A rule Codex skipped anyway can still be caught on the pull request: reviewing pull requests against AGENTS.md compares the tools that do it. 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. Through Codex's own hooks, Harbor serves Codex the decisions your team made, 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.

Related. AGENTS.md vs CLAUDE.md, does Claude Code read AGENTS.md, Codex skills, and Codex memories. The same problem in other agents: why Claude ignores CLAUDE.md, why Cursor ignores rules and why Copilot ignores its instructions.

Questions

Why is Codex not reading my AGENTS.md?

Usually it never loaded. Codex reads one file per folder from the project root down to the folder you started in, never below it, truncates project instructions past 32 KiB, and since 0.150.0 skips project files in a project marked untrusted. Run codex debug prompt-input to see exactly what the model receives.

Does Codex read AGENTS.md files in subdirectories?

Only in the folders between the project root and the folder you started Codex in. A file below that folder is not loaded, even when the agent later edits files there. Start Codex in that folder, or move the rule up.

What is the AGENTS.md size limit in Codex?

32 KiB by default (project_doc_max_bytes), for all project files together, spent from the root down. Past it, Codex truncates the file. Codex 0.168.0 and later warn in the session; older versions say nothing in the terminal. Raise the limit in ~/.codex/config.toml or cut the file.

Does Codex reload AGENTS.md after I edit it?

Project files are re-read only when the working folder, the trust level or the byte cap changes, so start a new thread after editing. The global ~/.codex/AGENTS.md is re-read during the session.

How do I make Codex always follow a rule?

AGENTS.md reaches the model as a user message it weighs, not as enforcement. To stop a command, use a rules file with a prefix_rule whose decision is "forbidden", or a PreToolUse hook that exits 2 or denies.

Does Codex read AGENTS.md, and where do global instructions go?

Yes, with no setup. Global instructions go in ~/.codex/AGENTS.md, or in the folder CODEX_HOME points to. That file loads first in every project, then the project files from the repository root down to the folder you started in.

What does AGENTS.override.md do in Codex?

It replaces the AGENTS.md in the same folder: Codex checks AGENTS.override.md first and takes one file per folder. Files in other folders still load. An empty override hides the AGENTS.md beside it. It is not an ignore file; OpenAI's docs describe no .codexignore, and reads are blocked with deny in a permission profile.

More on AGENTS.md, Cursor rules and Copilot instructions

  • AGENTS.md vs CLAUDE.md: which tools read which
  • How to sync AGENTS.md and CLAUDE.md across all your repos
  • How to keep CLAUDE.md, AGENTS.md and .cursorrules in sync
  • We checked 3,905 CLAUDE.md and AGENTS.md files on GitHub

Check your AGENTS.md or CLAUDE.md for free →

Your team’s rules, in every agent, checked on every PR.

Harbor is shared memory for your team’s Claude Code, Cursor, Codex and Copilot. Free for you and one teammate. No card. No end date.

Start free →

Product

  • How it learns
  • Only what fits
  • Pull request review
  • Keep it true
  • Handoffs
  • The result
  • Security
  • For coding agents
  • Pricing

Developers

  • Docs
  • Quickstart
  • Install
  • CLI
  • MCP server
  • Served and cited
  • Rule-file checker
  • Blog

Guides

  • Why Claude ignores CLAUDE.md
  • AGENTS.md vs CLAUDE.md
  • Share Claude Code memory with a team
  • Why Codex ignores AGENTS.md
  • Why Cursor ignores rules
  • Copilot instructions vs AGENTS.md
  • Shared memory across agents
  • Copilot Memory and Dreaming

Compare

  • All comparisons
  • vs Mem0
  • vs Zep
  • vs Unblocked
  • vs ByteRover
  • vs Cognee
  • vs Hindsight
  • vs OpenViking
  • vs Supermemory
  • vs Glen
  • vs MemPalace
  • vs Sentra
  • vs Trail-code

Company

  • Questions
  • Contact
  • X
  • LinkedIn
  • Privacy Policy
  • Terms of Service
  • Data Processing Agreement
  • Refund Policy
© 2026 HarborConnect your agents