Monorepos · Instruction files

Nested AGENTS.md in a monorepo: which file each agent reads

6 min read

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

A package-level AGENTS.md, by agent (from each tool's docs, November 2026)
AgentReads the package fileWith the root file
Claude CodeBy default (v2.1.277+), if no CLAUDE.md is in the way: at startup if started there, else when Claude opens a file thereBoth load
CodexSessions: only if started in that package or below it. Code review on GitHub: for files changed thereBoth load; closer file later
CursorWhen working with files in that folder or belowCombined; package file takes precedence
GitHub CopilotCan 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 defaultRoot 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.md or CLAUDE.local.md in the folder you start it in or above it. Then it reads every AGENTS.md from 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.md beats 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.useAgentsMdFile and the experimental chat.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/.

Repository layout (one Git repository, no CLAUDE.md)
AGENTS.md
packages/
  api/
    AGENTS.md
    src/server.ts   ← open file
  web/
    AGENTS.md

Applying 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.md once Claude opens a file in packages/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

  1. Root for what applies everywhere. Package manager, how to run all checks, commit and branch rules.
  2. 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.
  3. 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.
  4. 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.
  5. 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.