guides/agents-md.md Codex Docs, 2026-04-25 00:42 UTC → 2026-05-07 20:02 UTC

78 82 

79Here 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:

80 84 

81- AGENTS.md Repository expectations85<FileTree

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

83 87 tree={[

84 - payments/88 {

85 89 name: "AGENTS.md",

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

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

88 - README.md92 },

89 - search/93 {

90 94 name: "services/",

91 - AGENTS.md95 open: true,

92 - …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/>

93 121 

94## Customize fallback filenames122## Customize fallback filenames

95 123 

108 137 

109With 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:

110 139 

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

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

113- support/142 tree={[

114 143 {

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

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

117 146 highlight: true,

118 - …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/>

119 169 

120Set 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:

121 171