Skip to content
English
РусскийEnglish简体中文HindiEspañolPortuguês (BR)日本語FrançaisDeutsch한국어
Sign Up Free
Codex

What is AGENTS.md in Codex CLI?

Learn what AGENTS.md does in Codex CLI, how instruction hierarchy works, what to include, and common mistakes. Includes setup, examples, and common fixes.

Short answer

AGENTS.md is a project instruction file for Codex. It tells Codex about repository structure, commands, tests, coding style, commit rules, and collaboration preferences.

It is for stable project rules, not one-time tasks. Put one-time requirements in the current conversation.

What to include

  • How to install dependencies, start the project, and run tests
  • Common validation commands
  • Coding style and naming conventions
  • Directories that should not be changed casually
  • Required checks before finishing
  • Team preferences for communication and output

What not to include

  • API Keys, tokens, passwords, or private credentials
  • Temporary task instructions
  • Long product background stories
  • Generic prompts unrelated to the repository
  • Outdated commands and paths

Scope and precedence

Codex builds its initial instruction chain when a run starts. The launch directory matters:

  1. It first reads global guidance from CODEX_HOME, which defaults to ~/.codex: the first non-empty AGENTS.override.md or, otherwise, AGENTS.md.
  2. It then checks each directory from the project root, usually the Git root, down to the current working directory. Without a project root, it checks only the current directory for project guidance.
  3. In each project directory it uses at most one non-empty file: AGENTS.override.md first, then AGENTS.md, then names configured in project_doc_fallback_filenames.

More specific guidance later in the chain takes precedence where instructions conflict; unrelated parent rules still apply. An override replaces the ordinary file at the same directory level, not every instruction from its parents.

A directory example

~/.codex/AGENTS.md
repo/AGENTS.md
repo/services/payments/AGENTS.override.md
repo/services/payments/AGENTS.md
repo/services/search/AGENTS.md

Suppose global guidance says to use npm test, the repository file requires linting, and the payments override replaces the test command with make test-payments. When you launch from repo/services/payments, Codex loads the global file, the repository file, and the payments override. It keeps the lint rule, uses the payments test command, and skips the ordinary payments file. The sibling search file is outside that startup chain.

Suggested structure

Keep the template below short and replace its commands with commands that actually exist in your repository. A rule should say when it applies and how to check the result.

# Project instructions


## Build and test
- Run `npm test` before finishing behavior changes.
- Run `npm run lint` after editing TypeScript files.


## Style
- Keep diffs small and focused.
- Match existing component patterns.


## Safety
- Do not edit files outside this repository.
- Do not commit secrets.

Check missing or conflicting rules

After changing instructions, start a new session in the target directory and ask Codex to list its loaded sources and applicable commands:

Terminal window
codex -C /path/to/repo/services/payments "List the instruction files you loaded and the test command that applies here. Do not edit files."
  • Check the working directory and CODEX_HOME. Starting from the repository root does not preload every nested directory’s instructions.
  • Check the exact filename, non-empty contents, and any AGENTS.override.md at the same level. A fallback filename must appear in project_doc_fallback_filenames.
  • Inspect project_doc_max_bytes if long instructions are truncated. Shorten duplicated guidance and keep essential rules near the start.
  • For a conflict, identify both source files and the directory each rule governs. Put a narrow exception in the relevant directory instead of copying contradictory rules everywhere. Instruction files do not change sandbox permissions.

Common mistakes

  • Turning AGENTS.md into a very long universal prompt.
  • Writing secrets into the file.
  • Forgetting to update it when project commands change.
  • Mixing AGENTS.md with user-level config.toml.
  • Assuming rules remove the need to review diffs and tests.

About BetterToken

If a team uses BetterToken to unify model routing, AGENTS.md still matters. The API layer handles model requests and usage records. AGENTS.md handles project context and execution norms.

Use both to reduce configuration confusion and collaboration cost.

References