---
title: "What is AGENTS.md and how does Codex read it?"
description: "AGENTS.md is a Markdown file of instructions for coding agents. Codex reads one global file and one per directory, joins them, and stops at 32 KiB by default."
image: "https://bombos.ai/assets/og-en-v2.png"
---

# What is AGENTS.md and how does Codex read it?

Short answer

AGENTS.md is a plain Markdown file of instructions for coding agents: a README for agents, with no required fields. Codex first reads one global file from ~/.codex, then at most one AGENTS.md per directory from the project root down to your working directory. It joins them in order, the closest file last, and stops at 32 KiB by default.

*Piet Baudoin · published November 16, 2026 · November 16, 2026*

## What goes in AGENTS.md

AGENTS.md calls itself “a README for agents”. A README is for people: what the project is and how to get started. AGENTS.md is for the agent: how to build and test, what the code style is, what not to touch, what a pull request should look like. It is plain Markdown with no required fields.

The format is not OpenAI’s alone. It sits under the Agentic AI Foundation at the Linux Foundation and is read by Codex, Cursor, GitHub Copilot coding agent, Gemini CLI, Google Jules, Aider, Devin, Windsurf, Zed, Warp, VS Code and JetBrains Junie, among others. According to agents.md, more than 60,000 open-source projects use it.

## How Codex reads it, exactly

At the start of every session Codex builds an instruction chain in three steps.

1.  **Global.** In your Codex home directory (~/.codex, or the directory in CODEX\_HOME), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. Only the first non-empty file counts.
2.  **Project.** From the project root, usually the Git root, Codex walks down to the directory you are working in. In each directory it checks AGENTS.override.md, then AGENTS.md, then the names in `project_doc_fallback_filenames`. It takes at most one file per directory. Without a project root, Codex checks only the current directory.
3.  **Merge.** The files found are concatenated from the root down, separated by blank lines. A file closer to your working directory comes later and therefore wins on conflicting instructions. Empty files are skipped. Codex stops once the total reaches `project_doc_max_bytes`, 32 KiB by default.

| Setting in ~/.codex/config.toml | What it does | Default |
| --- | --- | --- |
| `project_doc_fallback_filenames` | Extra file names per directory, for example `["TEAM_GUIDE.md", ".agents.md"]` | None |
| `project_doc_max_bytes` | Cap on all instructions combined, for example `65536` | 32 KiB |

A change to the configuration or to an AGENTS.md needs a new session.

An example. You work in `services/payments/` of this repo:

```
~/.codex/AGENTS.md            personal preferences
repo/AGENTS.md                conventions for the whole repo
repo/services/AGENTS.md       conventions for all services
repo/services/payments/AGENTS.override.md   temporary deviation
```

Codex then joins them in this order: the global file, `repo/AGENTS.md`, `repo/services/AGENTS.md`, and the `AGENTS.override.md` in payments. An AGENTS.md next to that override in the same directory is skipped. To see what actually loaded, ask Codex at the start of a session to list the instructions it received.

## The misconception: everything in AGENTS.md gets through

Many teams keep adding to one large file and assume the agent reads all of it. Codex cuts the chain at 32 KiB, and what sits in the global and higher-level files comes before what sits deep in a subdirectory. A long global AGENTS.md can push a subdirectory’s instructions out of the window. Keep each file short and put specific rules in the directory where they apply; in a monorepo the nearest file wins. An explicit instruction in chat always overrides the file, according to agents.md.

## AGENTS.md next to CLAUDE.md

From version 2.1.277, Claude Code reads AGENTS.md as project instructions when there is no CLAUDE.md or CLAUDE.local.md in the working directory or the directories above it; the Project instructions setting can change that. If your repo already has a CLAUDE.md, put an `@AGENTS.md` line at the top: Claude Code then loads the shared file and does not read it twice. The other way round, Codex can read an existing CLAUDE.md if you add that name to `project_doc_fallback_filenames`. A team running [Codex and Claude Code side by side](https://bombos.ai/en/questions/codex/codex-vs-claude-code-for-teams/) then keeps its conventions in one place.

## What this means for a team

A committed AGENTS.md travels with the repo to everyone, alongside the README and other tracked documentation. Codex memories live on one machine, and OpenAI’s own advice is to keep required team guidance in AGENTS.md or checked-in documentation, not in memories. See [Does Codex remember previous work?](https://bombos.ai/en/questions/codex/does-codex-remember-previous-work-and-can-a-team-share-it/). But AGENTS.md is also manual work: someone has to write it, trim it and keep it current. It can hold decisions and point to other documents, but it does not fetch email or documents itself, and everything has to fit under the 32 KiB cap. How to capture that wider knowledge is in [How to give AI agents your company context](https://bombos.ai/en/knowledge-base/how-to-give-ai-agents-your-company-context/).

## Where Bombos fits

AGENTS.md gives every agent the same rules for one repo; Bombos gives every AI tool on the team one shared memory above that. It keeps the team’s knowledge and the rules the team learns, and reads what already exists in email, documents and repos, so Codex, Claude Code or Cursor can look it up without it having to fit in a 32 KiB file. One developer can try it first for their own agents.

## Related questions

What is the difference between AGENTS.md and AGENTS.override.md?

In the same directory AGENTS.override.md wins: if it exists, Codex skips the regular AGENTS.md there. Useful for a temporary or personal deviation without editing the shared file.

Does Claude Code read AGENTS.md?

Yes, from Claude Code v2.1.277, when there is no CLAUDE.md or CLAUDE.local.md in the working directory or the directories above it. If both exist, Claude Code reads only CLAUDE.md, unless it contains an @AGENTS.md import.

Can Codex read a file with another name, like CLAUDE.md?

Yes, through project\_doc\_fallback\_filenames in ~/.codex/config.toml. Codex tries those names in each directory when there is no AGENTS.override.md or AGENTS.md.

Why doesn't Codex see my change to AGENTS.md?

Codex builds the instruction chain when a session starts. Start a new session after a change, and check that the total stays under project\_doc\_max\_bytes.

## Sources

1.  [Custom instructions with AGENTS.md (Codex docs)](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
2.  [AGENTS.md](https://agents.md/)
3.  [How Claude remembers your project (Claude Code docs)](https://code.claude.com/docs/en/memory)
4.  [Codex memories (Codex docs)](https://learn.chatgpt.com/docs/customization/memories)

## What does your AI forget?

1.  01You tell us which AI you use and where it keeps starting over.
2.  02We show what a shared memory changes there, on your own examples.
3.  03You keep the plan, with or without Bombos.

![Piet Baudoin](https://bombos.ai/assets/team/piet-klein.jpg)

**Piet Baudoin**You talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe

## More questions about Codex

-   [What does a good AGENTS.md for Codex look like? An example](https://bombos.ai/en/questions/codex/agents-md-example-for-codex/)
-   [How much does Codex cost for a team?](https://bombos.ai/en/questions/codex/codex-pricing-for-teams/)
-   [Codex vs Claude Code: which should a team use?](https://bombos.ai/en/questions/codex/codex-vs-claude-code-for-teams/)
-   [Does Codex remember previous work, and can a team share that memory?](https://bombos.ai/en/questions/codex/does-codex-remember-previous-work-and-can-a-team-share-it/)

[All questions about Codex →](https://bombos.ai/en/questions/codex/)


---

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","url":"https://bombos.ai/","logo":"https://bombos.ai/assets/bombos-bee.png","description":"Bombos is the memory layer under every AI your team uses. One shared memory for Claude, ChatGPT, Copilot, Cursor and your own agents, that learns how you work.","sameAs":["https://www.linkedin.com/company/bombos-ai","https://www.youtube.com/@truebombos","https://www.instagram.com/truebombos/","https://bsky.app/profile/bombostrue.bsky.social","https://www.threads.com/@truebombos","https://mastodon.social/@Bombos","https://www.tiktok.com/@truebombos","https://t.me/truebombos","https://www.pinterest.com/truebombos/","https://github.com/bombos-ai","https://linktr.ee/bombos.ai","https://bombosai.substack.com","https://hashnode.com/@bombosai","https://hackernoon.com/u/bombos","https://dev.to/bombos"],"email":"info@bombos.ai","areaServed":["NL","Europe"],"knowsLanguage":["nl","en"],"contactPoint":{"@type":"ContactPoint","email":"info@bombos.ai","contactType":"sales","url":"https://bombos.ai/en/contact/","availableLanguage":["nl","en"]}},{"@type":"WebSite","@id":"https://bombos.ai/#website","name":"Bombos","url":"https://bombos.ai/","inLanguage":["nl-NL","en"],"publisher":{"@id":"https://bombos.ai/#organization"}}]}

{"@context":"https://schema.org","@type":"Article","headline":"What is AGENTS.md and how does Codex read it?","description":"AGENTS.md is a Markdown file of instructions for coding agents. Codex reads one global file and one per directory, joins them, and stops at 32 KiB by default.","abstract":"AGENTS.md is a plain Markdown file of instructions for coding agents: a README for agents, with no required fields. Codex first reads one global file from ~/.codex, then at most one AGENTS.md per directory from the project root down to your working directory. It joins them in order, the closest file last, and stops at 32 KiB by default.","datePublished":"2026-11-16T00:00:00.000Z","dateModified":"2026-11-16T00:00:00.000Z","author":{"@type":"Person","name":"Piet Baudoin"},"publisher":{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","logo":{"@type":"ImageObject","url":"https://bombos.ai/assets/bombos-bee.png"}},"image":"https://bombos.ai/assets/og-en-v2.png","mainEntityOfPage":"https://bombos.ai/en/questions/codex/what-is-agents-md-and-how-does-codex-read-it/","inLanguage":"en-US","isPartOf":{"@type":"CollectionPage","name":"Codex","url":"https://bombos.ai/en/questions/codex/"},"citation":[{"@type":"CreativeWork","name":"Custom instructions with AGENTS.md (Codex docs)","url":"https://learn.chatgpt.com/docs/agent-configuration/agents-md"},{"@type":"CreativeWork","name":"AGENTS.md","url":"https://agents.md"},{"@type":"CreativeWork","name":"How Claude remembers your project (Claude Code docs)","url":"https://code.claude.com/docs/en/memory"},{"@type":"CreativeWork","name":"Codex memories (Codex docs)","url":"https://learn.chatgpt.com/docs/customization/memories"}]}

{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Bombos","item":"https://bombos.ai/en/"},{"@type":"ListItem","position":2,"name":"Questions","item":"https://bombos.ai/en/questions/"},{"@type":"ListItem","position":3,"name":"Codex","item":"https://bombos.ai/en/questions/codex/"},{"@type":"ListItem","position":4,"name":"What is AGENTS.md and how does Codex read it?","item":"https://bombos.ai/en/questions/codex/what-is-agents-md-and-how-does-codex-read-it/"}]}

{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"What is the difference between AGENTS.md and AGENTS.override.md?","acceptedAnswer":{"@type":"Answer","text":"In the same directory AGENTS.override.md wins: if it exists, Codex skips the regular AGENTS.md there. Useful for a temporary or personal deviation without editing the shared file."}},{"@type":"Question","name":"Does Claude Code read AGENTS.md?","acceptedAnswer":{"@type":"Answer","text":"Yes, from Claude Code v2.1.277, when there is no CLAUDE.md or CLAUDE.local.md in the working directory or the directories above it. If both exist, Claude Code reads only CLAUDE.md, unless it contains an @AGENTS.md import."}},{"@type":"Question","name":"Can Codex read a file with another name, like CLAUDE.md?","acceptedAnswer":{"@type":"Answer","text":"Yes, through project_doc_fallback_filenames in ~/.codex/config.toml. Codex tries those names in each directory when there is no AGENTS.override.md or AGENTS.md."}},{"@type":"Question","name":"Why doesn't Codex see my change to AGENTS.md?","acceptedAnswer":{"@type":"Answer","text":"Codex builds the instruction chain when a session starts. Start a new session after a change, and check that the total stays under project_doc_max_bytes."}}]}
```
