# Set up AGENTS.md for Codex URL: https://developertoolkit.ai/en/codex/quick-start/agents-md/ Description: Write a global and a project AGENTS.md for Codex, check exactly what loaded with codex debug prompt-input, and prove the rules change what Codex does. `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](/en/codex/quick-start/first-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 (checked 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](/en/codex/build/agents-md-optimization/) 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: ```markdown # 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** ```text 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](/en/codex/quick-start/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. ```bash # terminal mkdir -p ~/.codex $EDITOR ~/.codex/AGENTS.md ``` ```markdown # 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. ```text 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: ```toml # ~/.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: ```bash # 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 `` 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. `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)** ```text 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: ```bash # 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](/en/codex/quick-start/review-workflow/). ## Add code review rules 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. For GitHub reviews, OpenAI's guide says: "Add a `## Code Review Rules` section to the file closest to the code the rules govern" (read 2026-10-13). Add a section the reviewer can act on: ```markdown ## Code Review Rules - 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](/en/codex/quick-start/github-integration/). ## 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 (v2.1.281 for Bedrock, Google Cloud, Foundry, LLM gateways and telemetry-off sessions), on both release channels (checked 2026-10-12); 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](/en/developer-scorecard-guide/claude-md-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](/en/codex/build/agents-md-optimization/) 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** ```text 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](/en/codex/quick-start/github-integration/) — Turn on @codex review and put your code review rules to work on pull requests. - [Optimize AGENTS.md and skills for Codex](/en/codex/build/agents-md-optimization/) — Keep the chain inside its budget, move procedures into skills, and fail CI before a file is truncated. - [Pruning CLAUDE.md and AGENTS.md](/en/workflows/context/pruning-context-files/) — The ablation protocol for deleting rules that no longer earn their place. - [Install and manage skills](/en/ecosystem/skills/installing-managing/) — Where skill files live for each tool, and how a team shares them.