DownloadCodex Unofficial guide
English

Give Codex standing instructions with AGENTS.md

Codex reads AGENTS.md files before doing any work. It first loads your global file from ~/.codex. Then it walks from the project root down to your current folder, adding one file per directory. Files closer to your folder appear later and so take priority. AGENTS.override.md replaces AGENTS.md in the same directory. The combined size is capped at 32 KiB by default.

How Codex finds instructions

  1. Global: in your Codex home (~/.codex), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. Only the first non-empty file counts.
  2. Project: starting at the project root, usually the Git root, Codex walks down to your current folder. In each folder it takes AGENTS.override.md, else AGENTS.md, else any fallback names you configured. That’s at most one file per folder.
  3. Merge: files are joined from the root down. Later files, closer to where you’re working, win when they conflict.

Empty files are skipped. Codex stops adding files at project_doc_max_bytes, which is 32 KiB by default.

A global file for your personal habits

# ~/.codex/AGENTS.md

## Working agreements
- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

A project file for the repository

# AGENTS.md

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

Overrides for one part of a monorepo

# services/payments/AGENTS.override.md

## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

These three examples are adapted from OpenAI’s AGENTS.md guide.

Check what Codex loaded

codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

Codex should list the global file first, then the repository file, then the closest override.

What to put in it

Include things you’d otherwise repeat: test and lint commands, package manager, code style rules, folders that are off-limits, and how to verify a change. Keep it short and concrete. Long prose gets truncated and is harder for the agent to follow.

Generate a starter file with our config generator.

Questions people ask

My repo already has TEAM_GUIDE.md. Can Codex use it?

Yes. Add it to project_doc_fallback_filenames in config.toml, for example project_doc_fallback_filenames = ["TEAM_GUIDE.md"], then restart Codex.

Do I need to clear a cache after editing AGENTS.md?

No. Codex rebuilds the instruction chain on every run and at the start of each TUI session. Restart Codex in the target folder.

Sources

We link to the official source for every instruction on this page. If anything here disagrees with them, trust the official source and tell us.

Read next