Home / Codex AGENTS.md template
A Codex AGENTS.md template for OpenAI Codex CLI
OpenAI Codex reads AGENTS.md before it does any work. That file is the Codex CLI agent instructions for the repo: stack, commands, hard never-dos, and what “done” means. A short, specific file gets followed. A 600-line essay gets skimmed.
This guide is a Codex AGENTS.md template you can paste today, plus how Codex actually discovers those files, and how that differs from CLAUDE.md and Cursor rules.
What Codex reads
Codex builds an instruction chain once per run (in the TUI, once per session):
- Global:
~/.codex/AGENTS.override.mdif it exists, otherwise~/.codex/AGENTS.md. Personal defaults, not repo rules. - Project: from the repo root (usually the Git root) down to the current working directory. In each directory it prefers
AGENTS.override.md, thenAGENTS.md. At most one file per directory. - Merge: files concatenate root → cwd. Closer files appear later, so they override broader guidance.
Empty files are skipped. Combined project instructions cap at about 32 KiB by default (project_doc_max_bytes). Keep the root file short; put specialist rules in nested directories instead of one giant README. Official discovery notes: Custom instructions with AGENTS.md.
Codex does not read CLAUDE.md or .cursor/rules/*.mdc. If those are your only instruction files, Codex guesses.
Minimal copy-paste template
Drop this at the repo root as AGENTS.md. Fill every <<FILL>>. Codex’s /init can scaffold a starter; edit that result the same way — exact commands beat vague vibes.
# AGENTS.md <!-- OpenAI Codex CLI agent instructions. Fill every <<FILL>>. --> ## Project - App: <<FILL: name and one-line purpose>> - Stack: <<FILL: e.g. Next.js 15 App Router, Supabase, Stripe, pnpm>> - Layout: <<FILL: where app/, lib/, tests, and generated types live>> ## Commands - Dev: <<FILL: e.g. pnpm dev>> - Test: <<FILL>> - Lint: <<FILL>> - Typecheck: <<FILL>> ## Hard rules - Never print, log, or commit secrets. Never prefix secrets with NEXT_PUBLIC_. - Never disable tests, typecheck, RLS, or other safety checks to make something pass. - Keep diffs small. Never edit generated files by hand. - For auth, payments, or migrations: write a short plan and wait for go. ## Workflow 1. Restate the goal in one line and list the files you will touch. 2. Make one small change, then run the tests / typecheck you listed. 3. Report what you verified, and what you could not verify. ## Done means The commands above pass, the change is described in plain words, and you did not expand the scope.
Paste a safety section from the free agent-guardrails.md (MIT) when the agent will call tools or read untrusted content. For Next.js + Supabase, the free nextjs-supabase-rls.mdc is a Cursor-shaped rule; copy the bullets into AGENTS.md (or a nested supabase/AGENTS.md) so Codex sees them too.
How this differs from CLAUDE.md and Cursor rules
| File | Who reads it | Shape | Use it for |
|---|---|---|---|
| AGENTS.md | OpenAI Codex CLI, Cursor, and other AGENTS.md-aware tools | Plain Markdown; nested files concatenate root → cwd | Shared source of truth: stack, commands, never-dos, done criteria |
| CLAUDE.md | Claude Code | Markdown; can import files with @path |
A thin file that starts with @AGENTS.md, then Claude-only notes |
| .cursor/rules/*.mdc | Cursor | Markdown + YAML frontmatter (globs, alwaysApply) |
Path-scoped rules that load only when matching files are in context |
Recommended layout: write AGENTS.md first so Codex has instructions. Add a one-line CLAUDE.md that imports it. Add scoped Cursor .mdc files for auth, RLS, or Stripe — do not paste the whole essay into every format. Full comparison: AGENTS.md vs CLAUDE.md vs Cursor rules. Claude-specific template: CLAUDE.md template.
Nested files and overrides
When a subdirectory has different commands or never-dos, put a second AGENTS.md there. Codex running from that directory loads the root file, then the nested one. If you need to replace the directory’s file without deleting it, use AGENTS.override.md in that folder — Codex will take the override and ignore the sibling AGENTS.md.
repo/
AGENTS.md # shared source of truth (Codex + others)
CLAUDE.md # @AGENTS.md + Claude-only notes
.cursor/rules/ # Cursor-only, path-scoped
services/payments/
AGENTS.md # payments commands and never-dos
Free files (MIT)
All of these live in the public eli-alvarado/agentkit-drawer repo:
- agent-guardrails.md — injection defense, ask-vs-act, uncertainty
- nextjs-supabase-rls.mdc — RLS bullets you can mirror into AGENTS.md
- godot-jam-timeline.md and agents-md-game-modding.md — game-shaped AGENTS.md starters
FAQ
What file does OpenAI Codex read?
Codex CLI reads AGENTS.md (and AGENTS.override.md when present) before it starts work. Personal defaults can live in ~/.codex/AGENTS.md. It does not read CLAUDE.md or Cursor .mdc rules.
Does Codex read CLAUDE.md or .cursor/rules?
No. Keep shared rules in AGENTS.md. Point Claude Code at that file with @AGENTS.md. Keep Cursor path rules in .cursor/rules/*.mdc.
Where should the Codex AGENTS.md template live?
Repo root, next to your lockfile. Nested AGENTS.md files refine the root file for a subdirectory. Codex concatenates from the Git root down to the working directory.
What is AGENTS.override.md?
In a given directory, it wins over AGENTS.md. Use it for a local or temporary override without deleting the shared file. Codex still takes only one instruction file per directory.
How is this different from Cursor rules?
AGENTS.md is unscoped plain Markdown. Cursor .mdc files add frontmatter so a rule loads only for matching paths. Shared facts belong in AGENTS.md; path-scoped extras belong in Cursor rules.
Want the whole drawer?
The Vibe Starter Rules Pack ($19) ships a ready AGENTS.md + CLAUDE.md pair, 8 scoped Cursor rules, 12 slash-command prompts, and launch checklists for Next.js + Supabase + Stripe — the file Codex actually reads, plus the tool-specific extras. The Agent Builder Prompt Pack ($29) is the system-prompt and eval kit for Codex-class agents.