Set up Codex CLI and write an AGENTS.md that Codex actually reads

Codex CLI is OpenAI's terminal coding agent. You sign in with a ChatGPT account, and it reads your local repository, writes code and runs commands.

This article covers install, sign-in and a first task, then how to write the AGENTS.md that Codex reads to learn your project's rules.

Prerequisites

Item	Detail
OS	macOS and Linux. Windows is documented via WSL 2
Node.js	Needed if you install with npm (use the LTS release)
Account	A paid ChatGPT plan, or an OpenAI API key
Git	Required if you want Codex to work with the repository

Install

With npm or Homebrew:

# npm
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

Check the version:

codex --version

Sign in

Start codex in a project directory and the first run asks how you want to sign in.

cd path/to/project
codex

• Sign in with ChatGPT: a browser opens and you sign in. Usage draws on what your plan includes.
• Sign in with an API key: pay-as-you-go. Set OPENAI_API_KEY, or register it with codex login --api-key.

codex login --api-key "sk-..."
codex login status   # check the current sign-in

A first task

Type what you want in the prompt:

Explain how this repository is organized, and how to run the tests

Codex reads the files it needs and runs commands where it has to. Whether it asks before editing a file or running a command depends on your approval mode and sandbox settings — see Codex approval modes and sandbox settings.

Where AGENTS.md goes, and how it is found

Codex collects AGENTS.md at startup and treats it as your project's rules. The format is not Codex-specific; several coding agents read it.

Location	Use
~/.codex/AGENTS.md	Your personal preferences across every project
AGENTS.md at the repository root	Project rules shared with the team
AGENTS.md in a subdirectory	Rules that apply only under that directory

Files are collected from the root toward your current directory and concatenated in that order, so deeper files land later and override earlier ones. At each level the order is AGENTS.override.md, then AGENTS.md, then any name listed in project_doc_fallback_filenames. The documentation adds that "Filenames not on this list are ignored for instruction discovery" — a name you leave off is not treated as guidance at all.

A template

# Project overview
Express + TypeScript REST API. PostgreSQL via Prisma.

## Setup and commands
- Dependencies: `pnpm install`
- Dev server: `pnpm dev`
- Tests: `pnpm test` (always run the tests related to your change)
- Lint / typecheck: `pnpm lint && pnpm typecheck`
- Migrations: `pnpm prisma migrate dev`

## Conventions
- Functions stay under 50 lines; split them otherwise
- Throw `AppError`; never swallow an error
- Keep external API calls in `src/clients/`
- Do not use `any`

## Do not change
- Existing files in `prisma/migrations/`
- `src/generated/` (generated code)

## How to work
- For changes spanning several files, propose the approach as a bulleted list first
- Do not report completion while tests are failing
- Commit messages follow Conventional Commits

## When opening a PR
- Title under 50 characters
- Body states why the change was made and how it was tested

/init has Codex inspect the project and generate a starting AGENTS.md. Don't ship the generated file as-is: cut anything a reader could get from the README, and keep only the agreements that aren't visible from the code.

Commands worth knowing

Command	What it does
/init	Generate a starting AGENTS.md
/model	Switch model and reasoning depth
/approvals	Switch approval mode
/status	Current settings, model and token usage
/diff	Show the current diff
/clear	Clear conversation history

Using it alongside CLAUDE.md

On a team that also uses Claude Code, you end up needing both AGENTS.md and CLAUDE.md. For how to avoid maintaining two copies, see CLAUDE.md, AGENTS.md and GEMINI.md differ only in how they load. For switching models and profiles through config.toml, see What you can configure in Codex's config.toml.

Summary

• Install with npm install -g @openai/codex or Homebrew, start codex, and sign in with ChatGPT or an API key
• An OPENAI_API_KEY in your environment can take precedence over a ChatGPT sign-in
• AGENTS.md lives at three levels — ~/.codex/, the repository root, and subdirectories — with deeper files overriding
• Each level is searched as AGENTS.override.md, AGENTS.md, then the fallback names; anything else is ignored for instruction discovery
• The combined limit is 32 KiB by default, so keep it short and point at detail by path