Global AGENTS.md does not appear to be loaded when a repo AGENTS.md is present

Resolved 💬 4 comments Opened Apr 16, 2026 by iamhectorlopez Closed Apr 30, 2026
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Summary

A session honored the repository-local AGENTS.md but did not appear to load or apply the global ~/.codex/AGENTS.md.

Why this seems wrong

The global file contained cross-project defaults, including commit policy guidance. During the session, the agent followed the repo-local file and later stated that it had not checked a global AGENTS.md and only knew about the repo-specific file that had been surfaced in context.

That suggests either:

  • global AGENTS.md is not being auto-loaded in some session types, or
  • global and repo AGENTS.md are not being merged as expected, or
  • the load behavior is correct but not visible enough to the agent/user.

Repro

  1. Put cross-project instructions in ~/.codex/AGENTS.md.
  2. Open a repository that also has its own AGENTS.md.
  3. Start a Codex session in that repo.
  4. Ask the agent to perform a task where the global policy should materially affect behavior.
  5. Ask the agent which AGENTS.md files were actually loaded.

Observed

  • The repo-local AGENTS.md was active.
  • The global ~/.codex/AGENTS.md did not appear to be active.
  • The agent reported that it only had the repo AGENTS.md in context and had not inspected a global one.

Expected

One of the following should be true:

  • The global ~/.codex/AGENTS.md is automatically loaded and merged with the repo AGENTS.md.
  • If global loading is intentionally disabled for a given session type, that should be clearly documented and ideally visible in-session.
  • The agent should be able to distinguish between "global instructions are loaded" and "a global file exists on disk but is not active in this session."

Impact

Users may assume their cross-project defaults are active when they are not, which can change commit strategy, tool behavior, and other workflow expectations in subtle ways.

View original on GitHub ↗

4 Comments

github-actions[bot] contributor · 4 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #17111

Powered by Codex Action

etraut-openai contributor · 4 months ago

Which Codex product are you using, and what's the version?

It's unlikely that Codex is failing to include the global AGENTS.md, at least in the general case. We would have seen this internally and heard from many customers if this were the case. You can verify yourself by looking at the rollout file, which will be found under ~/.codex/sessions. Ask Codex to look for the thread ID if you can't find it manually. If you open the jsonl rollout file, you'll see what details were sent to the model — including your AGENT.md contents.

If you need help diagnosing, please use /feedback to upload session details and post thread ID here.

runfence · 3 months ago

I used this feature and it worked a few weeks ago, now it stopped working and I have same issue. Why it's closed?

etraut-openai contributor · 3 months ago

@runfence, if you are seeing a problem that you can repro, please open a new issue using /feedback so we can look at your session details. Alternatively, you could ask codex to help you diagnose the problem you're seeing.