AGENTS.md

8:04 AGENTS.md is a Markdown file you put in a repository to tell AI coding agents how to work on it: the build and test commands, the code style, what to avoid. Codex "reads AGENTS.md files before doing any work" (OpenAI docs), and so do many other agents, because AGENTS.md is an open format, described by its site as "a README for agents" and used by over 60,000 open-source projects. Type /init in Codex to have it write a first draft for your project (Developer commands).

7:49 OpenAI first showed AGENTS.md at the launch of Codex on May 16, 2025, when its engineers said "we've introduced this concept of an AGENTS.md file", released it as an open format in August 2025, and later gave it to the Agentic AI Foundation under the Linux Foundation, which it co-founded with Anthropic and Block (OpenAI). The first Codex launch, on May 16, 2025, already said Codex "can be guided by AGENTS.md files placed within your repository" (OpenAI).

Quick facts

What goes in an AGENTS.md file?

8:32 Anything you would tell a new teammate who writes code but has never seen the project. The format's site suggests a project overview, build and test commands, code style, testing instructions and security considerations, plus commit and pull request rules, deployment steps and known traps (agents.md). A short example:

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons

16:00 Agents run the test commands you list and try to fix failures before finishing (agents.md). A README stays for people; AGENTS.md holds the detail that would clutter it.

How Codex finds AGENTS.md files

Codex builds an instruction chain once per run (in the interactive CLI, once per session) (OpenAI docs):

1. Global. In the Codex home folder (~/.codex, or wherever CODEX_HOME points), it reads AGENTS.override.md if there is one, otherwise AGENTS.md. Only the first non-empty file counts.
2. Project. From the project root (usually the Git root) down to the folder you are working in, it checks each folder for AGENTS.override.md, then AGENTS.md, then any fallback names you configured, and takes the first one it finds there. With no project root, it checks only the current folder.
3. Merge. It joins the files from the root down, so the closest file comes last and overrides anything earlier.

Empty files are skipped, and Codex stops adding files once the total reaches project_doc_max_bytes, 32 KiB by default. Codex stops at the working folder, so put specialized rules as close to the code as possible. A quick check: codex --ask-for-approval never "Summarize the current instructions." should quote your rules back (OpenAI docs).

Override files

AGENTS.override.md replaces the AGENTS.md in the same folder. In a subfolder it lets one team use different rules (a payments service that runs make test-payments instead of npm test); in ~/.codex it is a temporary global override you delete to go back to your normal rules (OpenAI docs).

Other file names and a bigger limit

If a repository already keeps agent rules in another file, add its name to project_doc_fallback_filenames in ~/.codex/config.toml, and raise the size limit if needed:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Codex then checks AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md and .agents.md in that order in each folder (OpenAI docs). For files named AGENT.md, the format's site suggests renaming to AGENTS.md and leaving a symbolic link behind (agents.md).

Create one with /init

1. Open Codex in the folder where the instructions should live (the repository root for project-wide rules).
2. Type /init.
3. Read the generated AGENTS.md, correct it to match how the project really works, and commit it.

Source: Developer commands, OpenAI docs, read Nov 6, 2026. /init for AGENTS.md was announced in the ChatGPT release notes on Jun 11, 2026.

Code review rules

5:57 Codex Code Review reads a ## Code Review Rules section in the AGENTS.md closest to the changed code. Keep it to a few rules about consequential, project-specific behavior, each with its safe path or exception, and leave formatting and lint to CI (OpenAI docs, GitHub review). Codex Cloud tasks also use AGENTS.md to find the project's lint and test commands (Codex Cloud (Legacy)).

Keep it short

Codex reads the combined files before every task, and OpenAI's tips for making Codex usage last include "Reduce the size of your AGENTS.md" (pricing). Put rules that only matter in one folder in that folder's file, and package repeatable procedures as skills instead (Codex CLI).

Which tools read AGENTS.md?

OpenAI lists Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules and VS Code among the tools that adopted it (OpenAI). Some need a setting: the format's site shows Gemini CLI reading it through .gemini/settings.json and Aider through read: AGENTS.md in .aider.conf.yml (agents.md). Rival agents are compared on Codex vs Claude Code and Codex vs Cursor.

The open format and the Agentic AI Foundation

The format grew out of a Codex need: a predictable place to find a project's conventions, build steps and test rules. OpenAI released it in August 2025 as a file to sit beside README.md, and the format's site credits OpenAI Codex, Amp, Google's Jules, Cursor and Factory with shaping it. OpenAI then co-founded the Agentic AI Foundation (AAIF) under the Linux Foundation with Anthropic and Block, supported by Google, Microsoft, AWS, Bloomberg and Cloudflare, and contributed AGENTS.md to it; Anthropic contributed the Model Context Protocol and Block its goose agent (OpenAI, agents.md). The site notes that OpenAI's main repository had 88 AGENTS.md files when it was written.

Frequently asked questions

What is AGENTS.md? AGENTS.md is a Markdown file of instructions for AI coding agents, a "README for agents", holding build and test commands, code style and project rules. Codex reads it before every task, and many other coding agents support the same open format.

Where does Codex look for AGENTS.md? Codex reads a global file in ~/.codex first, then every AGENTS.md from the repository root down to the folder you are working in; the closest file comes last and wins.

How do I create an AGENTS.md file? Type /init in Codex to generate a draft for the current folder, then edit it to match the project and commit it. Any Markdown with headings you choose works; there are no required fields.

Is there a size limit for AGENTS.md in Codex? Yes. Codex stops adding AGENTS.md files once their combined size reaches 32 KiB by default; raise it with project_doc_max_bytes in config.toml.

What is AGENTS.override.md? AGENTS.override.md replaces the AGENTS.md in the same folder for Codex, so one folder or your global setup can use different rules without deleting the shared file.

Sources

• Custom instructions with AGENTS.md, OpenAI docs, read Nov 6, 2026
• Developer commands, OpenAI docs, read Nov 6, 2026
• Review GitHub pull requests with Codex, OpenAI docs, read Nov 6, 2026
• Codex Cloud (Legacy), OpenAI docs, read Nov 6, 2026
• Pricing, OpenAI docs, read Nov 6, 2026
• Codex CLI, OpenAI docs, read Nov 6, 2026
• ChatGPT release notes, OpenAI Help Center, read Nov 6, 2026
• AGENTS.md, the format's site, read Nov 6, 2026
• OpenAI co-founds Agentic AI Foundation, donates AGENTS.md, OpenAI, read Nov 6, 2026 (no date shown in the copy read)
• Introducing Codex, OpenAI, May 16, 2025
• A research preview of Codex in ChatGPT, OpenAI, May 16, 2025 (video)
• Automatic code reviews with OpenAI Codex, OpenAI, Nov 4, 2025 (video)