# AGENTS.md

> A plain Markdown file in a project that Codex reads before it starts, holding standing instructions like which tests to run and which conventions to follow.

**Category:** ChatGPT

**AGENTS.md is the onboarding note for [Codex](/glossary#codex).** Put your project's working agreements in it: the test command, the package manager, when to ask before adding a dependency, how things are named. Codex reads it before every task.

Files can sit at several levels. One in your Codex home folder carries your personal preferences everywhere; one in the project root sets the project rules; files deeper in the folder tree add specific rules for that part. The closer file wins. In the CLI, `/init` writes a first draft.

## At work

Tired of telling Codex "run npm test after every change"? Write it in AGENTS.md once and it does it every time.

## Often confused with

Custom instructions. [Custom instructions](/glossary#chatgpt-custom-instructions) are for ChatGPT in general; AGENTS.md is a file in a codebase, for Codex only, and it travels with the project.

## Related terms

- Codex
- Markdown
- Skill (ChatGPT)

## See it in a lesson

[Codex](/en/learn/chatgpt/advanced/codex)

## Further reading

- [AGENTS.md (ChatGPT Learn)](https://learn.chatgpt.com/codex/agent-configuration/agents-md): Where the file lives and how files combine.
- [Codex CLI (ChatGPT Learn)](https://learn.chatgpt.com/codex/cli): The /init command and other basics.
- [Codex quickstart (ChatGPT Learn)](https://learn.chatgpt.com/codex/quickstart): Getting started with Codex.

---

Last updated: 14/10/2026  
Source: Rollo Academy glossary