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

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!

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.

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.

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.

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.

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?

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.

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.

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.

Neither ~/.codex/AGENTS.md and/or ~/.codex/AGENTS.override.md works for me. New session and running /status shows a blank Agents.md line.

I created a prompt which I load into each new session, not ideal but an easy work-around:

~/.codex/prompts 
❯ bat load-agents.md 
---
description: Load global AGENTS.md into this session
---
Read and follow the contents of `~/.codex/AGENTS.md` as binding instructions for this session.
If available, include the full contents verbatim in context.

Looks like there is a clear bug/diff between codex and their documentation.

@o6uoq, how do you know that AGENTS.md isn't being loaded? The /status command won't show your global AGENTS.md, only the project-level AGENTS.md. You can look in your session history (found at ~/.codex/sessions/YY/MM/DD/THREAD.jsonl) and examine the instructions that are sent to the model. Do you see the contents of your AGENTS files in the session history? Another thing to check: Do you have the CODEX_HOME env variable defined and pointing to a location other than ~/.codex/?

@etraut-openai this is really helpful information, thank you. TIL /status does not show the global agents being loaded. In the codex session, I can see my global AGENTS.md being loaded. However, there is a nested gist in my global AGENTS.md which codex does not follow unless I explicitly force it via my /load-prompts command. Also, while I have your attention, what is the nuance/difference between ~/.codex/AGENTS.md and ~/.codex/AGENTS.override.md ? ..and is there anyway to force codex on load in a new session to follow links in a global AGENTS.md ?

I have similar problem and project-level AGENTS.md does not work. The agent seems not follow

@hieuminh65, if you suspect a bug, please use the /feedback slash command top upload your logs and session details, open a new issue, and include your thread ID. Also, see my above comment for tips on how you can confirm that your AGENTS file is included in your session history.

This was written by ChatGPT itself after i asked Codex to verify if it read AGENTS.md / AGENTS.override.md:

Codex CLI does not reliably load global personal instructions from ~/.codex on Windows.

Expected:

• Per docs, Codex should load ~/.codex/AGENTS.override.md if present, otherwise ~/.codex/AGENTS.md.

Observed:

• CODEX_HOME is default.
• ~/.codex/config.toml is present and normal.
• ~/.codex/AGENTS.override.md exists.
• A direct self-test inside Codex reports that no personal instruction file was loaded, and only repo-local AGENTS.md was seen.

Repro:
codex --ask-for-approval never --sandbox danger-full-access exec --cd <repo> "Summarize the highest-priority personal instruction file you loaded, if any, in 3 bullets."

Impact:

• Global personal guidance cannot be trusted as enforced.
• Users must duplicate critical rules in repo-local AGENTS.md.

Reference: https://developers.openai.com/codex/guides/agents-md/

This is still a problem. Codex just flat ignores any overarching guidance document, on Windows at least.

I kind of given up on trying to figure this out and instead just always start codex cli in same folder where my top-level/big-picture AGENTS.md lives, then i link everything from there (or codex learns itself). I never go into another folder in shell now, instead just doing cd <my proj> and <instructions in codex, but often even cd is not needed, it can figure it all on its own. Oh i run --yolo mode too.

That sounds horrible.
Please @codex fix this properly! This is not sane!