AGENTS.mdAGENTS.md: where it lives and how tools read it
AGENTS.md is a plain Markdown file of project instructions that most coding agents read without extra setup. OpenAI contributed it to the Agentic AI Foundation under the Linux Foundation, and over 60k open-source projects use it.
Where it lives
- AGENTS.md at the repository root, for the whole project.
- Nested AGENTS.md files in subdirectories or packages; agents use the nearest one in the tree.
- OpenAI Codex: a global ~/.codex/AGENTS.override.md or, if that is empty or missing, ~/.codex/AGENTS.md.
- Cline: a global ~/.agents/AGENTS.md.
- Claude Code also accepts .claude/AGENTS.md.
Format
Plain Markdown with no frontmatter and no required fields; any headings work. The format sets no size limit, but OpenAI Codex stops reading at project_doc_max_bytes, 32 KiB by default.
# Acme web app
Customer-facing web app with an admin area and a REST API.
## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint and type-check: `pnpm lint && pnpm tsc --noEmit`
## Code style
- TypeScript strict mode; no `any` in new code.
- Keep database access in `src/db/`.
## Never
- Never commit secrets or .env files.
- Never edit files under `src/generated/` by hand.
Precedence and merging
The AGENTS.md closest to the file being edited wins, and an explicit instruction in chat overrides any file. OpenAI Codex concatenates one file per directory from the project root down to the working directory, so closer files come last and take priority. Claude Code skips AGENTS.md by default whenever a CLAUDE.md is present.
Tools that read it
| Tool | Support |
|---|---|
| OpenAI Codex | Native. Reads a global file, then at most one file per directory from root to working directory, up to 32 KiB by default. |
| Claude Code | Native from v2.1.277, but only when no CLAUDE.md or CLAUDE.local.md exists, unless set to claude-md-and-agents-md. |
| Cursor | Native, root and nested; nested files combine with parents and the more specific one wins. |
| GitHub Copilot (cloud agent, code review, VS Code) | Native, anywhere in the repository; the nearest file wins. |
| Devin Desktop (formerly Windsurf) | Native. The root file is always on; a subdirectory file applies to its own directory. |
| Cline | Native, plus a global ~/.agents/AGENTS.md; switch it on or off in the Rules panel. |
| Gemini CLI | Opt-in: add AGENTS.md to context.fileName in .gemini/settings.json. |
| Aider | Opt-in: add read: AGENTS.md to .aider.conf.yml. |
| OpenClaw | Native, as the required operating-instructions file in the agent workspace. |
| Listed on agents.md (not individually re-verified) | One of 23 tools on the agents.md list, including Amp, Jules, Zed, Warp, goose, opencode and JetBrains Junie; we didn't check these one by one. |
Tips
- Renaming an older AGENT.md? agents.md suggests mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md so both names keep working.
- List test and lint commands: agents try to run the checks they find and fix failures before finishing.
- In a monorepo, add a short AGENTS.md per package instead of growing one long root file.
- In OpenAI Codex, an AGENTS.override.md takes priority over AGENTS.md in the same directory.
Generate an AGENTS.md and matching rule files for five tools from one form. Open the AGENTS.md generator →