Deduplicate AGENTS.md when CODEX_HOME is also the project root
Open 💬 1 comment Opened Jul 19, 2026 by grig2277
Summary
When CODEX_HOME is also the project root and current working directory, Codex loads the same canonical AGENTS.md file twice:
- as the global
$CODEX_HOME/AGENTS.md; - again through project instruction discovery.
The second copy is wrapped as --- project-doc ---.
Environment
- codex-cli 0.144.6
- Linux x86_64
- zsh
Minimal reproduction
tmp="$(mktemp -d)"
export CODEX_HOME="$tmp"
cd "$tmp"
git init -q
printf '# CANONICAL_DEDUPE_MARKER\n' > AGENTS.md
codex debug prompt-input DEDUPE_CHECK |
jq -c '[.. | strings] as $strings |
{marker_count:([$strings[] | scan("# CANONICAL_DEDUPE_MARKER")]|length),
project_doc_wrappers:([$strings[] | scan("--- project-doc ---")]|length)}'
Observed: the marker appears twice and one project-doc wrapper is present.
The same behavior was measured in a real Codex home repository:
{"agents_headers":2,"project_doc_wrappers":1,"marker_count":1,"total_string_bytes":45422}
With the one-run override -c project_doc_max_bytes=0:
{"agents_headers":1,"project_doc_wrappers":0,"marker_count":1,"total_string_bytes":31123}
Expected behavior
Instruction assembly should deduplicate identical canonical source paths across global and project discovery. If $CODEX_HOME/AGENTS.md was already loaded globally, project discovery should not append the same file again.
Impact
- duplicate durable instructions in every turn;
- unnecessary input-token consumption;
- additional prompt processing latency;
- misleading provenance because one physical file appears as two logical instruction layers.
Configuration limitations
- Named profiles require explicit
--profileselection. - Project config cannot select a profile.
- A global
project_doc_max_bytes=0would incorrectly disable project instructions in every repository. - A conditional
-c project_doc_max_bytes=0suppresses the duplicate locally, but also suppresses the entire project instruction chain and is only a workaround.
Related work
- #23416 tracks incorrect instruction provenance when both global and project instructions are loaded.
- #17091 reports global and project
AGENTS.mdas separate layers in/status, but does not deduplicate identical paths.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗