How to Use AGENTS.md in OpenAI Codex

A comprehensive guide to setting up and using AGENTS.md files with OpenAI Codex to improve code generation accuracy and maintain consistency across your team.

OpenAI Codex is a powerful AI coding assistant, but to get the most out of it, you need to provide clear context about your project. AGENTS.md is the standard way to do this. This guide will show you exactly how to set up and use AGENTS.md with Codex to boost accuracy and maintain consistency across your entire team.

Where to Create Your AGENTS.md File

The location of your AGENTS.md file determines its scope and when Codex will read it. Here's how to choose the right location:

Project Root (Most Common)

Place AGENTS.md in your project's root directory, alongside package.json, README.md, or other configuration files:

my-project/
├── AGENTS.md          ← Primary configuration
├── package.json
├── README.md
├── src/
└── tests/

When to use: This is your go-to option for single-repository projects. Codex automatically looks for AGENTS.md in the project root when starting a new session.

Best for: Startups, small-to-medium projects, or any codebase with unified conventions.

Subdirectories (Monorepos)

For monorepos or large codebases with multiple sub-projects, place AGENTS.md files in each package or module:

1monorepo/
2├── AGENTS.md                    ← Root-level defaults
3├── packages/
4│   ├── frontend/
5│   │   ├── AGENTS.md           ← Frontend-specific rules
6│   │   └── src/
7│   ├── backend/
8│   │   ├── AGENTS.md           ← Backend-specific rules
9│   │   └── src/
10│   └── shared/
11│       ├── AGENTS.md           ← Shared utilities rules
12│       └── lib/
13

Resolution priority: When Codex encounters multiple AGENTS.md files, the closest file to the code being edited takes precedence.

Best for: Monorepos with different tech stacks, microservices, or projects with distinct coding conventions per module.

Global Configuration (Advanced)

Some Codex implementations support a global AGENTS.md in your home directory:

~/.config/codex/AGENTS.md        # Unix/Linux/macOS
C:\Users\<name>\.codex\AGENTS.md # Windows

When to use: For personal coding preferences that apply across all your projects.

Priority: Global settings have the lowest priority and are overridden by project-specific files.

What to Include in Your AGENTS.md File

A well-crafted AGENTS.md file gives Codex the context it needs to generate accurate, consistent code. Here are the essential sections:

1. Project Overview

Start with a brief description of what your project does and its purpose.

2. Tech Stack

List your technologies, versions, and key dependencies.

3. Essential Commands

Provide commands for setup, development, testing, linting, and building.

4. Directory Structure & Architecture

Explain your folder organization and key patterns.

5. Code Style & Conventions

Define coding standards specific to your project.

6. Testing Requirements

Specify testing standards and strategies.

7. Security & Compliance

Document security requirements and constraints.

8. Git Workflow & Commit Conventions

Establish version control practices.

9. AI Agent Guidelines

Tell Codex how to behave when working on your project.

Example Templates & Best Practices

Minimal Startup Template

Perfect for MVPs and small teams that need to move fast.

Enterprise-Grade Template

For large teams requiring strict governance.

Monorepo Template

For projects with multiple packages.

How Codex Reads and Merges AGENTS.md

Initialization Process

When you start a Codex session:

  1. Project Detection
  2. File Discovery
  3. Content Parsing
  4. Context Loading

Merging Strategy (Multiple Files)

Priority (Highest to Lowest):

  1. Explicit user prompts in chat
  2. AGENTS.md in the file's immediate directory
  3. AGENTS.md in parent directories (closest wins)
  4. Root-level AGENTS.md
  5. Global ~/.config/codex/AGENTS.md

Real-World Performance Impact

Accuracy Improvements:

  • 40-60% reduction in code review comments
  • 30-50% fewer test failures
  • 70-80% better file structure adherence

Team Consistency:

  • Faster developer onboarding
  • Reduced style debates in PRs
  • Consistent code quality

Time Savings:

  • 25-35% reduction in code review back-and-forth
  • 15-20% faster feature implementation
  • 50% reduction in "how do I..." questions

Last updated: January 2025