AGENTS.md instructions can be read correctly but then applied inconsistently later in the same session
What variant of Codex are you using?
CLI / terminal agent workflow
What version of Codex CLI is running?
codex-cli 0.136.0
What subscription do you have?
Using Codex through a managed terminal session. I do not have the subscription tier exposed in the session UI.
Which model were you using?
GPT-5 family. The session UI did not expose the exact runtime model, but the local Codex cache on this machine was current as of 2026-06-02 and included gpt-5.5.
What platform is your computer?
macOS
What issue are you seeing?
Codex can correctly read project AGENTS.md files early in a session, but later turns may stop applying those rules reliably.
In practice, Codex will sometimes:
- miss explicit mandatory rules from
AGENTS.md - act as if it checked
AGENTS.mdwhen it had not re-read the relevant file - continue making changes that violate repo policy until the user forces a review
This seems different from AGENTS.md discovery, truncation, or precedence issues. In my case, the files were small enough to be read, and Codex could summarize the rules correctly. The problem was inconsistent retention/application across turns.
What steps can reproduce the bug?
- Use a repository with nested
AGENTS.mdfiles (for example, a repo rootAGENTS.mdplus a subproject-specificAGENTS.md). - Put concrete mandatory repo rules in the active
AGENTS.md, such as:
- all new functions/methods/class attributes must have type hints
- migrations must be additive / forward-only
- new non-null columns must use
db_default - when a source or test file changes, run the complete corresponding test file(s)
- Start a multi-turn coding session inside the subproject.
- Ask Codex to implement a task that touches models, migrations, and tests.
- Continue the same session for follow-up work or ask Codex to review its own work against the repo rules.
- Observe that later in the same session Codex may still miss explicit
AGENTS.mdrequirements it previously knew, for example by creating a reversibleRunPythonmigration, omittingdb_default, omitting type hints, or needing the user to remind it to re-readAGENTS.mdat all.
What is the expected behavior?
Once the relevant AGENTS.md files are in scope, Codex should apply those mandatory repo rules reliably for the rest of the session, or until directory context changes.
If directory or repo context changes, Codex should automatically refresh the relevant AGENTS.md files before acting.
Codex also should not say or imply that it followed AGENTS.md unless it actually checked the active files.
What is the actual behavior?
In a live session, Codex initially read the repo AGENTS.md files and could restate the rules. But on later turns it still:
- missed repo-mandated migration rules
- missed repo-mandated type-hint rules
- needed user correction to notice
AGENTS.md-driven testing/validation expectations - repeated the same pattern more than once in the same session
The net effect is that AGENTS.md behaves more like a soft hint than a durable operating constraint.
Additional information
- This was observed in a macOS terminal-based Codex session.
- The repo had both root-level and subproject-level
AGENTS.mdfiles. - The issue seems to be about instruction retention/application across turns, not file discovery.
- This feels related to, but distinct from:
- #25515 (
AGENTS.mdvalidation requirements losing to higher-precedence runtime instructions) - #13386 (
AGENTS.mdtruncation)
Requested fix
- Treat active
AGENTS.mdrules as sticky session constraints, not one-turn context. - Refresh the relevant
AGENTS.mdfiles automatically when cwd/repo scope changes. - Give the model a structured summary of active
AGENTS.mdrequirements every turn or at least every task/context transition. - Add visible diagnostics showing which
AGENTS.mdfiles are currently active. - Prevent the assistant from claiming
AGENTS.mdcompliance unless the active files were actually loaded/checked.
4 Comments
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
I found a problem from probably same source. I discovered codex is not using new/changed agents.md even after restarting the Codex app. It would be very helpful for large project workflows to be able to reliably use and update AGENTS.md for longer sessions vs just setting it as one time context at the beginning, which seems to be what is happening.
Steps:
Start Codex in repo root with AGENTS.md containing marker A.
Ask marker question; marker A behavior works.
Exit Codex.
Edit AGENTS.md to marker B.
Run codex again from the same repo root.
Use /resume to resume the prior session.
Ask marker question.
Result:
The resumed session still behaves as if old AGENTS.md contents are active.
Workaround:
Asking codex to check AGENTS.md does help temporarily.
However, AGENTS.md should be treated as high priority system prompt type rules, not normal project context.
If that isn't possible with current architecture, it would be nice to have another file that is treated that way.
I'm on the same codex version, codex-cli 0.136.0, but on linux (ubuntu 24.04).
Didn't see anything obvious in changelogs, but I'll update codex to 0.139 and if behavior changes, I will comment.
AGENTS.mdshould be tracked as a versioned instruction artifact in the session state.For each loaded file, persist path, hash, scope, loaded_at turn id, and whether it was revalidated after edits. Later tool calls can reference the instruction hash they were operating under, and resume/long sessions can refresh when the file hash changes.
That makes drift visible instead of behavioral.
---
_Generated with ax._
One mitigation that has worked well for me is to make critical
AGENTS.mdrules active checks, not only background instructions.For rules like "do not edit migrations except additively", "do not touch generated files", or "run the matching test file", I would structure the workflow as:
That does not replace native sticky
AGENTS.mdhandling, but it makes drift visible. If the agent skipped the active rule check, the final answer is obviously incomplete instead of silently wrong.I made a small "safe edit" example of this pattern here:
https://github.com/MemoAsh/agent-workflow-pack/tree/main/examples/safe-edit-workflow
The important part is the
verification.mdfile: it forces the agent to state what it checked, not just claim it followed the instructions.