AGENTS.md for Codex: what it is, with a free template

What is AGENTS.md?

The AGENTS.md site calls it "a simple, open format for guiding coding agents". Think of it as a README written for AI agents instead of people. It is plain Markdown, and no fields are required. A group called the Agentic AI Foundation now looks after it, as part of the Linux Foundation.

OpenAI's Codex reads it. So do Cursor, GitHub Copilot's coding agent, Gemini CLI, Aider, Zed and many more on the AGENTS.md site. Claude Code reads it too, when the project has no CLAUDE.md.

Put an AGENTS.md in the top folder of your project. Add your build and test commands, your rules, and what not to touch. Below you'll find how Codex joins files, what to write, an example and a free template.

Download AGENTS.md →Free, no email needed. Plain Markdown: open it in any text editor.

How Codex finds AGENTS.md

The Codex docs on AGENTS.md describe two levels:

1. Global: AGENTS.md in your Codex home folder (~/.codex by default). If an AGENTS.override.md sits there, it wins.
2. Project: Codex starts at the top of the project, which is usually where git starts. Then it walks down to the folder you work in. In each folder it takes one file at most: AGENTS.override.md first, then AGENTS.md, then any other names you set up.

Codex joins all the files it finds, from the top down. Files closer to your working folder come later. So when two rules clash, the closer one wins. Empty files are skipped.

The 32 KiB limit

The setting project_doc_max_bytes caps the joined text. By default the cap is 32 KiB. Once Codex hits the cap, it adds no more files. Are your instructions getting long? Split them into files in subfolders. Or raise the limit in ~/.codex/config.toml.

Check what Codex loaded

From the top folder of the project, ask Codex to list its instructions. OpenAI gives this example:

codex --ask-for-approval never "Summarize the current instructions."

Codex should repeat your rules in the order it used them.

What to put in it

The AGENTS.md site suggests these sections:

• Project overview
• Build and test commands
• Code style guidelines
• Testing instructions
• Security considerations

Add rules for commits and pull requests, steps to deploy, and traps to avoid, where they help. Be specific. Give exact commands and exact paths. Write rules an agent can check its own work against.

An example

# AGENTS.md

## Project
Static website, built with `python build.py` into `public/`.

## Commands
- Build and check: `python build.py --check` (must print `checks: OK`)

## Rules
- After meaningful work, update `project/status.json`: done, next, waiting on me
- Commit only the files you changed, by name; never `git add .`
- Ask before deploying or publishing anything

## Don't touch
- `public/` by hand (it's generated)

How I use it

I put the same status rule in both AGENTS.md and CLAUDE.md: "after meaningful work, update the status file". That way Codex and Claude Code keep one shared record of each project, whichever of them did the work.

Nested files in monorepos

Some rules only apply to one part of a project. Put those in an extra AGENTS.md in that subfolder. The AGENTS.md site says the nearest file wins. And what you type in the chat beats every file. Codex works the same way: it reads subfolder files last, so they win. The Codex docs explain this.

Cursor reads AGENTS.md at the top of the project and in subfolders. It joins a subfolder's file with the ones above it, and the more specific file wins. For more detailed rules, Cursor also has its own .cursor/rules format. See the Cursor rules page.

Sharing AGENTS.md with Claude Code

Claude Code reads AGENTS.md itself when there is no CLAUDE.md or CLAUDE.local.md in your folder or above it. That needs version 2.1.277 or later. Want some rules for Claude only? Make a CLAUDE.md whose first line is @AGENTS.md. Add the extra rules below it. Claude then reads the shared file first and your extra rules after it. The Claude Code memory docs describe this.

The CLAUDE.md guide has its own template. Choosing between the two agents? The Codex vs Claude Code comparison shows how to run both on one project.

Moving from another filename

Maybe your project already has an instructions file under another name. The AGENTS.md FAQ suggests renaming it to AGENTS.md. Then leave a symbolic link (a shortcut) under the old name, for tools that still look for it. Setting up on Windows? The Windows guide covers installing Claude Code and Codex there.

Download AGENTS.md →Free, no email needed. Plain Markdown: open it in any text editor.