AGENTS.md
AGENTS.md is an open-standard markdown file of instructions for AI coding agents, read by Codex, Cursor, Copilot, Gemini CLI, and Claude Code.
AGENTS.md is a plain markdown file of instructions for AI coding agents, usually at the root of a repository. README.md is for people; AGENTS.md is for agents. It holds the things an agent needs on every task: how to build and test, conventions, a short map of the codebase, and what never to touch.
It is an open standard, not a vendor feature. The project site says it is stewarded by the Agentic AI Foundation under the Linux Foundation and used by over 60,000 open-source projects.
Which tools read it
- Codex reads it natively, from
~/.codex/and every directory from the git root down, capped at 32 KiB by default. - Claude Code reads it since v2.1.277, when no CLAUDE.md exists. A CLAUDE.md can import it with
@AGENTS.md. - Cursor, GitHub Copilot, Gemini CLI and many other agents list support.
In a monorepo, agents read the nearest AGENTS.md in the directory tree, so each package can carry its own.
What belongs in it
Constants: things still true in three months if nobody touches them. Commands, invariants, boundaries, and conventions a linter can't enforce. Decisions that change, deprecations, and work in progress go stale in a static file. For a full example and what to leave out, see AGENTS.md vs CLAUDE.md, more examples in AGENTS.md examples, and for Codex specifically, Codex memory.
- What is AGENTS.md?
- A markdown file, usually at the repository root, that tells AI coding agents how to work in a project: commands, conventions, and boundaries. It is an open standard stewarded by the Agentic AI Foundation under the Linux Foundation.
- Does Claude Code read AGENTS.md?
- Yes, since v2.1.277, but by default only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. A CLAUDE.md can import it with @AGENTS.md.
- How does Codex read AGENTS.md?
- Codex reads a global file from ~/.codex/ and then every AGENTS.md from the git root down to the current directory, concatenated, with files closer to where you work taking precedence. The chain is capped at 32 KiB by default.
Related