guides/agents-md.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-07 20:02 UTC

1# Custom instructions with AGENTS.md1# Custom instructions with AGENTS.md

2 2 

3Give Codex extra instructions and context for your project

4 

5Codex reads `AGENTS.md` files before doing any work. By layering global guidance with project-specific overrides, you can start each task with consistent expectations, no matter which repository you open.3Codex reads `AGENTS.md` files before doing any work. By layering global guidance with project-specific overrides, you can start each task with consistent expectations, no matter which repository you open.

6 4 

7## How Codex discovers guidance5## How Codex discovers guidance

80 82 

81Here is a sample repository after you add a global file and a payments-specific override:83Here is a sample repository after you add a global file and a payments-specific override:

82 84 

83- AGENTS.md Repository expectations85<FileTree

84- services/86 class="mt-4"

85 87 tree={[

86 - payments/88 {

87 89 name: "AGENTS.md",

88 - AGENTS.md Ignored because an override exists90 comment: "Repository expectations",

89 - AGENTS.override.md Payments service rules91 highlight: true,

90 - README.md92 },

91 - search/93 {

92 94 name: "services/",

93 - AGENTS.md95 open: true,

94 - …96 children: [

97 {

98 name: "payments/",

99 open: true,

100 children: [

101 {

102 name: "AGENTS.md",

103 comment: "Ignored because an override exists",

104 },

105 {

106 name: "AGENTS.override.md",

107 comment: "Payments service rules",

108 highlight: true,

109 },

110 { name: "README.md" },

111 ],

112 },

113 {

114 name: "search/",

115 children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }],

116 },

117 ],

118 },

119 ]}

120/>

95 121 

96## Customize fallback filenames122## Customize fallback filenames

97 123 

110 137 

111With the fallback list in place, Codex treats the alternate files as instructions:138With the fallback list in place, Codex treats the alternate files as instructions:

112 139 

113- TEAM\_GUIDE.md Detected via fallback list140<FileTree

114- .agents.md Fallback file in root141 class="mt-4"

115- support/142 tree={[

116 143 {

117 - AGENTS.override.md Overrides fallback guidance144 name: "TEAM_GUIDE.md",

118 - playbooks/145 comment: "Detected via fallback list",

119 146 highlight: true,

120 - …147 },

148 {

149 name: ".agents.md",

150 comment: "Fallback file in root",

151 },

152 {

153 name: "support/",

154 open: true,

155 children: [

156 {

157 name: "AGENTS.override.md",

158 comment: "Overrides fallback guidance",

159 highlight: true,

160 },

161 {

162 name: "playbooks/",

163 children: [{ name: "…", placeholder: true }],

164 },

165 ],

166 },

167 ]}

168/>

121 169 

122Set the `CODEX_HOME` environment variable when you want a different profile, such as a project-specific automation user:170Set the `CODEX_HOME` environment variable when you want a different profile, such as a project-specific automation user:

123 171