Guide · updated Oct 27, 2026

How to write an AGENTS.md

AGENTS.md is a plain markdown file Codex reads before it touches your repo. Think of it as the note you'd leave a new teammate.

What to put in it

How to install, run, test and lint (the exact commands).
Code style rules that aren't obvious from the code.
What not to touch: generated files, secrets, migrations.
How you want PRs and commit messages written.

Where Codex looks

~/.codex/AGENTS.md for global defaults, then every AGENTS.md from the repo root down to your working folder. Closer files win. AGENTS.override.md beats AGENTS.md in the same folder. The combined size is capped at 32 KiB by default, so keep it tight.

Want a head start? Our AGENTS.md generator builds one from a few questions, in your browser.

Questions people ask

Do other tools read AGENTS.md?

Yes, it's an open format. Cursor, Aider, Jules, Zed and others read it too.

Should I commit AGENTS.md?

Yes, commit it at the repo root so everyone, and every agent, gets the same rules.

All guides · Free tools · FAQ · Browse all 346 plugins