CLI ignores ancestor AGENTS.md above git repo root

Resolved 💬 1 comment Opened Mar 24, 2026 by lyonsno Closed Mar 24, 2026

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.md is applied
  • ~/.../AGENTS.md is 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?

  1. Create a parent directory with a child git repo:
mkdir -p /tmp/codex-agents-repro2/childrepo
cd /tmp/codex-agents-repro2/childrepo
git init
  1. Create /tmp/codex-agents-repro2/AGENTS.md with 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.
  1. Run Codex from the child repo:
codex exec --json -C /tmp/codex-agents-repro2/childrepo "what-is-the-behavioral-canary"
  1. Observe actual behavior:
  • Codex does not return behavioral_canary_parent_73105
  • Instead, it begins exploring the repo and running shell commands
  1. 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.
  1. Re-run:
codex exec --json -C /tmp/codex-agents-repro2/childrepo "what-is-the-behavioral-canary"
  1. 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_Terminal with xterm-256color
  • I also observed the same pattern in a real workspace:
  • ~/.codex/AGENTS.md was injected
  • /Users/noahlyons/dev/AGENTS.md was 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.

View original on GitHub ↗

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