What if one markdown file could nearly double your AI coding agent's success rate? That's exactly what Vercel discovered when they tested AGENTS.md against other approaches for teaching AI agents framework-specific knowledge. Their result: a 100% pass rate, up from just 53% without it.

In this guide, we'll show you how to set up AGENTS.md with OpenAI's Codex CLI — the lightweight, open-source coding agent that runs right in your terminal. Whether you're building a side project or managing a production codebase, this combination will make Codex CLI dramatically more reliable.

What Is AGENTS.md and Why Does It Matter?

AGENTS.md is an open standard for providing persistent instructions and context to AI coding agents. Think of it as a README, but for your AI assistant instead of human developers. Whatever you put in AGENTS.md is available to the agent on every turn, without the agent needing to decide whether to load it.

Vercel's January 2026 evaluation proved this matters enormously. They tested four configurations against hardened evals targeting Next.js 16 APIs that weren't in any model's training data:

Configuration	Pass Rate	vs Baseline
No docs (baseline)	53%	—
Skills (default)	53%	+0pp
Skills + explicit instructions	79%	+26pp
AGENTS.md docs index	100%	+47pp

The key insight: agents don't reliably invoke external tools (skills), even when explicitly available. In 56% of Vercel's eval cases, the skill was never invoked. But AGENTS.md is always loaded — no decision required.

How Codex CLI Uses AGENTS.md

OpenAI's Codex CLI has first-class support for AGENTS.md with a powerful layered instruction system. Here's how it works:

Layer	Location	Purpose
Global	`~/.codex/AGENTS.md`	Your personal preferences across all projects
Project root	`./AGENTS.md`	Project-wide conventions and setup
Directory	`./src/AGENTS.md`	Folder-specific rules (e.g., component patterns)
Override	`AGENTS.override.md`	Replaces normal AGENTS.md for that folder

Codex reads the global file first, then layers in project-specific instructions from the repo root down to your current directory. This means you can set universal preferences once and then customize per-project without repeating yourself.

Step-by-Step Setup: AGENTS.md for Codex CLI

Step 1: Install Codex CLI

If you haven't already, install Codex CLI globally:

# Using npm
npm install -g @openai/codex

# Using Homebrew (macOS)
brew install --cask codex

Run codex and sign in with your ChatGPT account. Plus, Pro, Team, Edu, and Enterprise plans all include Codex access.

Step 2: Create Your Global AGENTS.md

Set up your personal defaults that apply across every project:

mkdir -p ~/.codex
cat > ~/.codex/AGENTS.md << 'AGENTS'
# Global Agent Instructions

## Working Agreements
- Ask clarifying questions when scope is unclear.
- Keep changes small and reviewable.
- Run tests before finishing.
- Prefer retrieval-led reasoning over pre-training-led reasoning.

## Code Style Preferences
- Use TypeScript strict mode.
- Prefer functional components with hooks.
- Write descriptive variable names — no single-letter vars.
- Add JSDoc comments for exported functions.
AGENTS

Step 3: Create Your Project AGENTS.md

In your project root, add project-specific instructions:

cat > ./AGENTS.md << 'AGENTS'
# Project: My SaaS App

## Tech Stack
- Framework: Next.js 16 with App Router
- Styling: Tailwind CSS v4
- Database: Prisma + PostgreSQL
- Package Manager: pnpm (NOT npm or yarn)

## Build & Test Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Lint: `pnpm lint`
- Test: `pnpm test`
- Build: `pnpm build`

## Project Conventions
- All API routes go in `app/api/`
- Use `'use cache'` directive for cacheable server components
- Use `connection()` for dynamic rendering
- Environment variables: `.env.local` for secrets

## Important Rules
- ALWAYS run `pnpm lint` and `pnpm test` before reporting done
- Use `forbidden()` and `unauthorized()` for auth errors (NOT manual 403/401)
- Prefer server components by default; use `'use client'` only when necessary
AGENTS

Step 4: Add Directory-Level Instructions (Optional)

For specific directories with unique patterns:

cat > ./src/components/AGENTS.md << 'AGENTS'
# Component Guidelines
- Every component gets its own directory: `ComponentName/index.tsx`
- Co-locate tests: `ComponentName/__tests__/ComponentName.test.tsx`
- Use Radix UI primitives for accessibility
- Export via barrel files
AGENTS

Step 5: Run Codex CLI with Safe Defaults

Start Codex with a safe autonomy level that still removes friction:

# Recommended: approvals on request + workspace sandbox
codex --ask-for-approval on-request --sandbox workspace-write

# Or use the shortcut for the same combo
codex --full-auto

When you need access to directories outside your project (like shared libraries), use --add-dir instead of disabling sandboxing entirely.

Optimal AGENTS.md Structure for Codex CLI

After researching community patterns and OpenAI's best practices, here's the structure that works best with Codex CLI:

# Project Name

## Tech Stack
[Framework, language, key dependencies — Codex uses this to avoid outdated patterns]

## Build & Test Commands
[Exact commands — this is the #1 most impactful section]

## Project Structure
[Key directories and their purposes — helps Codex navigate large codebases]

## Conventions & Style
[Coding patterns specific to your project]

## Important Rules
[Hard constraints — things Codex must always or never do]

## API/Framework Reference (Optional)
[Compressed docs index for APIs not in training data — the Vercel approach]

Key tip from Vercel's research: Include this instruction in your AGENTS.md to prevent the agent from relying on outdated training data:

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
for any [your framework] tasks.

Codex CLI-Specific Tips and Configurations

Use Skills Alongside AGENTS.md

Codex CLI also supports SKILL.md files — packages of instructions for specific workflows. The best approach is to use AGENTS.md as the stable foundation and skills for specialized tasks:

# Save as ~/.codex/skills/ask-questions-if-underspecified/SKILL.md
---
name: ask-questions-if-underspecified
description: Ask 1-4 clarifying questions before acting.
---

# Ask Questions If Underspecified
- If goal, scope, constraints, or environment are unclear, ask numbered questions with options.
- Prefer short, multiple-choice questions with a default.
- Pause work until the user answers.

Plan-and-Verify Loop for Complex Tasks

Add this to your AGENTS.md or use it in prompts for tricky multi-file changes:

## Task Workflow
When tackling complex tasks:
1. Make a plan listing files to touch, risks, and verification steps.
2. Wait for approval before editing.
3. After changes, run all verification commands.
4. Paste the test summary before reporting done.

Resume Sessions to Keep Context

Codex CLI supports session resumption, which pairs perfectly with AGENTS.md:

# Resume your last session
codex resume --last

# Review changes without modifying working tree
/review

With vs Without AGENTS.md: Real Difference

Here's what actually changes when you add AGENTS.md to a Codex CLI project, based on Vercel's research and community reports:

Scenario	Without AGENTS.md	With AGENTS.md
Package manager	May use npm, yarn, or pnpm randomly	Always uses your specified tool
New framework APIs	Falls back to outdated patterns	Uses version-matched docs
Testing	Often skips verification	Runs lint + test before reporting done
Project structure	Guesses file locations	Follows defined conventions
Error handling	Generic try/catch blocks	Uses project-specific patterns
Eval pass rate (Vercel)	53%	100%

Real-World Project Example: Next.js SaaS App

Here's a complete AGENTS.md for a production Next.js 16 SaaS application:

# Acme SaaS Dashboard

## Tech Stack
- Next.js 16 (App Router)
- TypeScript 5.7 strict mode
- Tailwind CSS v4 + Radix UI
- Prisma 6 + PostgreSQL
- Stripe for billing
- Resend for emails

## Commands
- `pnpm install` — install dependencies
- `pnpm dev` — start dev server (port 3000)
- `pnpm lint` — ESLint + Prettier check
- `pnpm test` — Vitest with coverage
- `pnpm build` — production build
- `pnpm db:migrate` — run Prisma migrations

## Next.js 16 API Reference
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.

### Cache APIs
- Use `'use cache'` directive for cacheable components/functions
- `cacheLife()` — set cache duration
- `cacheTag()` — tag for revalidation
- `revalidateTag()` — invalidate by tag

### Dynamic Rendering
- `connection()` — opt into dynamic rendering
- `cookies()` and `headers()` are async in Next.js 16

### Auth Helpers
- `forbidden()` — throw 403 response
- `unauthorized()` — throw 401 response

## Project Structure
```
app/
  (auth)/        — auth pages (login, signup)
  (dashboard)/   — protected dashboard routes
  api/           — API routes
src/
  components/    — shared React components
  lib/           — utilities and helpers
  server/        — server-only code (db, auth)
prisma/          — schema and migrations
```

## Rules
- ALWAYS run `pnpm lint && pnpm test` before done
- Use server components by default
- All database queries go through `src/server/db.ts`
- Never expose API keys in client components
- Use Stripe webhook handler in `app/api/webhooks/stripe/`

At Serenities AI, we use a similar layered AGENTS.md approach across our projects. The consistency it brings to AI-assisted development is remarkable — our agents follow project conventions from the first prompt.

AGENTS.md vs CLAUDE.md: Cross-Tool Compatibility

If you're using multiple AI coding tools, you should know that AGENTS.md is an open standard supported by Codex CLI, while Claude Code uses its own CLAUDE.md format. The content structure is nearly identical. You can maintain both files, or symlink them:

# Keep one source of truth
ln -s AGENTS.md CLAUDE.md

For a deep comparison of how these tools stack up, check out our Claude Code vs Codex CLI comparison.

Pro Tips for Maximum Impact

Keep it under 8KB. Vercel's winning AGENTS.md was a compressed 8KB docs index. Don't dump your entire documentation — curate what matters.
Include build/test commands first. This single section has the highest impact on agent reliability.
Version your framework APIs. If you're on Next.js 16, explicitly list the new APIs so the agent doesn't fall back to Next.js 14 patterns.
Use the override file. AGENTS.override.md lets you replace instructions for specific folders — useful for monorepos with different conventions per package.
Commit AGENTS.md to git. Your whole team benefits, and the instructions evolve with your codebase.

For more tips on getting the most from AI coding tools, see our Claude Code tips and tricks guide — many of the prompt engineering principles apply to Codex CLI as well.

FAQ

Does AGENTS.md work with the Codex web app or only Codex CLI?

AGENTS.md is primarily designed for Codex CLI, which reads the file from your local filesystem. The Codex web app (at chatgpt.com/codex) operates on cloud-based repositories and reads AGENTS.md from the repo root when you connect a GitHub repository. Both interfaces support the format.

How big should my AGENTS.md file be?

Keep it under 8KB. Vercel's research showed that a compressed docs index at this size achieved perfect pass rates. Anything larger risks context window bloat and diminishing returns. Focus on build commands, key conventions, and APIs not in training data.

Can I use AGENTS.md and SKILL.md together in Codex CLI?

Yes, and you should. AGENTS.md provides stable, always-loaded context (project conventions, build commands). SKILL.md files package specialized workflows that Codex invokes on demand. Use AGENTS.md as the foundation and skills for specific complex tasks like database migrations or deployment scripts.

Will AGENTS.md slow down Codex CLI?

No. AGENTS.md is loaded once at session start and stays in context. It's far more efficient than the agent repeatedly searching for documentation mid-task. The small upfront context cost pays for itself many times over in reduced errors and retries.

Should I put sensitive information in AGENTS.md?

Never put API keys, passwords, or secrets in AGENTS.md. It's a markdown file that should be committed to version control. Reference environment variable names instead: Database connection: use DATABASE_URL from .env.local.

Start Using AGENTS.md Today

The data is clear: AGENTS.md transforms AI coding agents from unreliable assistants into consistent, project-aware partners. Vercel's 53% to 100% improvement isn't a fluke — it's what happens when you remove the guesswork from your AI's workflow.

Start with a simple AGENTS.md containing your build commands and key conventions. You'll see the difference immediately. Then iterate — add framework API references, directory-specific rules, and team conventions as you go.

For more guides on optimizing your AI coding workflow, explore the latest tutorials at Serenities AI.

Stop Your AI Agent from Forgetting: AGENTS.md Setup Guide