How to write an AGENTS.md for Codex (with a starter template)

Disclosure: I run PickAPlugin, an independent catalog of ChatGPT and Codex plugins. This is adapted from our guide on the same topic.

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

What to put in it

• How to install, run, test and lint, with 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.

A starter template

# AGENTS.md

## Setup
- Install: `npm install`
- Dev server: `npm run dev`
- Tests: `npm test` (run before every commit)
- Lint: `npm run lint`

## Style
- TypeScript, strict mode. No `any` unless commented why.
- Prefer small functions and named exports.

## Don't touch
- `dist/` and other generated files
- `.env*` files and anything holding secrets
- `migrations/` unless the task is a migration

## PRs
- One focused change per PR.
- Commit messages: imperative mood, under 72 characters.

Where Codex looks

• ~/.codex/AGENTS.md holds global defaults.
• Then Codex reads 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.

Common questions

Do other tools read AGENTS.md? Yes, it's an open format. Cursor, Aider, Jules, Zed and others read it too.

Should I commit it? Yes, at the repo root, so everyone (and every agent) gets the same rules.

If you'd rather not start from a blank file, there's a free in-browser AGENTS.md generator that builds one from a few questions. The original guide is here.