Skip to main content
Codex is OpenAI’s CLI coding agent built for running tasks in a terminal, writing and editing code, executing commands, and iterating on the results. It was one of the earliest and most prominent adopters of the AGENTS.md format, and its support helped establish AGENTS.md as a broadly used standard across the open-source ecosystem.

Codex documentation

Official Codex documentation from OpenAI.

​
How Codex reads AGENTS.md

Codex reads AGENTS.md automatically when it starts working in a repository. No configuration file or flag is required — if an AGENTS.md file exists at the repository root or in a parent directory of the code being edited, Codex will read it before taking any action. In a monorepo, Codex follows the standard precedence rule: the closest AGENTS.md to the code being edited wins. A file at packages/api/AGENTS.md takes precedence over the root AGENTS.md for work done inside that package.
User chat prompts always override instructions in AGENTS.md. AGENTS.md sets the default context; explicit instructions from the user take precedence.

​
What to put in AGENTS.md for Codex

Codex uses the full contents of AGENTS.md to guide its work. The most useful sections are:
  • Build and test commands — Codex will run these automatically to verify its changes
  • Code style rules — formatting conventions, naming patterns, preferred libraries
  • Repository structure — where packages live, how the monorepo is organized
  • PR and commit conventions — message format, branch naming, review expectations
  • Security notes — files or areas that require extra care

​
Example AGENTS.md for a Codex project

AGENTS.md
# AGENTS.md

## Build and test
- Install dependencies: `npm install`
- Compile TypeScript: `npm run build`
- Run Jest test suite: `npm test`
- Lint (ESLint + Prettier): `npm run lint`

## Code style
- TypeScript strict mode is enabled — no `any` types
- Use named exports; avoid default exports
- Prefer `const` over `let`; never use `var`
- All async functions must handle errors explicitly

## Repository structure
- `src/` — application source
- `src/api/` — REST API handlers
- `src/db/` — database models and migrations
- `tests/` — Jest test files, mirroring `src/` structure

## Commits and PRs
- Conventional Commits format: `feat:`, `fix:`, `chore:`, `docs:`
- Keep commits atomic — one logical change per commit
- PR descriptions must include a summary and a testing section

## Security
- Never commit secrets or API keys
- All user inputs must be validated before reaching the database
- Changes to `src/auth/` require an extra reviewer

Build docs developers (and LLMs) love

Get started for freeTalk to us