OpenAI Codex: `AGENTS.md` location, format and template

Where OpenAI Codex reads project instructions, whether it reads AGENTS.md, and what the format allows. From the official documentation, checked Oct 7, 2026. See also OpenAI Codex: pricing, popularity and alternatives.

Project files

AGENTS.md in each folder from the project root down to where you work; files closer to your folder come later and win
AGENTS.override.md replaces AGENTS.md at that level
Other names via project_doc_fallback_filenames in config.toml

Global (all projects)

~/.codex/AGENTS.md (or AGENTS.override.md) in $CODEX_HOME

AGENTS.md

✓ Native format.

Format and limits

At most one file per folder: AGENTS.override.md, then AGENTS.md, then the fallback names.
Combined instructions stop at project_doc_max_bytes, 32 KiB by default.
Plain Markdown, no front matter.

Sources: learn.chatgpt.com/docs/agent-configuration/agents-md

Templates

AGENTS.md for a TypeScript projectAGENTS.md

# AGENTS.md

## Project
One paragraph: what this repository does and who uses it.

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Tests: `pnpm test` (run before you finish)
- Lint and types: `pnpm lint && pnpm typecheck`

## Layout
- `src/app/`: routes and pages
- `src/lib/`: shared logic, no UI code
- `tests/`: mirrors `src/`

## Conventions
- TypeScript strict mode; avoid `any`.
- Follow the patterns already in `src/` before adding new ones.
- Small, focused functions; name things for what they do.

## Boundaries
- Never read or edit `.env*` files or commit secrets.
- Ask before adding a dependency or changing a public API.

## Done means
Tests pass, lint is clean, and the change is explained in the PR description.

AGENTS.md for a Python projectAGENTS.md

# AGENTS.md

## Project
One paragraph: what this package does.

## Commands
- Set up: `uv sync`
- Tests: `uv run pytest -q`
- Lint and format: `uv run ruff check . && uv run ruff format .`
- Types: `uv run mypy src`

## Conventions
- Python 3.12; type hints on every public function.
- Use `pathlib`, f-strings and dataclasses; no new global state.
- Tests live in `tests/` and name the behaviour they check.

## Boundaries
- Don't touch `migrations/` without asking.
- Never print or log secrets; config comes from environment variables.

Nested AGENTS.md in a monorepopackages/api/AGENTS.md

# API package

Applies to everything under `packages/api/`, on top of the root AGENTS.md.

- Run `pnpm --filter api test` instead of the full test suite.
- Handlers live in `src/routes/`, one file per resource.
- Validate every request body with the schemas in `src/schemas/`.
- Database access only through `src/db/`; no raw SQL in handlers.

Codex instruction settings~/.codex/config.toml

# Folders without AGENTS.md: read these names instead
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
# Raise the 32 KiB cap on combined instructions
project_doc_max_bytes = 65536

Written by AgentGid as a starting point; swap in your own commands and folders.

OpenAI Codex: AGENTS.md location, format and template