Codex AGENTS.md

AGENTS.md is Codex's custom instruction file that allows you to set global guidance and workflow conventions for Codex.

This section details how to create and use AGENTS.md.

---

What is AGENTS.md?

Codex automatically reads at startupAGENTS.mdfile, using the hierarchical mechanism of "global configuration + project-level overrides", so that every task inherits consistent working conventions no matter which code repository you open.

AGENTS.md is an instruction file that Codex reads before doing any work, allowing you to:

• Set global coding standards
• Define project-specific workflows
• Provide different guidance for different directories
• Standardize team development practices

With AGENTS.md, you can ensure Codex follows consistent conventions across the entire codebase.

---

How Codex discovers guides

Codex builds the instruction chain according to the following priorities.

Three-tier loading mechanism

Tier	Loading rule	Description
Global tier	Reads~/.codex/AGENTS.override.md	If it does not exist, reads~/.codex/AGENTS.md, takes only the first non-empty file
Project tier	Scans from the Git root directory level by level to the current directory	Checks each level in orderAGENTS.override.md → AGENTS.md → project_doc_fallback_filenamesalternate file names in
Merge tier	Concatenates from root to leaf in order	Files closer to the current directory appear later and have higher priority

The default total size limit after merging is 32 KiB (controlled byproject_doc_max_bytes), and the excess part will be truncated.

---

Step 1: Create global configuration

Global configuration applies to all projects and is suitable for universal working conventions.

Create a configuration directory

mkdir -p ~/.codex

Make sure the Codex home directory exists; all global configurations are placed in this directory.

Write global conventions

Create~/.codex/AGENTS.mdfile, write conventions common to all projects:

# ~/.codex/AGENTS.md

## 全局工作约定

- 修改 JavaScript 文件后，始终运行 npm test
- 安装依赖时优先使用 pnpm
- 新增生产依赖前先请求确认

Verify the configuration takes effect

Run the following command; Codex should echo the entries you wrote:

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

If you need a temporary global override, you can createAGENTS.override.md, and deleting that file restores the original configuration.

---

Step 2: Layer configuration by repository

Project-level files make Codex follow repository-specific conventions while still inheriting global configuration.

Add repository-level conventions

Create in the project root directoryAGENTS.md：

# AGENTS.md

## 仓库约定

- 提 PR 前运行 npm run lint
- 修改公共工具行为时，同步更新 docs/ 中的文档

Add overrides for subdirectories

For subdirectories with special needs (such asservices/payments/), createAGENTS.override.mdto perform local overrides:

# services/payments/AGENTS.override.md

## 支付服务规则

- 使用 make test-payments 替代 npm test
- 轮换 API Key 前必须通知安全频道

Complete directory structure

The following is a typical directory layout after a repository loadsAGENTS.md:

repo/
├── AGENTS.md                          # 仓库级约定（加载）
└── services/
    ├── payments/
    │   ├── AGENTS.md                  # 被跳过（override 优先）
    │   └── AGENTS.override.md         # 支付服务覆写（加载）
    └── search/
        └── AGENTS.md                  # 搜索服务约定（加载）

In the same directory,AGENTS.override.mdwhen it exists, the siblingAGENTS.mdwill be skipped.

Verify the loading order

Start Codex from a subdirectory and view the sources of loaded instructions:

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

Expected result: list the global file, repository root file, and payment service override file in order.

---

Advanced options

The following two features apply to scenarios where you need to further customize instruction loading behavior.

Custom file name

If the project already has a customaryTEAM_GUIDE.md, you can append it to the fallback list in the configuration file, and Codex will treat it as an instruction file:

# ~/.codex/config.toml
# 追加回退文件名并提高合并上限
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

After modification, the inspection order for each directory becomes:AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md, take the first existing file.

After modifying the configuration, you need to restart Codex to makeconfig.tomlthe changes take effect.

Switch configuration directory

ThroughCODEX_HOMEenvironment variable, you can use independent configuration profiles for different projects or automated processes:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

At this point, Codex will use the.codexsubdirectory under the current directory to read the global configuration, rather than the default~/.codex。

---

Verification and debugging

The following command can quickly check the source of currently active instructions.

Quick check

# 从仓库根目录检查全局 + 项目指令
codex --ask-for-approval never "Summarize the current instructions."

# 从子目录检查嵌套覆写
codex --cd subdir --ask-for-approval never "Show which instruction files are active."

Enable verbose logs

If you need to audit the instruction loading process in detail, you can enable TUI logging:

# 输出 TUI 日志到本地目录
codex -c log_dir=./.codex-log
# 日志文件位于 ./.codex-log/codex-tui.log

---

Troubleshooting common issues

The following table summarizes possible issues during configuration and troubleshooting directions.

Symptom	Troubleshooting direction
Nothing is loaded	Confirm the file is not empty; runcodex statusCheck whether the workspace root directory is correct
Incorrect instructions appeared	Check whether there are leftoverAGENTS.override.md
Fallback file name does not take effect	Confirmconfig.tomlspelling is correct in the , and restart Codex to make it take effect.
Instruction content is truncated	Increaseproject_doc_max_bytes, or split large files into multiple directory levels
Profile confusion	Runecho $CODEX_HOME, confirm it points to the expected directory

Other extensions