AGENTS.md for OpenAI Codex: Complete Setup and Configuration Guide (2026)

AGENTS.md is the instruction file OpenAI Codex reads before it touches your code. Get this file right and Codex operates with accurate context from the first prompt. Get it wrong — or skip it entirely — and you will spend your sessions correcting mistakes that could have been avoided. This guide covers everything you need: where the file lives, how Codex discovers it, how to write instructions that actually land, and real examples from production repositories.

What Is AGENTS.md?

AGENTS.md is a plain Markdown file that tells AI coding agents how your project works. Originally popularized by OpenAI’s Codex CLI, the format has since been adopted as an open standard by the Agentic AI Foundation (a directed fund under the Linux Foundation) and is now supported across Codex, Cursor, Gemini CLI, Windsurf, GitHub Copilot, and dozens of other tools.

Think of it as a README written specifically for AI agents rather than humans. Where a README explains what a project does, AGENTS.md explains how the project should be worked on: what commands to run, what conventions to follow, what to never touch.

For Codex specifically, the file does something more concrete: it is concatenated directly into the context window at the start of every session. That means whatever you put in AGENTS.md is the first thing Codex reads before it sees any of your prompts.

How Codex Discovers AGENTS.md Files

Codex does not just read one AGENTS.md file — it builds an instruction chain by walking the filesystem. Understanding this hierarchy is the key to using the format effectively.

When you start a Codex session, it runs through the following discovery sequence:

Step 1: Global scope

Codex checks your Codex home directory, which defaults to ~/.codex/. It looks for files in this order:

1. ~/.codex/AGENTS.override.md — if this exists, it is read and the regular AGENTS.md at this level is skipped
2. ~/.codex/AGENTS.md — your global personal instructions

Step 2: Project scope

Starting at your Git repository root, Codex walks down the directory tree toward your current working directory. At each level, it checks:

1. AGENTS.override.md — takes precedence, skips regular AGENTS.md at this level
2. AGENTS.md — the standard file
3. Any filenames listed in project_doc_fallback_filenames (configured in config.toml)

Step 3: Merge

All discovered files are concatenated in order from root to current directory. Files discovered later — that is, closer to your current directory — appear later in the combined prompt. Since language models weight recent context more heavily, deeper files naturally take precedence.

Here is what this looks like in a monorepo:

~/.codex/AGENTS.md          ← loaded first (global)
repo-root/AGENTS.md         ← loaded second
repo-root/packages/api/AGENTS.md  ← loaded third (if working here)

When you run Codex from packages/api/, all three files load. When you run it from the repo root, only the first two load. The packages/api/AGENTS.md never loads when you are working outside that directory.

The 32 KiB limit

Codex stops reading AGENTS.md files once it has accumulated project_doc_max_bytes worth of content (32 KiB by default). If your combined files exceed this limit, files discovered later — the ones with project-specific context — may be partially or fully dropped. This is the most common cause of “Codex is ignoring my project instructions” complaints.

Keep your global AGENTS.md lean (under 2-3 KB) so project-level files always fit within the budget.

The Override Mechanism

The AGENTS.override.md filename deserves its own section because it changes how merging works.

At any level where Codex finds AGENTS.override.md, it reads that file and skips any AGENTS.md at the same level. The override file is not additive — it replaces the regular file at its scope level.

This is useful in two scenarios:

Temporary overrides: You want to run Codex with different global instructions without modifying your permanent ~/.codex/AGENTS.md. Drop an AGENTS.override.md in ~/.codex/, run your session, then delete it.

Package-level replacement: In a monorepo where the root AGENTS.md defines general rules, a subdirectory with fundamentally different requirements can use AGENTS.override.md to replace rather than extend the root file’s instructions.

Configuring Discovery with config.toml

Codex’s AGENTS.md discovery behavior is configurable via ~/.codex/config.toml. Two settings matter:

# ~/.codex/config.toml

# Increase the instruction budget if your projects have large AGENTS.md files
project_doc_max_bytes = 65536  # 64 KiB

# Fall back to alternative filenames when AGENTS.md doesn't exist
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".codex/instructions.md"]

# Use a non-default Codex home directory
# Can also be set via CODEX_HOME environment variable

The project_doc_fallback_filenames setting is particularly useful for teams adopting AGENTS.md incrementally. If you already have a CONTRIBUTING.md with instructions that would work for agents, add it as a fallback rather than duplicating content.

project_doc_fallback_filenames = ["CONTRIBUTING.md", "docs/DEVELOPMENT.md"]

Note that fallback filenames are tried in order, and only the first match at each directory level is used.

What to Put in AGENTS.md

The content question is where most guides go wrong. They either list everything (“include your entire dev setup”) or nothing (“keep it minimal”). The right answer depends on what you are trying to accomplish.

The essential commands block

This is non-negotiable. Codex needs to know how to run your project before it can do anything useful. Put build, test, lint, and start commands at the top:

## Commands

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Type check: `npm run typecheck`
- Start dev server: `npm run dev`

For monorepos, be specific about where commands run from:

## Commands

Run from the repo root unless specified.

- Build all: `pnpm build --recursive`
- Build one package: `cd packages/api && pnpm build`
- Test all: `pnpm test --recursive`
- Lint: `pnpm lint` (ESLint across all packages)

Do not use npm — this repo uses pnpm workspaces.

That last line matters more than it looks. Codex will default to npm unless you tell it not to.

Project structure

Agents need to know where things live. Without this, they will create files in the wrong places:

## Project Structure

src/
  api/          # Express route handlers — one file per resource
  services/     # Business logic — no database access here
  repositories/ # All database queries live here
  models/       # TypeScript interfaces and Zod schemas
  middleware/   # Express middleware

tests/ mirror src/ structure (co-located .test.ts files are also fine)

Do not add business logic to route handlers. It belongs in services/.

Conventions that are not obvious from code

Things like “we use pnpm, not npm” and “tests go in tests/, not co-located” are not discoverable by reading the code. They need to be in AGENTS.md:

## Conventions

- TypeScript strict mode is on — no `any` types except in test files
- Error handling: always use `Result<T, E>` pattern, never throw
- Database: use repository pattern, never query directly from services
- Environment variables: access via `config.ts`, never `process.env` directly
- Imports: use path aliases (@/services, @/models), not relative paths

What NOT to put in AGENTS.md

Just as important as what to include:

• No style manifesto. “Write clean, readable code” tells Codex nothing. Be specific or skip it.
• No secrets or credentials. AGENTS.md is a file you commit to version control.
• No extensive documentation. If it reads like a README, it belongs in a README. AGENTS.md is operational, not explanatory.
• No vague policies. “Follow best practices” is noise. “Run npm run lint --fix before committing” is useful.

Five Real AGENTS.md Examples from the Gallery

The following examples are drawn from production repositories. We curate these in our gallery — the examples below link directly to the source rules.

1. Minimal open-source project

The AGENTS.md specification repository itself ships a minimal AGENTS.md that focuses purely on the essentials:

# AGENTS.md

## Dev environment tips
- Use Node.js 20+
- Run `npm install` to install dependencies

## Testing instructions
- Run tests with `npm test`
- All PRs require passing tests

## PR instructions
- Keep PRs focused on a single change
- Update tests when modifying behavior

This is intentionally lean. For a widely-adopted open standard with contributors from many companies, maximal clarity beats maximal detail.

2. Codex-optimized project configuration

The OpenAI Codex AGENTS.md guide in our gallery shows what OpenAI’s own team recommends:

# ~/.codex/AGENTS.md (global)

## My Standards

- TypeScript strict mode on all new projects
- Explicit return types on all exported functions
- Error handling: prefer explicit errors over exceptions
- Package manager: use the one already in the project's lockfile

## Testing

- Write tests for every public function
- Use the project's existing test runner; don't introduce new ones
- Name tests with "should [behavior] when [condition]"

The key insight here: global AGENTS.md defines personal standards, not project specifics. Project specifics go in the repo.

3. E-commerce TypeScript monorepo

The YourNextStore AGENTS.md demonstrates how to handle a Next.js + SDK combination:

# AGENTS.md

Your Next Store -- e-commerce app built with Next.js App Router + Commerce Kit SDK.

## Commands

bun dev           # Dev server (port 3000)
bun run build     # Production build
bun run lint      # Biome lint (--write to auto-fix)
bun run format    # Biome format
bun test          # Run tests (bun:test)
tsgo --noEmit     # Type check

## Key Files

app/              # Pages, layouts, server actions (App Router)
components/ui/    # Shadcn UI components (50+)
lib/commerce.ts   # Commerce API client — single source of truth for all API calls

## Rules

- Use `bun` not `npm` or `yarn`
- Server components by default; use 'use client' only when necessary
- All Commerce API calls go through lib/commerce.ts

4. Turborepo monorepo

The Turborepo AGENTS.md shows how to handle cross-package rules:

# AGENTS.md

## Monorepo Structure

apps/
  web/          # Next.js frontend
  api/          # Express API server
packages/
  ui/           # Shared React components
  config/       # Shared ESLint, TypeScript configs

## Rules

- NEVER import from apps/ into packages/
- All shared code goes in packages/
- Use workspace protocol for internal deps: "@repo/ui": "workspace:*"
- Changes to packages/ must not break any app

## Development

turbo dev     # Start all apps in parallel
turbo build   # Build all packages and apps
turbo test    # Run all tests

5. Multi-agent production setup

The Everything Claude Code AGENTS.md (28 sub-agents) shows what an advanced multi-agent setup looks like:

# AGENTS.md

## Core Principles

1. Agent-First — Delegate to specialized agents for domain tasks
2. Test-Driven — Write tests before implementation, 80%+ coverage required
3. Security-First — Never compromise on security; validate all inputs
4. Plan Before Execute — Plan complex features with architecture review first

## Agent Delegation

- security tasks → invoke security-auditor agent
- test generation → invoke test-generator agent
- documentation → invoke docs-writer agent
- pre-deploy checks → always invoke pre-deploy-checker before deployer

This pattern separates “when to invoke which agent” from general project conventions, keeping the instruction file navigable.

AGENTS.md vs CLAUDE.md vs .cursorrules

Developers working across multiple AI tools frequently ask which instruction file they should use. Here is a direct comparison:

When to use AGENTS.md: You are using Codex, or you want a single instruction file that works across multiple tools (Codex, Cursor, Gemini CLI, Windsurf). AGENTS.md is the format most likely to be read by whichever tool your team adopts next.

When to use CLAUDE.md: You are exclusively using Claude Code and want access to Claude-specific features like hooks integration, tool permissions, and the import system. CLAUDE.md supports a more sophisticated configuration surface but only works with Claude Code.

When to use .cursorrules: You are exclusively using Cursor. The format is simple and effective for single-tool setups but offers no path to portability.

Using both AGENTS.md and CLAUDE.md: This is common in teams that use Codex for some tasks and Claude Code for others. AGENTS.md handles the universal layer (commands, conventions, project structure). CLAUDE.md handles Claude-specific configuration (hooks, memory files, tool restrictions). There is intentional redundancy between the two files — that is expected and correct.

We cover this comparison in depth in our AGENTS.md vs CLAUDE.md guide.

Common Mistakes

Mistake 1: Putting everything in the global file

~/.codex/AGENTS.md should contain personal preferences that apply to all your projects, not project-specific instructions. “Use TypeScript strict mode” is a reasonable global rule. “Run cd packages/api && pnpm test to test the authentication service” is not.

When project-specific instructions are in the global file, they add noise for every project and can conflict with instructions in a project’s own AGENTS.md.

Mistake 2: Exceeding the 32 KiB budget with verbose global instructions

Every byte in ~/.codex/AGENTS.md is a byte that cannot be used by project-level files. If your global file is 20 KB, a deeply nested project file might get truncated. Write global instructions concisely. One hundred lines is plenty.

Mistake 3: Forgetting the override file doesn’t extend — it replaces

A common misuse: creating AGENTS.override.md with only the lines you want to change, expecting it to extend the regular AGENTS.md. It does not. It replaces the file at its level entirely. If you want to extend, use AGENTS.md (which concatenates with parent files). If you want to replace, use AGENTS.override.md.

Mistake 4: Vague constraints without actionable specifics

# Bad
Do not break existing functionality.

# Good
Before making changes to lib/auth.ts, run `npm run test:auth`
and confirm all tests pass. Failing auth tests block all merges.

The first line sounds professional but tells Codex nothing it did not already know. The second gives Codex a concrete action, a specific file, and a clear boundary condition.

Mistake 5: Not verifying what Codex actually reads

You can ask Codex to summarize its current instructions before doing any work:

codex --ask-for-approval never "Summarize the instructions you have loaded for this session"

Run this after setting up your AGENTS.md to confirm discovery is working as expected. If key instructions are missing, you likely have a size limit issue or a path discovery problem.

Structuring AGENTS.md for Monorepos

Monorepos benefit most from the hierarchical AGENTS.md pattern, but they also have the most surface area for things to go wrong.

The recommended approach:

Root AGENTS.md: Universal conventions, top-level commands, rules that apply everywhere.

# AGENTS.md (root)

## Workspace Rules

- Package manager: pnpm workspaces (never npm or yarn)
- Internal packages use workspace protocol: `"@acme/utils": "workspace:*"`
- Never import across app boundaries
- Every PR needs passing tests in affected packages

## Top-level Commands

- Install: `pnpm install`
- Build all: `pnpm build --recursive`
- Test all: `pnpm test --recursive`
- Lint: `pnpm lint`

Package-level AGENTS.md: Package-specific commands, conventions, and constraints that override or extend the root:

# packages/api/AGENTS.md

## API Package

Express + TypeScript REST API. Talks to PostgreSQL via Prisma.

## Commands (run from packages/api/)

- Start: `pnpm dev`
- Test: `pnpm test`
- Migrations: `pnpm prisma migrate dev`
- Generate types: `pnpm prisma generate`

## Conventions

- Routes in src/routes/ (one file per resource)
- Business logic in src/services/ (never in routes)
- Database access only in src/repositories/
- No direct process.env access — use src/config.ts

## Boundaries

Never modify packages/ui/ or packages/config/ from this package's tests.

When Codex is working in packages/api/, it sees both files concatenated — root rules plus package-specific rules. When it is at the repo root, it only sees the root file.

Package-level AGENTS.override.md: Use this only when a package has requirements so different from the root that you want to replace, not extend, the root’s instructions:

# packages/mobile/AGENTS.override.md

## Mobile Package (React Native)

This package has different conventions from the rest of the monorepo.
Do not apply the web-focused rules from the root AGENTS.md here.

## Commands

- Start: `pnpm react-native start`
- iOS: `pnpm react-native run-ios`
- Android: `pnpm react-native run-android`
- Test: `pnpm test`

## Conventions

- Components in src/components/ using React Native primitives
- Navigation via React Navigation (not Next.js router)
- No SSR, no server components

Browse AGENTS.md Examples in Our Gallery

The Prompt Shelf maintains a curated collection of AGENTS.md files from real repositories. If you want to see how specific project types structure their AGENTS.md — a Rust library, a Django API, a Go CLI, a TypeScript monorepo — the gallery has real examples rather than fabricated ones.

Browse the full collection at our rules gallery, or jump directly to AGENTS.md-specific entries:

• OpenAI Codex AGENTS.md Guide — official Codex discovery hierarchy and config reference
• AGENTS.md Open Specification — the Linux Foundation-backed standard format
• Turborepo AGENTS.md — monorepo build system configuration
• Everything Claude Code — 28 Sub-Agents — advanced multi-agent setup
• shadcn/ui AGENTS.md — component library conventions
• Tauri Desktop App AGENTS.md — Rust + WebView cross-platform setup

Quick Start Checklist

For a new project getting AGENTS.md for the first time:

# AGENTS.md

## Project

[One sentence: what this project is and what it does]

## Commands

- Install: [command]
- Build: [command]
- Test: [command]
- Lint: [command]
- Start: [command]

## Project Structure

[Directory tree with one-line explanations of key directories]

## Conventions

- [Most important convention 1]
- [Most important convention 2]
- [Most important convention 3]

## Boundaries

- [What Codex should never modify without explicit instruction]
- [Any protected files or directories]

Start with this. Add specifics as you discover Codex making mistakes that better instructions would have prevented. The best AGENTS.md files were not written all at once — they grew from observed failure modes.

We update our gallery regularly with new AGENTS.md examples from high-signal repositories. If you find a well-written AGENTS.md in the wild, let us know and we will review it for inclusion.