CLI fails to read AGENTS.md from the global location by default

[smitchell-kareo]

What version of Codex is running?

codex-cli 0.77.0

What subscription do you have?

Enterprise

Which model were you using?

gpt-5.2-codex xhigh

What platform is your computer?

Darwin 24.6.0 arm64 arm

What issue are you seeing?

Codex CLI fails to load the AGENTS.md from the global location (~/.codex/AGENTS.md) despite it being listed as a valid location here: https://developers.openai.com/codex/guides/agents-md

Codex CLI always fails to load it and I'm forced to spend time telling it where to find it in every new session. It always says:

Step 2 (explanation):

• I defaulted to searching only the workspace because I assumed the instruction file would be colocated with the repo and did not expand to the documented global locations unless prompted; that assumption was wrong given your setup.
• Each new session starts without memory of prior paths, so if I don’t immediately check the known global location, I repeat the same mistake.

Asking it how to prevent this in new session, it admits it can't

Step 2 (root cause):

• I defaulted to a repo-local search because I didn’t include the documented global location in my initial search order. That’s on me; your setup is valid.

Progress update:

• Step 2: completed.

Step 3 (durable fix for new sessions):
The only solution that does not depend on me “remembering” in each new session is to make the instructions discoverable from the repo itself. These are the reliable options:

1. Create a symlink AGENTS.md in the repo root pointing to /Users//.codex/AGENTS.md (single source of truth, no duplication).
2. Copy /Users//.codex/AGENTS.md into the repo root as AGENTS.md (works everywhere, but duplicates content).
3. I can follow a strict search order that checks the global path first every session, but that still relies on me doing it correctly each time and does not enforce discovery at the repo level.

What steps can reproduce the bug?

1. Add an AGENTS.md file to ~/.codex
2. Launch a new codex CLI instance some where (eg: ~/foo) that doesn't contain an AGENTS.md file
3. Require it load AGENTS.md to process requests
4. Observe it failing to discover the file

What is the expected behavior?

It should load ~/.codex/AGENTS.md when there is no local AGENTS.md defined as it's a valid search location according to documentation.

Additional information

No response

[etraut-openai]

Thanks for the bug report. Could you repro with a simple prompt? If so, please use the /feedback slash command to upload your logs and session and post the thread ID here. Thanks!

[smitchell-kareo]

Done: 019b95e2-fe57-7032-8879-0f54a40c413b

I have my AGENTS.md located in the global fallback location:

$ ll ~/.codex
total 4968
lrwxr-xr-x   1 <username>  staff    48B Dec 16 12:51 AGENTS.md -> /Users/<username>/.codex/playbooks/AGENTS.md

The prompt:

$ codex
╭────────────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.78.0)                          │
│                                                    │
│ model:     gpt-5.2-codex medium   /model to change │
│ directory: ~/tmp/session                           │
╰────────────────────────────────────────────────────╯

  Tip: Switch models or reasoning effort quickly with /model.


› propose how to upgrade this project to use spring-boot 3.x


• Explored
  └ List ls
    Search rg --files -g AGENTS.md

─ Worked for 13s ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

• I’m about to determine how to upgrade this project to Spring Boot 3.x based only on the current command and its instruction file, but I can’t find AGENTS.md in /Users/<username>/tmp/session. Please provide the path to AGENTS.md (or paste its contents) and the project root directory so I can proceed.

In another session I asked it to tell me what the lcoation of the AGENTS.md file it was using and asked to confirm if it was using one or not:

• Reset done. Task understood: confirm whether I am using any AGENTS.md for /Users/<username>/dev.8/session-service.

  Plan summary: re-check for AGENTS.md, then answer based on the verified search.

  Progress: rg --files -g 'AGENTS.md' and find . -name AGENTS.md -print returned no results.

  Answer: Correct—there is no AGENTS.md in this repo, so I am not using any.

Thanks.

[etraut-openai]

Thanks for uploading the session details. It appears that Codex is working correctly.

The model won't know the location of the AGENTS.md that it's using. It's injected by the harness, and the path used by the harness is not provided. So I think this is just a misunderstanding based on the fact that you asked the model for information it doesn't have access to.

For details about how Codex handles AGENTS.md, refer to this documentation.

You can also verify that the Codex harness is adding the correct AGENTS.md by looking at the session details in your editor. You'll find the session information in ~/.codex/sesssions/<year>/<month>/<day>/<session-id>.jsonl.

[smitchell-kareo]

How is it working when I'm following the documentation that you linked, specifically:

Global scope: In your Codex home directory (defaults to ~/.codex, unless you set CODEX_HOME), Codex reads AGENTS.override.md if it exists. Otherwise, Codex reads AGENTS.md. Codex uses only the first non-empty file at this level.

I have a file at that location.

[smitchell-kareo]

Also if that's specifically related to me asking what AGENTS.md file it was using, that was just another example. The real test was asking it to perform an action in a new session and it saying it couldn't find the AGENTS.md and failing, despite me having that file in a proper location according to the documentation. From above:

$ codex
╭────────────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.78.0)                          │
│                                                    │
│ model:     gpt-5.2-codex medium   /model to change │
│ directory: ~/tmp/session                           │
╰────────────────────────────────────────────────────╯

  Tip: Switch models or reasoning effort quickly with /model.


› propose how to upgrade this project to use spring-boot 3.x


• Explored
  └ List ls
    Search rg --files -g AGENTS.md

─ Worked for 13s ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

• I’m about to determine how to upgrade this project to Spring Boot 3.x based only on the current command and its instruction file, but I can’t find AGENTS.md in /Users/<username>/tmp/session. Please provide the path to AGENTS.md (or paste its contents) and the project root directory so I can proceed.

[etraut-openai]

OK, please try these steps:

1. Launch Codex with a global AGENTS.md file with some content that you can later search for. Use a clean project with no project-level AGENTS.md file.
2. Issue a prompt to start a session.
3. Quick Codex.
4. Look in the ~/.codex/session directory for the session that was just created. Open the .jsonl file in an editor.

Do you see the contents of your global AGENTS.md file in this .jsonl file?

[smitchell-kareo]

Long Winded Details

Ok that worked and since it worked I dug further and found the root issue which I think should work but clearly doesn't. Codex isn't able to find the AGENTS.md during a session if it's been told to re-read its instructions as an enforcement/corrective measure.

Working with codex I kept running into issues where it performed actions that violated rules/guidance/instructions in the AGENTS.md and when I asked how to make sure it followed those instructions it suggested adding an enforcement mechanisms such as:

## Added Memories
- For every task, I must first re-read all provided instruction files (e.g., CLAUDE.md, task-specific markdown). Then, I must state a step-by-step plan based only on those instructions before I begin execution.
- Exception: The mandatory instruction-file re-read required above is exempt from the plan requirement; no other tool calls may occur before the plan is stated.

## The Self-Correction and Verification Protocol

To ensure I follow all instructions without missing steps, I will adopt the following internal protocol:

1.  **Comprehensive Plan Generation:** Before taking any action, I will create a detailed, step-by-step execution plan based *only* on the provided instructions. This plan will be logged internally for my own reference.
2.  **Public Plan Summary:** I will present a concise summary of this plan to you so you know what I intend to do, without requiring you to approve a detailed checklist.
3.  **Sequential Execution with Self-Verification:** I will execute the plan step-by-step. After each step, I will internally verify that the action was completed correctly and successfully before proceeding to the next. This includes:
    *   **Rule Application Check:** After modifying a file based on a set of rules, I will re-read the file and the rules to ensure every single rule was applied. For example, after a `pom.xml` refactoring, I will explicitly re-check for any remaining third-party dependencies that should have been removed.
    *   **File-Specific Logic:** I will pay closer attention to instructions that differentiate between file types (e.g., root `pom.xml` vs. module `pom.xml`) and explicitly verify that I have followed the correct logic for each.
4.  **Final Verification:** Upon completing all steps, I will perform a final, comprehensive verification against the original instructions to guarantee that all requirements have been met and no steps were missed.

I had codex add those suggestions to my main AGENTS.md and removing the above blocks from my AGENTS.md allows it work. However adding those blocks to my simple AGENTS.md of:

 - Favorite snack: almonds

doesn't cause it to break but it does illustrate that having instructions telling codex to re-read the instructions file fails to find it in the global location. There must be some other instructions in my larger AGENTS.md that cause it to stop/fail if it wasn't able to perform the re-read. So in my simple example where I added those Memories and Self-Correction blocks it does answer the question but shows that it failed to re-read the instructions file:

$ codex
...
› What is my favorite snack?

• Explored
  └ List ls
    Search rg --files -g AGENTS.md
    Read AGENTS.md

─ Worked for 42s • Re-read the provided instruction content in your message; AGENTS.md was not found at /Users/<username>/tmp/codex/AGENTS.md.

  Plan:

  1. Use the provided instructions to identify the stored preference.
  2. Answer the question directly.

  Your favorite snack is almonds.

I can confirm I see the contents of the AGENTS.md in the *.jsonl session file.

tl;dr

• The global location ~/.codex/AGENTS.md is loaded on startup
• Within a codex session it cannot find the ~/.codex/AGENTS.md to re-read it
• codex suggested and added enforcement mechanisms to require re-reading the AGENTS.md before taking action, due to it ignoring those instructions during a session, fail until it's told where to find the AGENTS.md file in a valid (documented) location.

[etraut-openai]

Is it possible that this is related to compaction? Are your sessions long enough to consume most of the context window, which would then cause auto-compaction to occur? We've heard reports of compaction causing some of the details in the original AGENTS.md to be lost.

[smitchell-kareo]

It could be related to compaction but I'm also fairly certain (not 100% since it was before all the enforcement instructions were added) that it was before compaction.

We just kept running into issues where codex made assumptions that went counter to the instructions, so it suggested adding these, and I'm fairly certain some of them were in new/clean sessions. Things like always assuming we were on Java 17+ and Spring Boot 3.x when in a legacy service that was Java 8 & Spring Boot 2.x. We have details in the AGENTS.md describing our mixed environment and the need to determine Java/SB version before performing work and it usually would implement code that wasn't compatible with that service.

But again, I can't be 100% on all the issues and if compaction occurred or not since this was months ago (6+?) and I don't recall specifics.