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
Posted on Oct 21 • Originally published at agentkitdrawer.com
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.
Codex builds an instruction chain once per run (in the TUI, once per session):
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.
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.
Enter fullscreen mode Exit fullscreen mode 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.
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.
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 Enter fullscreen mode Exit fullscreen mode Free files (MIT) All of these live in the public eli-alvarado/agentkit-drawer repo:
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.
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.
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.
Buy Vibe Starter · $19 Buy Agent Builder · $29
Not ready for a full pack? Start with One-File Agent Rules ($9), one universal AGENTS.md for any stack, or get the free Starter AGENTS.md by email.
Launch week: 30% off any kit with code LAUNCH at Stripe checkout, through Oct 28, 2026. 14-day refund.
Originally published at agentkitdrawer.com.