Set up your environment and AGENTS.md — Codex: AI-Assisted Development

Updated November 3, 2026 based on Codex documentation (Codex CLI, Authentication, Codex IDE extension, Custom instructions with AGENTS.md): the @openai/codex-cli package and codex auth login command do not exist (use npm install -g @openai/codex and codex login); the extension identifier is openai.chatgpt; the codex.openai.com address and “Team, Enterprise, or API” plans are replaced with current access methods; and the AGENTS.md read order is clarified (project root → current directory). Sources: Codex CLI · Authentication · AGENTS.md · Pricing.

Prepare your project for Codex

Two things must be in place before your first task: your Codex access—your account and GitHub connection—and your project itself, defined through the AGENTS.md file that will guide the agent. The first part takes about 15 minutes and is a one-time setup. The second determines the quality of everything you get out of Codex, separating teams who are satisfied with Codex from those who find it disappointing.

Step 1: Your Codex access

You can use Codex with a ChatGPT account or an API key. The Free and Go plans provide access, depending on the current deployment, to GPT-6 Luna in the desktop app. Starting with Plus, Codex is available on the web, in the CLI, in the editor extension, and on iOS, with cloud integrations like automated code review. An API key works for automation in shared environments like CI, using the CLI, SDK, or extension—though some features may not be available. Details and usage limits are on the Codex pricing page.

To work in the cloud on your repositories, connect GitHub when you create your first Codex Cloud environment (Lesson 2). When granting permissions, keep it minimal: limit access to only the repositories you actually need.

Step 2: Install the editor extension

In VS Code and its derivatives (Cursor, Windsurf), install the Codex extension from the marketplace—its identifier is openai.chatgpt:

code --install-extension openai.chatgpt

Then open Codex via its icon, or through the command palette with Codex: Open Codex Sidebar, and log in. Xcode and JetBrains IDEs have their own integrations: in JetBrains, open AI Chat and select Codex.

Step 3: Install the CLI

# Installation (macOS and Linux), or npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Verify installation
codex --version

# Log in (browser), or check connection status
codex login
codex login status

codex login opens the login flow in your browser. For an API key, pass it via standard input (printenv OPENAI_API_KEY | codex login --with-api-key). Codex caches credentials either in a plaintext file, ~/.codex/auth.json, or in the system keychain, depending on the cli_auth_credentials_store setting (file, keyring, auto, or ephemeral). If the file is used, treat it like a password: it contains access tokens, so never commit it. The CLI and extension share this cache.

The AGENTS.md file—your project guide

AGENTS.md is central to using Codex effectively. It’s a simple Markdown file placed at the root of your repository that gathers instructions, conventions, and commands specific to your project. When Codex clones the repo, it reads this file first: think of it as automatic onboarding for the agent, exactly what you’d explain orally to a new team member.

The impact is immediate. Without AGENTS.md, if you ask for a unit test on a project using Vitest, there’s a good chance Codex will give you Jest, because that’s the most common choice in the ecosystem. A single line of convention is enough to get Vitest right the first time, saving you from making the same correction a hundred times. Here’s the structure of a basic file for a SaaS invoice management project.

# AGENTS.md

## Project context
SaaS invoice management application.
Stack: Next.js 15, TypeScript, Prisma, PostgreSQL.

## Code conventions
- Use React functional components (no classes)
- Name files in kebab-case
- TypeScript types in separate .types.ts files
- Tests with Vitest, .test.ts files next to code

## Useful commands
- `npm run dev` — development server
- `npm run test` — run tests
- `npm run lint` — check linting
- `npm run build` — production build

## Project structure
    src/
      app/          → Next.js pages (App Router)
      components/   → Reusable React components
      lib/          → Business logic and utilities
      prisma/       → DB schema and migrations

## Strict rules
- NEVER modify Prisma schema without a migration
- NEVER commit .env files
- Always use Server Actions for mutations

How Codex finds AGENTS.md files

A single root file quickly becomes too generic. Codex lets you stack instructions in a precise order you need to know:

Global level: In your Codex folder (~/.codex, unless CODEX_HOME overrides it), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md.
Project level: Starting from the project root (usually the Git root), Codex descends to the current directory and reads, in each folder traversed, AGENTS.override.md or, failing that, AGENTS.md.
Merging: Files are concatenated from the root down to the current directory; those closest to the current directory come last and therefore override more general instructions.

my-project/
  AGENTS.md              → Project instructions
  src/
    api/
      AGENTS.md          → "API routes use Zod for validation"

Practical consequence: src/api/AGENTS.md is only read if Codex is working from src/api or one of its subdirectories, not when launched from the root. Empty files are ignored, and concatenation stops at 32 KiB by default (project_doc_max_bytes). If your repo already uses another name, like TEAM_GUIDE.md, add it to project_doc_fallback_filenames in ~/.codex/config.toml.

To verify what Codex has actually loaded, just ask: codex --ask-for-approval never "Summarize the current instructions.". Codex rebuilds the instruction chain on every launch: if in doubt, restart it in the correct directory.

Best practices for AGENTS.md

The guiding principle is explicitness. “Use Vitest, not Jest” is better than “Use our test framework,” which assumes knowledge the agent doesn’t have. Always include commands: without them, Codex won’t know how to run your tests, linter, or build, and it will deliver code it couldn’t verify. Document the structure as a directory tree, which prevents it from exploring blindly and creating files in the wrong place.

Finally, list the prohibitions. Rules written as “NEVER” are the most cost-effective in the file, because they block expensive mistakes that are hard to fix: committing a .env file, modifying a schema without a migration. The hardest discipline is keeping the file up to date. An AGENTS.md that describes last year’s project actively steers Codex toward abandoned conventions—far worse than having no file at all, since the error then becomes systematic.

Key takeaways

Initial setup requires an OpenAI account and a GitHub connection
The IDE extension and CLI install in minutes
AGENTS.md is the most important file for effective Codex use
It contains conventions, commands, and rules specific to your project
AGENTS.md files in subdirectories enable contextual instructions