YouTip

AGENTS.md is Codex's custom instruction file, allowing you to set global guidelines and workflow specifications for Codex.\n\nThis section details how to create and use AGENTS.md.\n\n* * *\n\n## What is AGENTS.md?\n\nCodex automatically reads the `AGENTS.md` file at startup. Through a hierarchical mechanism of "global configuration + project-level overrides", it ensures that every task inherits consistent working conventions, regardless of which code repository you open.\n\nAGENTS.md is an instruction file that Codex reads before executing any work, allowing you to:\n\n* Set global coding standards\n* Define project-specific workflows\n* Provide different guidelines for different directories\n* Standardize team development practices\n\n!(#)\n\n> Through AGENTS.md, you can ensure that Codex follows consistent standards across the entire codebase.\n\n* * *\n\n## How Codex Discovers Guidelines\n\nCodex builds an instruction chain according to the following priorities.\n\n### Three-Layer Loading Mechanism\n\n| Layer | Loading Rule | Description |\n| --- | --- | --- |\n| Global Layer | Reads `~/.codex/AGENTS.override.md` | If it does not exist, reads `~/.codex/AGENTS.md`, taking only the first non-empty file |\n| Project Layer | Scans from the Git root directory down to the current directory level by level | At each level, checks `AGENTS.override.md` → `AGENTS.md` → alternative filenames in `project_doc_fallback_filenames` in sequence |\n| Merge Layer | Concatenates from root to leaf in order | Files closer to the current directory appear later and have higher priority |\n\n> The total size limit after merging defaults to 32 KiB (controlled by `project_doc_max_bytes`); any excess will be truncated.\n\n* * *\n\n## Step 1: Create Global Configuration\n\nGlobal configuration applies to all projects and is suitable for placing general working conventions.\n\n### Create Configuration Directory\n\nmkdir -p ~/.codex\nEnsure the Codex home directory exists; all global configurations are placed in this directory.\n\n### Write Global Conventions\n\nCreate the `~/.codex/AGENTS.md` file and write conventions common to all projects:\n\n# ~/.codex/AGENTS.md## Global workflow convention - Always run npm test after modifying JavaScript files - Prefer pnpm when installing dependencies - Request confirmation before adding production dependencies\n### Verify Configuration is Effective\n\nRun the following command, and Codex should echo the entries you wrote:\n\ncodex --ask-for-approval never "Summarize the current instructions."\n> If you need a temporary global override, you can create `AGENTS.override.md`; deleting this file will restore the original configuration.\n\n* * *\n\n## Step 2: Configure by Repository Layers\n\nProject-level files make Codex follow repository-specific standards while still inheriting global configurations.\n\n### Add Repository-Level Conventions\n\nCreate `AGENTS.md` in the project root directory:\n\n# AGENTS.md## Repository convention - Run npm run lint before submitting PR - When modifying public utility behavior, simultaneously update documentation in docs/\n### Add Overrides for Subdirectories\n\nFor subdirectories with special requirements (e.g., `services/payments/`), create `AGENTS.override.md` for a local override:\n\n# services/payments/AGENTS.override.md## Payment service rule - Use make test-payments instead of npm test - Must notify the security channel before rotating API Keys\n### Complete Directory Structure\n\nThe following is a typical directory layout of a repository after loading `AGENTS.md`:\n\nrepo/├── AGENTS.md # Repository-level convention (loading)└── services/ ├── payments/ │ ├── AGENTS.md # Skipped (override takes precedence) │ └── AGENTS.override.md # Payment service override (loading) └── search/ └── AGENTS.md # Search service convention (loading)\n> In the same directory, when `AGENTS.override.md` exists, the peer `AGENTS.md` will be skipped.\n\n### Verify Loading Order\n\nStart Codex from a subdirectory to view the sources of loaded instructions:\n\ncodex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."\nExpected result: Lists the global file, repository root directory file, and payment service override file in sequence.\n\n* * *\n\n## Advanced Options\n\nThe following two features apply to scenarios where you need to further customize the instruction loading behavior.\n\n### Custom Filenames\n\nIf the project already has an established `TEAM_GUIDE.md`, you can append it to the fallback list in the configuration file, and Codex will treat it as an instruction file:\n\n# ~/.codex/config.toml# Append fallback filenames and increase merge limit project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] project_doc_max_bytes = 65536\nAfter modification, the check order for each directory becomes: `AGENTS.override.md` → `AGENTS.md` → `TEAM_GUIDE.md` → `.agents.md`, taking the first existing file.\n\n> You need to restart Codex after modifying the configuration for the `config.toml` changes to take effect.\n\n### Switch Configuration Directory\n\nThrough the `CODEX_HOME` environment variable, you can use an independent configuration profile for different projects or automation workflows:\n\nCODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"\nAt this point, Codex will read the global configuration from the `.codex` subdirectory of the current directory, instead of the default `~/.codex`.\n\n* * *\n\n## Verification and Debugging\n\nThe following commands can quickly check the currently active instruction sources.\n\n### Quick Check\n\n# Check global + project instructions from repository root codex --ask-for-approval never "Summarize the current instructions."# Check nested overrides from subdirectory codex --cd subdir --ask-for-approval never "Show which instruction files are active."\n### Enable Detailed Logging\n\nIf you need a detailed audit of the instruction loading process, you can enable TUI logging:\n\n# Output TUI logs to local directory codex -c log_dir=./.codex-log # Log file located at ./.codex-log/codex-tui.log\n\n* * *\n\n## Common Troubleshooting\n\nThe table below summarizes potential issues during configuration and troubleshooting directions.\n\n| Phenomenon | Troubleshooting Direction |\n| --- | --- |\n| Nothing loaded | Confirm the file is not empty; run `codex status` to check if the workspace root directory is correct |\n| Incorrect instructions appear | Check if there is a leftover `AGENTS.override.md` in a parent directory |\n| Fallback filenames not taking effect | Confirm the spelling in `config.toml` is correct, and restart Codex to make it effective |\n| Instruction content is truncated | Increase `project_doc_max_bytes`, or split large files into multi-level directories |\n| Profile confusion | Run `echo $CODEX_HOME` to confirm it points to the expected directory |