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:

  1. as the global $CODEX_HOME/AGENTS.md;
  2. 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 --profile selection.
  • Project config cannot select a profile.
  • A global project_doc_max_bytes=0 would incorrectly disable project instructions in every repository.
  • A conditional -c project_doc_max_bytes=0 suppresses 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.md as separate layers in /status, but does not deduplicate identical paths.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗