Fix Codex Nested AGENTS.md Not Loading

If Codex follows the repository-root AGENTS.md but misses instructions in a nested package, start a new Codex session from that package with codex --cd path/to/package. Codex builds its instruction chain once per run, walking from the project root down to the starting working directory. It does not automatically load every descendant AGENTS.md just because a later task touches that folder.

For tasks that span several packages, keep the root file short and explicitly tell Codex which nested instruction file to read before planning or editing in each subtree. Then verify the active scope in a new session. Do not assume an answer such as “I have the root file loaded” proves what the runtime actually assembled.

Confirm the Failure Before Changing Anything

The same symptom can come from four different boundaries:

• Codex started at the repository root, so descendant instructions were outside the startup chain.

• An unexpected .git entry made a nested directory look like the project root.

• AGENTS.override.md replaced AGENTS.md at one directory level.

• The combined instruction chain reached the default 32 KiB project_doc_max_bytes limit.

Prerequisites

• Run these checks in the repository where the problem occurs.

• Know the subdirectory whose rules appear to be missing.

• Save or commit work you care about before changing any repository marker or instruction file.

• Use a current Codex CLI and start a new session after every scope or configuration change.

First record the root and current directory:

git rev-parse --show-toplevel
pwd

Expected result: the Git root is the repository you intended to open, and pwd shows the directory from which Codex was launched.

Now list candidate instruction files without modifying them:

repo_root="$(git rev-parse --show-toplevel)"

find "$repo_root" -type f \
  \( -name AGENTS.md -o -name AGENTS.override.md \) \
  -print

Suppose the result includes:

/work/acme/AGENTS.md
/work/acme/services/payments/AGENTS.md

If Codex started in /work/acme, only the root file is on the root-to-working-directory chain. The payments file is a descendant, so it will not become active later just because Codex opens services/payments/handler.ts.

Fix 1: Start Codex in the Target Subtree

Launch a fresh process with the package as the working directory:

codex --cd services/payments \
  --ask-for-approval never \
  "List the instruction sources you loaded, in precedence order."

Expected result: Codex reports the global guidance first, then the repository-root AGENTS.md, then the payments instruction file. A local AGENTS.override.md appears instead of the same directory's AGENTS.md when both exist.

Use this fix when the task is contained in one service or package. It gives Codex the narrowest relevant scope without injecting unrelated rules from every sibling directory.

Fix 2: Route Cross-Package Work From the Root File

A monorepo task may legitimately span several subtrees. In that case, add one compact routing section to the root AGENTS.md instead of copying every package rule into the root:

## Nested project instructions

- Before planning or editing under `services/payments/`, read and follow `services/payments/AGENTS.md`.
- Before planning or editing under `apps/dashboard/`, read and follow `apps/dashboard/AGENTS.md`.
- When a task spans both paths, apply both files only to the code they govern

Start a new Codex session after saving the change. Then ask Codex to name the files it will read before touching each subtree.

This is a routing workaround, not dynamic runtime discovery. It makes the root instruction chain tell the agent when to open a descendant file. A July 2026 r/codex report used this pattern after nested instructions were missed, and the reporter confirmed that adding the root reference restored the expected behavior.

Check for an Accidental Nested Project Root

Codex normally uses .git as a project-root marker. A stray .git directory can stop discovery before Codex reaches the real parent repository, even if that directory is empty.

Find nested markers:

repo_root="$(git rev-parse --show-toplevel)"

find "$repo_root" -mindepth 2 -name .git -print

Do not remove a marker just because it appears in this list. Submodules, worktrees, and intentional nested repositories use .git files or directories. Inspect the suspect path first:

git -C services/payments rev-parse --show-toplevel

If the nested marker is confirmed to be accidental, empty, and unrelated to a submodule, worktree, or nested repository, move it aside reversibly:

mv services/payments/.git services/payments/.git.disabled

Then start a new Codex session from the intended directory and repeat the instruction-source check. Expected result: discovery reaches the actual repository root and includes the applicable files between that root and the starting directory.

Check the 32 KiB Instruction Limit

Codex stops adding project instructions after the combined chain reaches project_doc_max_bytes, which defaults to 32 KiB. Check the files on the active path:

wc -c \
  ~/.codex/AGENTS.md \
  "$repo_root/AGENTS.md" \
  "$repo_root/services/payments/AGENTS.md" \
  2>/dev/null

Expected result: the total is comfortably below 32,768 bytes. If it is not, keep the root file focused on repository-wide rules and move package-specific detail closer to the package. You can also raise the limit in ~/.codex/config.toml:

project_doc_max_bytes = 65536

Restart Codex after editing the configuration. Raising the limit consumes more context on every session, so prefer a concise root file and scoped nested files before making the prompt larger.

Check Override and Profile Confusion

Codex checks AGENTS.override.md before AGENTS.md in each directory and uses at most one file at that level. If the regular file appears ignored, look for an override:

find "$repo_root" -type f -name AGENTS.override.md -print

Also check whether Codex is using a non-default home directory:

printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"

An unexpected CODEX_HOME changes where global instructions and config.toml are read. Correct the profile in the shell or launcher that starts Codex, then begin a new session.

Verify the Fix With Evidence

Use three checks rather than trusting a single conversational answer:

1. Start Codex with --cd set to the intended subtree.

2. Ask it to summarize one unique, harmless instruction from both the root and nested files.

3. Run a bounded task that should visibly follow the nested rule, such as naming the package-specific test command without executing it.

For a deeper local audit, enable the documented plaintext TUI log for one test session:

codex --cd services/payments -c log_dir=./.codex-log

After exiting the session, search for a distinctive phrase from the nested file:

rg -n "distinctive package rule" .codex-log/codex-tui.log

Expected result: the phrase appears in the assembled instruction context and the bounded task follows it. Keep the log local because it can contain prompts and repository context.

Why These Fixes Work

Codex instruction discovery has a startup boundary and a precedence chain:

global Codex home guidance
  -> repository root
  -> directories between root and startup cwd
  -> nearest file wins at each directory level
  -> combined size limit

Starting in the target subtree puts its file on that chain. Root routing handles the different case where one task must enter several descendant scopes. Removing only a confirmed accidental root marker restores the correct ancestry. Splitting or raising the byte limit prevents later instructions from being omitted.

These fixes do not make AGENTS.md a security boundary. Put deterministic safety, formatting, and test requirements in CI, hooks, permissions, or repository-owned scripts when a violation must be impossible. For review-specific guidance, see How to Add Custom Codex Code Review Rules in AGENTS.md.

Keep Structured Integrations Verifiable

Once Codex is loading the right project rules, use the same explicit-discovery habit for external Actions. Aident Loadout lets an agent search connected capabilities, inspect the exact schema, and preflight cost and approval requirements before execution.

aident account auth status
aident vault vault --action status

aident capabilities search \
  --targetEnv staging \
  --query "read-only repository issue search" \
  --types '["action"]' \
  --limit 5

Copy the exact Action name from the result, inspect it with aident capabilities get, and run aident capabilities preflight with bounded input. Expected result: Loadout shows authenticated account and Vault state, then returns a reviewed Action contract without exposing provider credentials.

Ready to test one governed integration path? Set up Aident Loadout and preflight one read-only Action.

Sources

• OpenAI: Custom instructions with AGENTS.md

• OpenAI Codex issue 37091: inherited AGENTS.md instructions not discovered or reported

• OpenAI Codex issue 12115: dynamically loading nested AGENTS.md

• OpenAI Codex issue 25651: an empty nested .git marker changed discovery

• r/codex: AGENTS.md files in nested folders

• YouTube: Codex AGENTS.md has a hidden 32KB limit

Review this article when Codex adds dynamic descendant discovery, changes project-root marker behavior, adds a dedicated agents-md diagnostic command, or changes the default project_doc_max_bytes limit.