# AGENTS.md — the instructions Codex reads every time

Course: Codex from Zero — https://zero2vibecode.com/learn/codex
Canonical URL: https://zero2vibecode.com/learn/codex/0-3-agents-md
Verified against: Codex CLI v0.163.0 (2026-10-22)
Last updated: 2026-10-22

Codex reads AGENTS.md files before it does any work: one in your Codex home folder, then one per folder from the project root down to where you are. Write the things you would otherwise repeat every session, and keep the file short.

Three sessions in, you notice you keep typing the same sentences. Use pnpm, not npm. Run the tests before saying it is done. Do not touch the generated folder.

Write them down once instead.

## What AGENTS.md is

A plain Markdown file in your project. Codex reads AGENTS.md files before doing any work, so whatever is in them shapes every task without you repeating it.

There is no special syntax. Headings and bullet points are fine. The Codex docs' own example looks like this:

```text
# AGENTS.md

## Repository expectations

- Run npm run lint before opening a pull request.
- Document public utilities in docs/ when you change behavior.
```

## Where Codex looks, and in what order

When it starts, Codex builds a chain of instructions:

1. **Your global file.** In your Codex home folder, `~/.codex/AGENTS.md`. Preferences that should follow you into every repository go here.
2. **The project, folder by folder.** Starting at the project root — usually the root of the Git repository — Codex walks down to the folder you are in and picks up an AGENTS.md in each one along the way.
3. **Root first, nearest last.** The files are joined in that order. Something closer to your current folder appears later, so where two files disagree, the closer one wins.

Two details matter in practice. A folder can hold an `AGENTS.override.md`, which Codex reads instead of that folder's AGENTS.md. And Codex builds this chain once, when it starts: after editing a file, restart Codex in the folder you are working in.

## Let it draft one

Inside a session, `/init` generates an AGENTS.md scaffold in the current folder. Use it, and then read every line. A generated file full of confident, wrong statements about your project is worse than no file.

To check what Codex actually loaded, the docs suggest asking it from the repository root:

```bash
codex --ask-for-approval never "Summarize the current instructions."
```

## What earns a line

The test: *would I otherwise say this at the start of every session?*

- **Commands.** How to run the tests, the build, the linter. This turns "it suggests a command" into "it runs the right one".
- **Boundaries.** Generated folders, vendored code, anything that must not be edited by hand.
- **Conventions you cannot see in the code.** "Dates are stored as UTC strings."

And keep it short. Codex stops adding files once the combined instructions reach a size limit, and long before that, every line is competing with the actual task for attention.

Write the exercise version in the terminal: the test command and one hands-off folder.

**Switching from another agent.** 
Rules kept in another agent's file, such as CLAUDE.md, are not what Codex reads by default. If your repository already keeps its rules under a different name, you can add that name to `project_doc_fallback_filenames` in `~/.codex/config.toml`, and Codex will treat it like an AGENTS.md.

**Should AGENTS.md be committed to Git?**

Yes, for project rules: everyone on the project gets the same instructions, and they change together with the code. Personal preferences belong in ~/.codex/AGENTS.md instead.

**Do other tools read AGENTS.md too?**

AGENTS.md is a plain Markdown convention with its own site at agents.md, which the Codex docs point to. Whether another agent reads it by default is up to that agent, so check its documentation for the file it loads rather than assuming.