How to write OpenAI Codex
AGENTS.md instructions

What makes Codex different from other AI coding tools

OpenAI Codex is a terminal-based agentic coding tool that reads AGENTS.md as its system prompt and executes tasks autonomously in a sandboxed environment with network access disabled and filesystem isolation by default. The sandboxed execution distinguishes Codex from Cursor or Windsurf - it is designed specifically for safe autonomous operation.

Understanding Codex approval modes

suggest (default, safest)

Codex shows every proposed change before applying it. You approve or reject each change individually. Best for learning Codex or working on unfamiliar codebases. AGENTS.md safety rules can be lighter in this mode since you have manual review of every change.

auto-edit

Codex applies file edits automatically but asks before running shell commands. Best for standard development tasks where you trust Codex's code changes but want to review before any commands execute.

full-auto

Codex runs completely autonomously in the sandbox without any prompts. Best for well-defined tasks with clear success criteria on codebases you know well. Your AGENTS.md must have the strictest scope rules in this mode.

What to include in AGENTS.md

# Project: [Name]

## Tech Stack
- TypeScript, Node.js 22
- Express, PostgreSQL via Drizzle ORM
- Vitest for testing

## Architecture
- API routes in src/routes/
- DB access only through src/db/ layer
- Auth in src/middleware/auth.ts - do not reimplement

## Scope Rules (critical for auto-edit / full-auto)
- Only modify files in src/ and tests/
- Never modify package.json without noting the change
- Run npm test after every significant change
- Task is complete when all tests pass and TypeScript compiles

## Coding Standards
- Named exports only
- Async/await over .then() chains
- JSDoc for all exported functions

Common questions

What is the difference between AGENTS.md and codex.md?

Both are recognized by Codex. AGENTS.md is the primary documented filename. If both exist in the project root, AGENTS.md takes precedence.

How do I use --instructions without modifying AGENTS.md?

Run: codex --instructions "focus only on the authentication module" "implement password reset". The --instructions string is added as additional context for that session only.

How does Codex compare to Claude Code?

Both are agentic terminal tools with project-level instruction files (AGENTS.md vs CLAUDE.md). Codex runs in a sandboxed environment making full-auto safer. Claude Code uses Anthropic's Claude models. See our Claude Code guide for a direct comparison.