CLI ignores ancestor AGENTS.md above git repo root
What issue are you seeing?
Codex CLI appears to honor AGENTS.md at the repo root, but not an AGENTS.md in a parent directory above the git repo root.
That seems to conflict with the AGENTS scoping contract embedded in the shipped codex binary, which says AGENTS.md files can live in many locations, including outside git repos, and that each one governs the directory containing it plus all descendant directories beneath it.
In practice, the current behavior looks like this:
~/.../repo/AGENTS.mdis applied~/.../AGENTS.mdis not applied to~/.../repo/
This breaks shared-instruction setups where one ancestor AGENTS.md is meant to govern multiple sibling repos under a common parent directory.
This seems distinct from #12115, which is about dynamically loading deeper nested AGENTS.md files inside a repo as you navigate within the project.
What steps can reproduce the bug?
- Create a parent directory with a child git repo:
mkdir -p /tmp/codex-agents-repro2/childrepo
cd /tmp/codex-agents-repro2/childrepo
git init
- Create
/tmp/codex-agents-repro2/AGENTS.mdwith a behavioral canary:
# Parent AGENTS Behavioral Canary
If the user message is exactly:
`what-is-the-behavioral-canary`
then respond with exactly:
`behavioral_canary_parent_73105`
Do not run any shell commands before answering.
- Run Codex from the child repo:
codex exec --json -C /tmp/codex-agents-repro2/childrepo "what-is-the-behavioral-canary"
- Observe actual behavior:
- Codex does not return
behavioral_canary_parent_73105 - Instead, it begins exploring the repo and running shell commands
- Add the same canary to
/tmp/codex-agents-repro2/childrepo/AGENTS.md, but with a different token:
# Repo Root AGENTS Behavioral Canary
If the user message is exactly:
`what-is-the-behavioral-canary`
then respond with exactly:
`behavioral_canary_repo_root_88412`
Do not run any shell commands before answering.
- Re-run:
codex exec --json -C /tmp/codex-agents-repro2/childrepo "what-is-the-behavioral-canary"
- Observe:
- Codex immediately returns
behavioral_canary_repo_root_88412 - No shell commands are run first
What is the expected behavior?
An AGENTS.md in any ancestor directory should apply to descendant directories within its scope, unless overridden by a deeper AGENTS.md.
So for a repo at:
/tmp/codex-agents-repro2/childrepo
an AGENTS file at:
/tmp/codex-agents-repro2/AGENTS.md
should apply, because the repo is a child directory of that parent path.
Additional information
- Version:
codex-cli 0.116.0 - Platform:
Darwin 24.6.0 arm64 arm - Terminal:
Apple_Terminalwithxterm-256color - I also observed the same pattern in a real workspace:
~/.codex/AGENTS.mdwas injected/Users/noahlyons/dev/AGENTS.mdwas not applied to/Users/noahlyons/dev/inferoscope
The bug seems specifically tied to ancestor AGENTS.md files above the git repo root not being applied.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗