DEV Community

AGENTS.md ignored in a monorepo? Claude Code and Codex walk the tree in opposite directions

How Claude Code and Codex build the chain

Start Codex at the root of a monorepo and the AGENTS.md in your package stays out of that run. Leave a CLAUDE.md in any folder above your working directory and Claude Code, under its default setting, reads that file instead of AGENTS.md.

In both cases the AGENTS.md sits where you put it. So when an AGENTS.md looks ignored, check the path around it before you edit the file. Three things decide what loads: the folder you launched from, a file higher up that takes its place, and a size cap.

The same problem shows up on Stack Overflow for other setups. A question about GitHub Copilot reporting no instructions while AGENTS.md is in the repository had 1,584 views on 5 November 2026, and one about AGENTS.md in a Gradle multi-module project had 149.

This post covers Claude Code and Codex, the two I use, per their official docs as of 5 November 2026. For a file-by-file comparison of the two formats, see CLAUDE.md vs AGENTS.md.

Take this monorepo, with the session started in packages/api/src:

repo/
  AGENTS.md
  packages/
    api/
      AGENTS.md
      src/
    web/
      AGENTS.md
      CLAUDE.md

Codex, per its AGENTS.md guide, first reads one global file from its home folder (~/.codex unless you set CODEX_HOME): AGENTS.override.md if it exists, otherwise AGENTS.md. Then it starts at the project root, typically the Git root, and walks down to the folder you launched from.

In each folder it takes at most one file, checking AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. It joins the files root first, so the file closest to your folder comes last and overrides earlier guidance.

Claude Code, per its memory docs, walks the other way: from your working directory up through every folder above it. If no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits on that path, it reads every AGENTS.md and .claude/AGENTS.md it finds there at session start.

An AGENTS.md below your working directory loads later, when Claude Code opens a file in that subfolder with the Read tool, and only if the subfolder has no CLAUDE.md of its own. Reading AGENTS.md directly needs Claude Code v2.1.277 or later.

The agents.md site recommends nested files for monorepos and says the file closest to the edited file takes precedence. Claude Code and Codex both follow that layering and differ in when each file enters the session.

With both started at the root of the example repo, Claude Code reads packages/api/AGENTS.md once it opens a file in that package with the Read tool, and Codex leaves it out of the run.

Three files that hide an AGENTS.md

  • AGENTS.override.md. Codex checks it first in each folder and reads only one file there, so an override hides the AGENTS.md beside it. Claude Code doesn't read override files at all. If Codex follows rules you can't find, look for an override higher in the tree or in ~/.codex.
  • A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it. Under the default setting, Claude Code reads those instead of AGENTS.md, even when the file sits in a parent folder above the repo. Your ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ files don't count: they load alongside AGENTS.md.
  • A package CLAUDE.md. In the example, packages/web/CLAUDE.md makes Claude Code skip packages/web/AGENTS.md when it works in that package. Codex reads packages/web/AGENTS.md and ignores the CLAUDE.md.

The Codex troubleshooting list adds two causes. Codex skips empty files. A non-default CODEX_HOME points it at a different home folder from the one you edited, so run echo $CODEX_HOME before you debug the global file.

Where root rules and package rules go

Put rules every package follows in the root AGENTS.md and rules for one package in that package's AGENTS.md. If a package needs a CLAUDE.md for lines only Claude Code should see, start that file with a bare @AGENTS.md import.

Claude Code reads the imported file first, then the lines below it, so Claude Code and Codex both get the package AGENTS.md.

In a large monorepo, Claude Code's claudeMdExcludes setting skips other teams' files by path or glob, and the docs say it covers the AGENTS.md files Claude Code reads too. Put it in .claude/settings.local.json to keep the exclusion on your machine.

Keep the Codex chain under 32 KiB

Codex stops adding files once the combined size of the chain reaches project_doc_max_bytes, 32 KiB by default. Root files load first, so in a deep package the root file can use most of the budget and the package file, which loads last, gets cut.

Raise the limit in ~/.codex/config.toml or move rules out of the root file:

# ~/.codex/config.toml
project_doc_max_bytes = 65536

Claude Code's docs target under 200 lines per CLAUDE.md, and a file over 4 MiB is skipped. A subfolder CLAUDE.md that loads on demand has a per-file character limit tied to the context window, and Claude Code receives only the start of a longer file.

Check what loaded, from the root and from a package

This script only reads files. It prints the Codex chain with its combined size, any file that stops Claude Code reading AGENTS.md, and the nested files below you. It doesn't cover names in project_doc_fallback_filenames.

#!/usr/bin/env bash
# Run from the folder you start Claude Code and Codex in.
root=$(git rev-parse --show-toplevel) || exit 1
here=$(pwd -P)
home=${CODEX_HOME:-$HOME/.codex}
echo "Codex chain (global, then root down to here):"
for f in "$home/AGENTS.override.md" "$home/AGENTS.md"; do [ -s "$f" ] && { echo "$f"; total=$(wc -c < "$f"); break; } done
dirs=()
d=$here
while :; do dirs=("$d" "${dirs[@]}"); [ "$d" = "$root" ] && break; d=$(dirname "$d"); done
for d in "${dirs[@]}"; do for f in AGENTS.override.md AGENTS.md; do [ -s "$d/$f" ] && { echo "$d/$f"; total=$((${total:-0} + $(wc -c < "$d/$f"))); break; } done done
echo "combined bytes: ${total:-0} of 32768 default"
echo "Files that stop Claude Code reading AGENTS.md (here and above):"
d=$here
while :; do for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do [ -e "$d/$f" ] && [ "$d/$f" != "$HOME/.claude/CLAUDE.md" ] && echo "$d/$f" done; [ "$d" = / ] && break; d=$(dirname "$d"); done
echo "Nested files below here (load later or only from their folder):"
find . -mindepth 2 \( -name 'AGENTS*.md' -o -name 'CLAUDE*.md' \) -not -path '*/node_modules/*' -not -path './.git/*'

Then ask Codex directly. Its guide gives one command for the root and one for a package. Both turn approval prompts off, so run them only in a repo you trust:

codex --ask-for-approval never "Summarize the current instructions."
codex --cd packages/api --ask-for-approval never "Show which instruction files are active."

For a record, start Codex with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log. Codex rebuilds the chain on every run, so restart it in the target folder after an edit.

In Claude Code, an interactive session with no CLAUDE.md on the path shows a line starting no CLAUDE.md found; AGENTS.md loaded: followed by the file's path. Run /memory and look for that path, or run /context all and check the list under Memory files.

Before v2.1.280 neither one listed an AGENTS.md read directly, so on older versions ask Claude Code what its project instructions say. A nested CLAUDE.md that loads on demand prints a Loaded line with its path when it enters the session.

If /config has no Project instructions setting, your session can't read AGENTS.md directly, and a CLAUDE.md with @AGENTS.md is the way in.

The checklist for one package:

  • Start in the package folder and run the script.
  • Remove or rename any AGENTS.override.md you didn't mean to keep.
  • Remove stray CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md files on the path, or set Project instructions to claude-md-and-agents-md in /config.
  • Keep the Codex combined size under 32 KiB, or raise project_doc_max_bytes.
  • Run both Codex commands above and confirm the package file comes last.
  • In Claude Code, look for the AGENTS.md loaded line or the path in /memory.

If the script turns up a file you didn't write, my post on the planted AGENTS.md in Downloads has commands to check where it came from and what it changed.

One global rulebook for Claude Code and Codex

The global layer sits at the top of every chain above, so I keep mine in one place. In the Two Engines Kit, RULES.md holds the rules Claude Code and Codex share, and claude.md and codex.md hold the few lines that differ.

The installer points ~/.claude/CLAUDE.md at the shared rules and builds ~/.codex/AGENTS.md from them with sync.sh. It previews each change, asks first and backs up what it replaces, and uninstall.sh restores it.

The kit is built on information gathered since the first Codex and Claude CLIs. Project and package AGENTS.md files stay in your repo, so every check in this post applies with the kit installed too.

If you run Claude Code and Codex on one machine, get the Two Engines Kit at https://rayastats.com/en/two-engines-kit and keep one global rulebook for both.

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.