What AGENTS.md is and how coding agents use it

Last updated October 30, 2026

AGENTS.md is a plain Markdown file of instructions for AI coding agents, kept in your repository like a README written for agents. Codex and many other agents read it before they start work. Put build steps, test commands, code style and project conventions in it. It has no required fields or format.

Who reads AGENTS.md

AGENTS.md is an open format, now stewarded by the Agentic AI Foundation under the Linux Foundation. The agents.md site lists the tools that support it, among them OpenAI Codex, Google Jules, Gemini CLI, GitHub Copilot's coding agent, Cursor, Windsurf, Devin, Aider, Zed, Warp, VS Code, JetBrains Junie, Amp, goose and opencode.

Some tools need one setting first. For Aider, add read: AGENTS.md to .aider.conf.yml. For Gemini CLI, set "context": { "fileName": "AGENTS.md" } in .gemini/settings.json.

Claude Code reads its own file, CLAUDE.md. From version 2.1.277 it also reads AGENTS.md when a project has no CLAUDE.md. See What CLAUDE.md is.

Where Codex looks for AGENTS.md

Codex builds its instructions fresh at the start of each run:

1. Your global file. ~/.codex/AGENTS.override.md if it exists, otherwise ~/.codex/AGENTS.md. These apply to every project.
2. Your project. Starting at the root of the git repository and going down to the folder you're in, Codex checks each folder for AGENTS.override.md, then AGENTS.md. It takes at most one file per folder.

Codex joins the files from the root down. A file closer to your current folder comes later, so its guidance wins where two files disagree. Empty files are skipped.

To check what Codex loaded, run codex --ask-for-approval never "Summarize the current instructions."

Use nested AGENTS.md files in a monorepo

Put one AGENTS.md at the root for rules that apply everywhere, and one in each package for rules that apply only there. The agents.md format says the file closest to the code being edited wins, and a direct instruction in the chat overrides any file.

The size limit

Codex stops adding AGENTS.md files once their combined size reaches 32 KiB, the default value of project_doc_max_bytes in ~/.codex/config.toml. Guidance past that point is never read. If you're near the limit, move rules into the package folders that need them, or move growing notes such as past decisions out of the file and into something the agent searches.

Use another file name

If a project already has instructions under another name, list it in project_doc_fallback_filenames in ~/.codex/config.toml. Codex then tries those names when a folder has no AGENTS.md.

Share one file with Claude Code

Claude Code prefers CLAUDE.md. To keep one set of instructions for both tools, make a CLAUDE.md that contains @AGENTS.md, with anything specific to Claude Code below it. You can also make CLAUDE.md a link to AGENTS.md (ln -s AGENTS.md CLAUDE.md), but links can cause trouble for people on Windows.

Frequently asked questions

Is it AGENTS.md or AGENT.md?

AGENTS.md, plural. If a project has an AGENT.md, the agents.md site suggests renaming it and leaving a link in its place: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

Does Codex read AGENTS.md from my home folder?

Yes. Codex reads ~/.codex/AGENTS.md, or ~/.codex/AGENTS.override.md if that exists, before the files in your project.

Is there a size limit for AGENTS.md?

In Codex, yes: 32 KiB for all AGENTS.md files together, by default. Change it with project_doc_max_bytes in ~/.codex/config.toml.

What should go in AGENTS.md?

Rules that most tasks need: how to build, test and run the project, code style, folder layout and what to avoid. Long histories and decisions that only some tasks need fit better in a memory the agent searches. See CLAUDE.md and AGENTS.md vs a memory server.

Can Codex remember things between sessions without editing AGENTS.md?

Yes, with an MCP memory server. Codex saves notes there and searches them later. See how to give Codex memory between sessions.

Sources

Checked on October 30, 2026:

• AGENTS.md, the format's site
• Custom instructions with AGENTS.md, Codex documentation
• How Claude remembers your project, Claude Code documentation