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…
Here's a guide on creating an AGENTS.md file specifically for Codex, complete with a starter template:
What is AGENTS.md?
AGENTS.md is a simple Markdown file that Codex checks before interacting with your repository. Consider it a briefing note for a new team member to help them understand how to set up and work on your project.
Key elements to include in AGENTS.md:
1. Setup instructions:
- Installation command: `npm install`
- Development server: `npm run dev`
- Running tests: `npm test` (mandatory before each commit)
- Linting: `npm run lint`
2. Coding style guidelines:
- Use TypeScript with strict mode and avoid using `any` unless necessary
- Favor small, well-named functions and exports
3. What not to modify:
- Generated files located in the `dist/` folder
- `.env*` files containing sensitive information
- `migrations/` folder, unless the task specifically involves migrations
4. Contributing guidelines:
- One focused change per pull request (PR)
- Commit messages in imperative mood, under 72 characters
How Codex processes AGENTS.md:
- The file is located at ~/.codex/AGENTS.md for global defaults
- Codex sequentially reads AGENTS.md files from the repository root down to the current working folder
- Later files override earlier ones; for example, AGENTS.override.md will take precedence over AGENTS.md in the same folder
- The total size of combined AGENTS.md files is limited to 32 KiB
Additional tips:
- Commit AGENTS.md to the repository root so all team members and agents share the same rules
- If you don't want to start from scratch, use the free in-browser AGENTS.md generator, which creates a file based on a few simple questions
Remember, AGENTS.md is an open standard used by various tools like Cursor, Aider, Jules, and Zed. By providing clear instructions and guidelines, you help ensure consistency and make onboarding new contributors easier.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
