AGENTS.md in a monorepo: how each agent reads nested files
Put one AGENTS.md at the repo root for what every package shares, and one in each package for its own commands and rules. Most agents read the file nearest the code they touch, but each finds nested files differently, and a few never look below the root.
Can AGENTS.md be nested?
Yes. The agents.md spec says to place an AGENTS.md in each package: the one closest to the edited file wins, and an explicit instruction in chat overrides everything. The file is plain Markdown with no required fields, so a package file is just a shorter AGENTS.md.
The spec doesn't fix when an agent loads a nested file. Some read every file from the root down to the directory you started in; some load a package's file once they open a file in it; some read only the root.
How does each agent find nested AGENTS.md files?
| Agent | Which files it loads | Below the working directory |
|---|---|---|
| Claude Code | CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it, joined root first. AGENTS.md and .claude/AGENTS.md the same way, but only when none of those CLAUDE.md files exist. | A subdirectory's CLAUDE.md loads once Claude reads, writes or edits a file there; its AGENTS.md loads when Claude reads a file there and that directory has no CLAUDE.md. |
| Codex | From the project root (usually the Git root) down to the working directory, at most one file per directory: AGENTS.override.md, else AGENTS.md, else a fallback name. Joined root first; closer files override earlier ones. | Not read: only directories on the path to where you started count. Start Codex inside the package. |
| Cursor | AGENTS.md in the project root and in subdirectories, combined, the more specific taking precedence. CLAUDE.md is read like AGENTS.md; the docs describe one at the root. | Read. Rules in .cursor/rules/*.mdc can also scope to a package with globs. |
| Copilot cloud agent | Any number of AGENTS.md files anywhere in the repo; the nearest one in the directory tree takes precedence. | Read. |
| Copilot CLI | The repo root, the working directory, every directory between them, and directories on the path to a file it is working on. | Read along the path of each file it works on. |
| Copilot in VS Code | Copilot harness: root, working directory, intermediate directories and paths to files it works with, combined. Local harness: the root file needs chat.useAgentsMdFile. | Local harness: only with chat.useNestedAgentsMdFiles, which is experimental and off by default. |
| Gemini CLI | GEMINI.md in the workspace directories and their parents. AGENTS.md only once listed in context.fileName. | When a tool touches a file, it scans that directory and its ancestors up to a trusted root. |
| OpenCode | AGENTS.md found by walking up from the current directory; CLAUDE.md if there is no AGENTS.md. | Not documented. List package files in instructions, e.g. packages/*/AGENTS.md. |
| Devin | Looks for AGENTS.md before it starts coding, at the root "or anywhere else", and includes the first 16 KiB of each file. | Which file wins between nested ones is not documented. |
| Devin Desktop (ex-Windsurf) | AGENTS.md, AGENTS.local.md and AGENT.md as always-on rules, in each directory from the workspace root to the working directory. | Not documented beyond that path. |
| Antigravity | AGENTS.md or GEMINI.md in the folder and its parents up to the repo root, plus .agents/AGENTS.md and .agents/rules/*.md. | Not loaded. Open the package as the workspace. |
| Aider | Nothing automatically. Files load only when listed under read: in .aider.conf.yml or passed with --read. | Only what you list. |
The root file is the one every agent sees, so it must stand alone. A package file adds to it and can't rely on being loaded.
Does Codex have a size limit for nested AGENTS.md files?
Yes: 32 KiB combined by default (project_doc_max_bytes). Codex adds files root first and stops at the limit, so a long root file can crowd out the package file closest to your work, the one that matters most. Keep the root short, or raise the limit in your Codex config. Codex skips empty files.
Devin caps each file instead, at its first 16 KiB. Claude Code caps files it loads on demand at 40,000 characters each on a 200K context window, and Anthropic suggests under 200 lines per CLAUDE.md.
What goes in the root AGENTS.md and what goes in a package?
| Root AGENTS.md | Package AGENTS.md |
|---|---|
| How the workspace is laid out: which directory holds what | What this package is and who depends on it |
| The package manager and the one install command | This package's build, test and lint commands |
| Repo-wide rules: commit style, CI, generated files never to edit | Its framework, versions and local conventions |
| How to run one package's tests from the root (a filter flag) | Traps specific to it: slow tests, fixtures, env vars |
| A pointer: each package has its own AGENTS.md | Nothing that repeats the root |
Don't repeat the root in each package. Agents that concatenate files (Codex, Claude Code, Copilot CLI) see the text twice and spend context on it.
How do I give each package its own test command?
Write the exact command, runnable from that directory, in the package file, and the root-level equivalent in the root file. An agent that runs a large monorepo's whole suite to check one change wastes minutes; one that guesses the filter syntax wastes a turn.
packages/api/AGENTS.md
# packages/api
HTTP API on Hono. Depends on packages/db; nothing imports it.
## Commands (run from this directory)
- Test: `pnpm test` (from the root: `pnpm --filter api test`)
- One file: `pnpm vitest run src/routes/users.test.ts`
- Typecheck: `pnpm tsc --noEmit`
## Rules
- Routes live in src/routes/, one file per resource.
- Tests hit a real Postgres from `docker compose up db`; never mock packages/db.
What does a monorepo AGENTS.md layout look like?
One root file, one per package, CLAUDE.md files importing them
AGENTS.md # workspace map, install, repo-wide rules
CLAUDE.md # @AGENTS.md
apps/
web/AGENTS.md # Next.js app: dev server, e2e tests
web/CLAUDE.md # @AGENTS.md
packages/
api/AGENTS.md
api/CLAUDE.md # @AGENTS.md
db/AGENTS.md # migrations: never edit an applied one
db/CLAUDE.md # @AGENTS.md
Claude Code reads AGENTS.md only where it finds no CLAUDE.md, so one CLAUDE.md anywhere above hides every AGENTS.md. A one-line CLAUDE.md importing @AGENTS.md beside each file keeps both loading; Anthropic's docs say the import never makes Claude read the file twice. A symlink also works, but Git checks it out as a plain text file on Windows unless core.symlinks is on.
How do I set up CLAUDE.md for a large monorepo?
- Keep the root CLAUDE.md (or AGENTS.md) to what every session needs; it loads every time.
- Put package detail in that package's file, which loads only once Claude works there.
- Use
.claude/rules/*.mdwith apaths:glob list for rules tied to file types, not directories; such a rule loads when Claude reads, writes or edits a matching file. - Use
claudeMdExcludesin settings to skip other teams' CLAUDE.md files by path or glob. - Run
/memoryto see which files loaded, or/context allfor the list under Memory files.
How many popular repos use nested AGENTS.md files?
We read the whole file tree of 388 GitHub repos on our board on 2026-11-16. 218 have an AGENTS.md somewhere, and 109 of those (50%) have more than one or keep theirs below the root. The most files: BerriAI/litellm (120), medusajs/medusa (86), PostHog/posthog (66), apache/doris (31), mastra-ai/mastra (30).
Counts include empty files, and 13 trees were too large for GitHub to return whole, so these are a floor. The repo pages below show how the top repos score per agent.
Questions people ask
- Does Codex read AGENTS.md files in subdirectories?
- Only those on the path from the project root to the directory you started Codex in, one per directory, up to 32 KiB combined. A package's file is read if you start Codex in that package or below it.
- Does Cursor support nested AGENTS.md?
- Yes. Cursor reads AGENTS.md in the project root and in subdirectories, combines them, and lets the more specific one take precedence.
- Which AGENTS.md wins when two conflict?
- The agents.md spec says the closest one to the edited file, with your chat prompt overriding both. Codex and Copilot document the same; Antigravity combines every file it finds without stating an order.
- Can I use AGENTS.override.md in a monorepo?
- In Codex, yes: in any directory it replaces the AGENTS.md beside it. Claude Code doesn't read
AGENTS.override.md. - Should each package have a CLAUDE.md too?
- Only if your team uses Claude Code and you want it to read the package's AGENTS.md even when a CLAUDE.md exists higher up. A one-line
@AGENTS.mdimport does it. - Is one big root AGENTS.md better than nested files?
- For a small repo, yes. In a monorepo a long root file costs every session context, and in Codex it can push the package file past the 32 KiB limit.
From the docs: agents.md (new tab) · code.claude.com/memory (new tab) · learn.chatgpt.com/agents-md (new tab) · cursor.com/rules (new tab) · docs.github.com/add-repository-instructions (new tab) · docs.github.com/add-custom-instructions (new tab) · code.visualstudio.com/custom-instructions-reference (new tab) · geminicli.com/gemini-md (new tab) · opencode.ai/rules (new tab) · docs.devin.ai/agents-md (new tab) · docs.devin.ai/memories (new tab) · antigravity.google/rules (new tab) · aider.chat/conventions.html (new tab)
litellm · medusa · posthog · doris · mastra · Check your AGENTS.md · AGENTS.md examples · CLAUDE.md guide · One file for every agent · What each agent reads