Set up AGENTS.md for Codex

AGENTS.md is the Markdown instruction file Codex adds to every session before it acts. Codex combines one global file from ~/.codex/ with at most one project file per directory, from the repository root down to the startup directory, so deeper files land later and win. Since Codex 0.150.0, a project you mark untrusted supplies no project files.

This page is for the developer setting up Codex on a real repository, and for the tech lead who will own that file for a team. You asked Codex to add an endpoint and it reached for Express in your Fastify service, then ran npm test in a pnpm workspace. The model is not the problem: nothing told it how this repository works.

What you’ll have after setting up AGENTS.md

• A short project AGENTS.md that states the commands, stack choices, and hard rules Codex cannot infer from the code.
• A global ~/.codex/AGENTS.md for your personal defaults, kept separate from team rules.
• A nested file for one package in a monorepo, and the difference between AGENTS.md and AGENTS.override.md.
• A deterministic check of what Codex loaded, plus a probe that shows whether the rules change behaviour.
• Three copy-paste prompts: draft the file, probe the rules, and audit the file for stale or conflicting lines.

You need Codex installed and signed in, and one task already run. If not, start with run your first Codex task.

How does Codex choose which AGENTS.md files to load?

Codex builds one instruction block at the start of each session. The behaviour below was reproduced in a scratch repository with Codex CLI 0.157.1 on 2026-09-26.

Layer	Where Codex looks	Rule
Global	~/.codex/ (or $CODEX_HOME)	AGENTS.override.md if it exists, otherwise AGENTS.md. One file.
Project root	Walks up from the startup directory to the first project_root_markers match (default .git)	The walk defines where the project chain starts.
Each directory, root to startup directory	That directory	The first that exists: AGENTS.override.md, then AGENTS.md, then each project_doc_fallback_filenames entry. One file per directory.
Budget	All project files together	project_doc_max_bytes, default 32,768 bytes (32 KiB). The global file sits outside it.
Trust	The project	A project marked untrusted loads only the global file (Codex 0.150.0 and later).

Two consequences matter on day one. First, AGENTS.override.md hides only the AGENTS.md in the same directory; the files above it still load. Second, when the chain runs over budget, Codex cuts the deepest file first, mid-sentence, with no message in the terminal (Codex CLI 0.157.1). The AGENTS.md optimization guide covers the budget in depth.

Draft the project AGENTS.md with /init

Start from a draft Codex writes, then cut it. A generated file lists everything the agent could see; your job is to keep only what it could not work out alone.

1. Open the repository root in a terminal and start Codex with codex. When Codex asks Trust this folder?, accept it. An untrusted project never loads its project files, so the file you write would never load.

2. Type /init at the Codex prompt. Codex scans the repository and writes an AGENTS.md at the root.

3. Cut the draft to the lines that pass this test: “Would Codex get this wrong without the line?” Framework names that are obvious from package.json usually fail it. The exact test command, forbidden libraries, and directories never to edit usually pass.

4. Commit the file, and add it to CODEOWNERS so a named owner approves every change. The file steers every session on the repository, so it deserves the same review as CI config.

A project file that survives that cut is short. This one is for a Fastify API in a pnpm workspace:

# Orders API

## Commands
- Install: `pnpm install --frozen-lockfile`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Full gate before you say you are done: `pnpm typecheck && pnpm lint && pnpm test`

## Hard rules
- The HTTP framework is Fastify. Never add Express or its middleware.
- Validate every request body with the Zod schemas in `src/schemas/`.
- Log with the `pino` instance from `src/logger.ts`. No `console.log` in `src/`.
- Never edit files under `src/generated/`; run `pnpm codegen` instead.

## Definition of done
- A new endpoint ships with a test in `tests/routes/` that fails without the change.
- Report the gate output. If a command fails, say so; do not claim success.

Copy-paste prompt: draft an AGENTS.md you can trust

Draft an AGENTS.md for this repository. Read package manifests, lockfiles,
CI workflows and lint/test config before writing anything.

Include only:
1. The exact install, single-test, and full-gate commands, copied from CI.
2. Hard rules a reader could not infer from the code (forbidden libraries,
   generated directories, logging and validation conventions).
3. A short definition of done that names the commands to run.

Rules for you: imperative sentences, no more than 40 lines, no framework
descriptions a manifest already states. After the file, list every line you
inferred rather than read from a config file, with the file you would check.
Do not write the file yet; show it to me first.

The last instruction matters. A draft that separates what it read from what it guessed tells you exactly which lines to check before you commit.

What belongs in AGENTS.md, and what belongs somewhere else?

AGENTS.md is advice the model reads. Anything that must hold every time belongs in a mechanism that fails loudly instead.

The rule	Put it in	Why
“Run pnpm test before finishing”	AGENTS.md, and the same command in CI	Codex follows it most of the time; CI enforces it every time.
“No console.log in src/”	A lint rule, plus one line in AGENTS.md	The lint gate catches the miss the model makes.
A 12-step release or migration procedure	A skill in .agents/skills/	It loads only when the task needs it, instead of on every turn.
Sandbox, approvals, allowed model	config.toml	Those are settings Codex enforces, not advice. See Codex configuration.

Add a global AGENTS.md for your personal defaults

The global file follows you into every repository, so it holds preferences about how you work, never facts about one project. Keep it to a handful of lines; it loads in every session.

# terminal
mkdir -p ~/.codex
$EDITOR ~/.codex/AGENTS.md

# Personal defaults
- Before you change more than three files, show me a plan and wait.
- Prefer small commits with conventional messages (feat:, fix:, chore:).
- Never push, force-push, or open a pull request unless I ask.
- When a repository's AGENTS.md disagrees with this file, follow the repository.

The last line settles conflicts in writing. The project file already loads later and usually wins, but saying so removes the guesswork. For a temporary personal change, create ~/.codex/AGENTS.override.md; it replaces the global AGENTS.md until you delete it.

Add a nested AGENTS.md for one package in a monorepo

In a monorepo, one package often breaks the root’s rules. Put a file in that package and start Codex from inside it.

repo/
  AGENTS.md                  # workspace-wide rules, always loaded
  packages/
    billing/
      AGENTS.md              # adds billing rules on top of the root
    legacy-api/
      AGENTS.override.md     # wins over legacy-api/AGENTS.md
      AGENTS.md              # ignored while the override exists

Started from packages/billing/, Codex loads the global file, then the root AGENTS.md, then packages/billing/AGENTS.md. Started from the repository root, it loads no package file at all, because the walk stops at the startup directory. That is the most common reason a package rule “does not work”.

Use AGENTS.override.md sparingly, for a temporary phase such as a migration, and put the removal condition in its first line. It is easy to forget, and it keeps hiding the AGENTS.md beside it until someone deletes it.

If your team already keeps agent guidance in another file, list it as a fallback in ~/.codex/config.toml rather than duplicating it:

~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md"]

Codex checks the fallback names only when a directory has neither AGENTS.override.md nor AGENTS.md.

Check exactly what Codex loaded

Asking Codex “which instruction files did you load?” gets you the model’s recollection. codex debug prompt-input prints the prompt Codex would send, as JSON, without calling the model:

# terminal, from the directory where you normally start Codex
codex debug prompt-input "ping" > /tmp/codex-prompt.json
jq -r '.. | .text? // empty | select(startswith("# AGENTS.md instructions"))' /tmp/codex-prompt.json

The output is one <INSTRUCTIONS> block, printed with real line breaks. Your global file comes first, then a --- project-doc --- separator, then each project file from root to startup directory. From packages/billing/ in the tree above, you should see three sections. If the project files are missing, the folder is marked untrusted. If the last file ends mid-sentence, you are over budget.

Note

codex debug prompt-input has no --cd flag in Codex CLI 0.157.1. Change into the directory first: (cd packages/billing && codex debug prompt-input "ping").

Prove the rules change what Codex does

A file that loads is not yet a file that works. Probe the hard rules with a read-only run, and compare the answer with what you expect before you trust the file with real tasks.

Copy-paste prompt: probe your AGENTS.md rules (read-only)

Do not edit any files. For each task below, state the exact commands you
would run, the files you would touch, and quote the AGENTS.md line that
decided each choice. If no line applies, say "no instruction" instead of
guessing.

1. Add a POST /refunds endpoint with request validation.
2. Fix a failing test in tests/routes/orders.test.ts.
3. Update a type that lives in src/generated/.

Save the prompt above as probe.txt at the repository root. Run it non-interactively so the answer is repeatable:

# terminal, repository root
codex exec --sandbox read-only "$(cat probe.txt)"

Each “no instruction” answer is a gap you either accept or close with one line. Each answer that quotes the wrong line is a conflict to fix. Keep probe.txt in the repository and rerun it whenever someone edits AGENTS.md.

The probe tells you Codex intends to follow the file. The gates prove it did. Keep the commands from your “Definition of done” in CI, so a session that ignored a rule fails the build rather than a reviewer’s attention span. For review without reading every line, see review Codex’s changes before you commit.

Add review guidelines Codex applies to pull requests

Codex review reads the same files. The review instructions built into Codex CLI 0.157.1 tell the reviewer to use the root and scoped instruction files that apply to the changed files, with more-specific guidance winning on conflict. Add a section the reviewer can act on:

## Review guidelines
- Flag any route in src/routes/ registered without the auth preHandler.
- Flag SQL built with string concatenation instead of the query builder.
- Treat a missing test for a new endpoint as a P1 finding.

Try it locally before you push with codex review --base main. To run the same rules on GitHub with @codex review, follow connect Codex to GitHub.

Share one AGENTS.md with Claude Code

AGENTS.md is not Codex-only. Claude Code reads AGENTS.md when a repository has no CLAUDE.md, from v2.1.277 on the latest release channel (v2.1.281 for Bedrock, Google Cloud, Foundry, LLM gateways and telemetry-off sessions; checked 2026-09-26); the toggle sits under “Project instructions” in /config. A team that uses both tools can keep one file instead of two that drift apart. For the cross-tool view, see AGENTS.md and CLAUDE.md as concise repository context.

Why is Codex ignoring my AGENTS.md?

Most failures are loading problems, not model problems. Check them in this order.

Symptom	Cause	Recovery
Only your global rules show up in codex debug prompt-input	The project is marked untrusted	Relaunch codex in the folder and accept Trust this folder?, or set trust_level = "trusted" under [projects."/absolute/path"] in ~/.codex/config.toml.
A package’s rules never apply	You started Codex from the repository root	Start Codex in the package directory. Put rules that must apply everywhere in the root file.
A directory’s AGENTS.md is ignored	An AGENTS.override.md sits beside it, possibly empty	Delete the override, or merge its content and delete it.
The deepest file stops mid-sentence	The chain exceeds project_doc_max_bytes	Cut the root file first. Raising the limit hides the problem; the optimization guide has a CI budget check.
Your edits to ~/.codex/AGENTS.md have no effect	CODEX_HOME points somewhere else	Run echo $CODEX_HOME. Codex reads the global file from that directory when it is set.
The file loads but Codex still breaks a rule	The rule is vague, or another line contradicts it	Rewrite it as an imperative with a concrete path or command, then back it with a lint rule or test.
Codex runs a command that no longer exists	The file went stale after a tooling change	Run the audit prompt below after every change to package.json scripts or CI.

Copy-paste prompt: audit AGENTS.md for stale and conflicting rules

Audit every AGENTS.md and AGENTS.override.md in this repository, plus
~/.codex/AGENTS.md. Do not edit anything. Report:

1. Commands that do not exist in package.json scripts, the Makefile, or CI.
2. Pairs of lines that contradict each other, with both file paths.
3. Lines that restate what a manifest or config file already makes obvious.
4. Any AGENTS.override.md, with the AGENTS.md it currently hides.

End with a proposed diff that removes or fixes each item, smallest first.

Where to go next with AGENTS.md

Connect Codex to GitHub Turn on @codex review and put your review guidelines to work on pull requests.

Optimize AGENTS.md and skills for Codex Keep the chain inside its budget, move procedures into skills, and fail CI before a file is truncated.

Pruning CLAUDE.md and AGENTS.md The ablation protocol for deleting rules that no longer earn their place.

Install and manage skills Where skill files live for each tool, and how a team shares them.