Nested AGENTS.md in a monorepo: which file each agent reads
The short answer
Claude Code, Codex and Cursor load a package's AGENTS.md alongside the root one, each on its own trigger: Cursor for files in that folder, Codex sessions only when started in that package or below, and Claude Code (v2.1.277+) at startup if started there or when it opens a file there, by default only with no CLAUDE.md in the way. GitHub's docs say the nearest AGENTS.md takes precedence for Copilot.
A monorepo rarely has one set of rules. The API package runs its tests one way, the web app another, and a single root
file that covers every package grows long and mostly irrelevant to the code you are working on. The usual answer is a
nested AGENTS.md: a short file in each package with that package's own rules. The idea is simple. What
each coding agent actually does with those files is not the same, and the differences decide whether your package
rules reach the agent at all.
What the AGENTS.md format says
The AGENTS.md site recommends exactly this for large monorepos: place another AGENTS.md inside each package, because agents read the nearest file in the directory tree. Its FAQ adds that the closest AGENTS.md to the edited file wins when instructions conflict, and that explicit chat prompts override everything.
That is the intent of the format. Each agent's own documentation describes something more specific: when the file is read (at startup, or only when the agent touches that folder), which folders count, and whether the root file still loads next to it. In practice most agents combine the root and the package file rather than replacing one with the other.
What each agent does with a package AGENTS.md
| Agent | Reads the package file | With the root file |
|---|---|---|
| Claude Code | By default (v2.1.277+), if no CLAUDE.md is in the way: at startup if started there, else when Claude opens a file there | Both load |
| Codex | Sessions: only if started in that package or below it. Code review on GitHub: for files changed there | Both load; closer file later |
| Cursor | When working with files in that folder or below | Combined; package file takes precedence |
| GitHub Copilot | Can sit anywhere in the repo (GitHub); found along paths to files it works with (VS Code's Copilot harness) | Nearest takes precedence (GitHub); combined (VS Code's Copilot harness) |
| VS Code Local chat (deprecated) | On demand, only with two settings, one experimental and off by default | Root file included when its setting is on |
Sources: Claude Code's memory docs, the Codex AGENTS.md guide, Cursor's rules docs, GitHub's repository instructions docs and VS Code's custom instructions reference.
- Claude Code (v2.1.277 or later, default setting) reads AGENTS.md files only when there is no
CLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.mdin the folder you start it in or above it. Then it reads everyAGENTS.mdfrom that folder and the folders above it at session start. A subfolder's AGENTS.md loads later, when Claude opens a file there with the Read tool and that subfolder has none of those three files of its own. - Codex walks from the project root, usually the Git root, down to your current directory, takes at
most one file per directory (an
AGENTS.override.mdbeats an AGENTS.md in the same folder), and joins them root first, so closer files override earlier guidance. It stops at the directory you started in. Codex code review on GitHub works differently: it applies the root file and the more specific AGENTS.md that covers each changed file. - Cursor applies a nested AGENTS.md automatically when working with files in that directory or its children, combined with the parent directories' files, with the more specific one taking precedence.
- GitHub Copilot: GitHub's docs say AGENTS.md files can live anywhere in the repository and the
nearest one in the directory tree takes precedence. VS Code's reference says its Copilot harness discovers
AGENTS.md files at the root, the working directory, the folders in between and along the paths to the files it works with, and combines
them. VS Code's Local sessions, which VS Code has deprecated and plans to remove in February 2027, are different: nested discovery needs both
chat.useAgentsMdFileand the experimentalchat.useNestedAgentsMdFiles, which is off by default.
A worked example
Here is a small repository with a root file and two package files, and an open file in the API package. The root
AGENTS.md says to use pnpm and run pnpm check before committing; packages/api/AGENTS.md gives
the test command pnpm --filter api test and says never to edit src/generated/; packages/web/AGENTS.md says components live in src/components/.
AGENTS.md
packages/
api/
AGENTS.md
src/server.ts ← open file
web/
AGENTS.mdApplying each agent's documented rules above to packages/api/src/server.ts, started at the repository root:
- Claude Code: the root AGENTS.md at startup, then
packages/api/AGENTS.mdonce Claude opens a file inpackages/api/with the Read tool. - Codex (a session): the root AGENTS.md only. The API file is below the folder Codex started in.
- Cursor: the root file and the API file, combined.
- Copilot: the API file, as the nearest AGENTS.md, which GitHub's docs say takes precedence. GitHub's docs don't say whether the root file is also read; VS Code's reference says its Copilot harness combines the two.
Started in packages/api/ instead, Claude Code and Codex both load the root file and the API file at
startup. For server.ts, packages/web/AGENTS.md stays out in every case; it only comes into play when the agent works on a file in packages/web/, which is the point of splitting the rules.
The CLAUDE.md trap
A common way to share one AGENTS.md with Claude Code is a root CLAUDE.md that contains the line @AGENTS.md, as described in AGENTS.md vs CLAUDE.md.
It works for the root file. In a monorepo with nested files it has a side effect.
With the default Project instructions setting, Claude Code reads AGENTS.md files only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or
above it. The root CLAUDE.md counts. Claude then reads your CLAUDE.md files only, so the root AGENTS.md still arrives
through the import, but packages/api/AGENTS.md is no longer loaded as instructions. In our example, Claude would no longer
see the API package's own test command.
The same check applies to a gitignored CLAUDE.local.md you add at the repository root for your own notes: it counts as a
CLAUDE.md, so for you alone Claude stops reading AGENTS.md files directly, the root file and the package files alike.
Where to put AGENTS.md in a monorepo
- Root for what applies everywhere. Package manager, how to run all checks, commit and branch rules.
- Package for what only applies there. That package's test and build commands, generated folders not to edit, its conventions. Keep it short: when it loads, Claude Code and Codex read it in addition to the root file, not instead of it.
- Add, don't contradict. "Closest wins" is the format's intent, but most agents combine files, and Claude's docs say that with contradictory instructions it may pick one arbitrarily. If a package really is an exception, say so in the root file too.
- Mind Codex's limit. Codex stops adding files once their combined size reaches 32 KiB by default
(
project_doc_max_bytes), and a long root file leaves less room for the package file. In our measurement of 18 instruction files, pnpm's root AGENTS.md alone was just over that size. - Start where you work. For Codex, start in the package folder. For Claude Code with no CLAUDE.md in the way, starting in the package loads its AGENTS.md at startup instead of on demand.
To check Claude Code, start it in the package. With no CLAUDE.md in the way, an interactive session prints a line such
as no CLAUDE.md found; AGENTS.md loaded: followed by the path; with pointer files, run /context all and look for the package's CLAUDE.md under Memory files. For Codex, the guide suggests
starting it with codex --cd and the folder you want to test, and asking it to show which instruction
files are active.
MonoVue, our VS Code extension, shows this per agent for the file you have open. Pick Claude Code, Copilot, Cursor, Codex or Gemini CLI and the instruction overview lists the files that agent loads, treating the workspace folder as the folder the agent starts in. For Copilot it follows GitHub's documented rules, so it lists only the nearest AGENTS.md. It shows them in load order with an estimated token count for each, and adds a note when an expected file is left out, such as a package AGENTS.md hidden by a root CLAUDE.md.
Questions people ask
- Can a repository have more than one AGENTS.md?
- Yes. The AGENTS.md format suggests one per package in a large monorepo, and Claude Code (from v2.1.277), Codex, Cursor and GitHub Copilot each document reading AGENTS.md files below the repository root, with different rules for when. In VS Code, Local chat sessions (a harness VS Code has deprecated and plans to remove in February 2027) only discover nested files with chat.useAgentsMdFile and the experimental chat.useNestedAgentsMdFiles setting, which is off by default.
- Does the closest AGENTS.md override the root one?
- Not as a hard rule. The AGENTS.md site says the closest file wins, and GitHub says the nearest one takes precedence for Copilot, but when Codex, Cursor and Claude Code load the package file, they load it alongside the root one rather than instead of it. Codex places closer files later so they override earlier guidance, and Cursor gives the more specific file precedence. Claude Code's docs warn that when instructions contradict each other Claude may pick one arbitrarily, so use a package file to add rules rather than reverse the root's.
- Does Claude Code read AGENTS.md files in subdirectories?
- Yes, from v2.1.277 (some sessions, such as those on Amazon Bedrock, only from v2.1.281). With the default Project instructions setting, Claude reads a subfolder's AGENTS.md when it opens a file in that folder with the Read tool, but only if there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in that subfolder, in the folder you started Claude in, or above it. If you start Claude inside the package, its AGENTS.md loads at session start, under the same condition.
- Why doesn't Codex read my package's AGENTS.md?
- Codex builds its instruction chain once when it starts, from the project root (usually the Git root) down to the directory you started it in, with at most one file per directory. A package's AGENTS.md below that directory is not part of the chain. Start Codex in the package folder, for example with codex --cd, to include it. Codex code review on GitHub is different: it applies the root AGENTS.md and the more specific one that covers each changed file.
- Where should I put AGENTS.md in a monorepo?
- Put rules that apply everywhere, such as the package manager and the commit style, in the root AGENTS.md, and a package's own build and test commands and conventions in an AGENTS.md in that package's folder. Codex stops adding files once their combined size reaches 32 KiB by default, so keep both short.