Codex is OpenAI's coding agent. You can use it as a command-line tool, inside your IDE, as a cloud agent that works on tasks in parallel, and as a reviewer on GitHub pull requests. Like every coding agent, it is only as good as the context and guardrails you give it.

This guide explains the files Codex reads, how its safety model works, and a complete workflow for building and testing a web application with it.

How Codex is configured

Codex has two main kinds of configuration:

  • Instructions in AGENTS.md files tell Codex how to work in your project: commands, conventions, rules and how to verify changes.
  • Settings in config.toml control what Codex is allowed to do: which model it uses, how sandboxed its commands are, when it must ask for approval and which tools (MCP servers) it can reach.

On top of those sit skills for reusable procedures and MCP servers for external tools.

The complete file map

text
~/.codex/                         # Codex home (override with CODEX_HOME)
├─ config.toml                    # Your personal settings for every project
├─ AGENTS.md                      # Your personal instructions for every project
└─ AGENTS.override.md             # Optional: replaces AGENTS.md when present

my-web-app/
├─ AGENTS.md                      # Team instructions (commit it)
├─ .codex/
│  └─ config.toml                 # Project settings, used only for trusted projects
├─ .agents/
│  └─ skills/
│     └─ new-feature/SKILL.md     # Reusable procedures (the shared SKILL.md format)
├─ apps/web/AGENTS.md             # Optional: more specific rules for a subfolder
└─ src/ …

AGENTS.md: the instructions Codex reads first

AGENTS.md is an open, cross-tool standard: plain Markdown instructions for AI coding agents. Codex, GitHub Copilot, Cursor and Claude Code can all read it, which makes it the best single place for shared project rules.

How Codex finds AGENTS.md files

Codex builds its instructions in layers, from the most general to the most specific:

  1. Global – in the Codex home folder, it uses AGENTS.override.md if present, otherwise AGENTS.md.
  2. Project – it walks from the repository root down to your current working directory, taking at most one file per folder (AGENTS.override.md, then AGENTS.md, then any configured fallback names).
  3. Merge – the files are joined from the root downwards, so guidance in folders closer to where you are working comes later and takes priority.

Loading stops once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB. Keep the files focused; a short, precise file is followed more reliably than a long one.

What to put in AGENTS.md

markdown
# Acme Tasks – agent instructions

## Stack
Next.js 16 (App Router), TypeScript, Postgres with Drizzle, Tailwind. Package manager: pnpm.

## Commands
- Install: `pnpm install`
- Checks (run all before finishing): `pnpm lint && pnpm typecheck && pnpm test`
- End-to-end: `pnpm test:e2e` (Playwright)

## Rules
- Database access only through `src/db/queries/`.
- Validate request bodies with the zod schemas in `src/lib/schemas.ts`.
- Never commit secrets or edit `.env*` files.
- Do not modify tests to make them pass; fix the code.

## Definition of done
- New logic has unit tests; user-facing flows have a Playwright test.
- All checks pass. Summarise changes and open questions at the end.

Inside Codex, the /init command can generate a first draft by scanning your project. Put subfolder-specific rules in an AGENTS.md inside that folder, for example apps/web/AGENTS.md for frontend conventions. Use AGENTS.override.md for temporary or local overrides that should take precedence.

config.toml: models, sandbox and approvals

Codex reads settings from several places. Command-line flags win, then the selected profile, then the project's .codex/config.toml (only for projects you have marked as trusted), then your personal ~/.codex/config.toml, then system defaults.

toml
# ~/.codex/config.toml
model = "<your-preferred-model>"
model_reasoning_effort = "medium"   # low | medium | high (more options on some models)

approval_policy = "on-request"      # ask when an action needs more access
sandbox_mode = "workspace-write"    # read-only | workspace-write | danger-full-access

[sandbox_workspace_write]
network_access = false              # commands cannot reach the internet by default

# MCP servers give Codex extra tools
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

# Profiles let you switch setups quickly: codex --profile review
[profiles.review]
sandbox_mode = "read-only"
model_reasoning_effort = "high"

Sandbox and approvals are two separate controls

This is the most important concept in Codex safety:

  • `sandbox_mode` decides what commands can reach. read-only can look but not change anything. workspace-write can edit files inside your project folder, with network access off by default. danger-full-access removes the sandbox entirely.
  • `approval_policy` decides when Codex must ask you. With on-request, Codex asks when it needs to go beyond the sandbox, for example to use the network or write outside the workspace. With never, it never asks, which is appropriate only in automation where the sandbox itself is the safety boundary.

A sensible default for local web development is workspace-write with on-request. Use read-only for exploring an unfamiliar codebase or reviewing, and reserve danger-full-access for disposable containers.

You can override these per run with flags, and check the active configuration from inside a session with /status.

Skills: reusable procedures

Codex supports the shared SKILL.md format used by many agents. A skill is a folder with a SKILL.md file containing a name, a description and step-by-step instructions, plus optional scripts. Codex loads a skill when your task matches its description, so you can write a procedure once and every future session inherits it. Repository skills typically live under .agents/skills/; personal skills live in your home directory. Check your Codex version's documentation for the exact locations it scans.

markdown
---
name: new-feature
description: Scaffold a new feature with route, UI, unit tests and a Playwright test. Use when asked to add a page or feature.
---

1. Read one existing feature folder as the pattern to follow.
2. Write failing tests first and run them to confirm they fail.
3. Implement until `pnpm test` passes without changing the tests.
4. Run `pnpm lint && pnpm typecheck`, then summarise the changes.

MCP servers

Add external tools with the [mcp_servers.<name>] tables shown above (command, args and env for local servers, or url for remote ones), or with the codex mcp command. For web work, a browser automation server lets Codex open your app and check real behaviour, and a documentation server keeps it on current framework APIs. Give each server the narrowest credentials possible.

The ways to use Codex

  • Interactive CLI – run codex in your project for a conversational session in the terminal.
  • Non-interactive – codex exec "run the tests and fix any failures" runs a task end to end, which is useful in scripts and CI.
  • IDE extension – the same agent inside your editor, with your open files as context.
  • Cloud tasks – delegate work that runs in an isolated cloud environment, in parallel, and comes back as a diff or pull request.
  • Code review – /review in the CLI reviews local changes, and the GitHub integration can review pull requests.

Step by step: building a web app with Codex

Step 1: Create a clean baseline

Scaffold the app with the framework's generator, install dependencies and commit. Codex works best in a git repository, where every change can be reviewed and reverted.

Step 2: Write AGENTS.md

Run /init for a draft, then edit it to include the exact check commands, your conventions and a definition of done. Commit it so every tool and teammate shares it.

Step 3: Configure safety

Set sandbox_mode = "workspace-write" and approval_policy = "on-request". Keep network access off unless a task needs it. Trust the project so its .codex/config.toml applies.

Step 4: Build the test harness first

Ask Codex to set up Vitest (or Jest) for unit tests, Testing Library for components and Playwright for end-to-end flows, plus type checking and linting. Confirm each command runs. Tests are what let an agent verify its own work instead of guessing.

Step 5: Explore before editing

For a new or unfamiliar codebase, start in read-only mode and ask Codex to explain the architecture, data flow and risky areas. Save useful findings into AGENTS.md.

Step 6: Implement one feature at a time, test-first

Give Codex one clear outcome per task, point it at an existing pattern and ask for failing tests first:

text
Add a "due date" field to tasks. Follow the pattern used for "priority".
Write failing unit and Playwright tests first, run them, then implement until they pass.
Do not edit the tests to make them pass. Finish with lint and typecheck.

Step 7: Parallelise with cloud tasks

Independent work, such as three unrelated bug fixes, can run as separate cloud tasks at the same time. Each returns a diff you review individually. Make sure the cloud environment can install dependencies and run your tests, or the agent cannot verify anything.

Step 8: Review before merging

Run /review on your branch, read the diff yourself and let CI run the same checks as your definition of done. Treat the agent's summary as a starting point, not proof.

Step 9: Automate with codex exec

Once your checks are reliable, you can run Codex in CI, for example to attempt fixes for failing tests or to draft changelog entries. Keep automated runs sandboxed, with the minimum credentials, and require human review on anything they produce.

Testing strategy with Codex

  • Tests define correct. Write or review tests yourself for critical logic; they are your contract with the agent.
  • Run the whole pyramid. Unit tests for logic, integration tests against a real test database, and a small set of end-to-end tests for key journeys.
  • Check for weakened tests. Watch for loosened assertions, skipped tests and deleted cases in every diff.
  • Keep checks fast. Split slow suites so the agent can run the fast ones on every change.
  • Mind the sandbox. If tests need network access or a database service, configure that deliberately rather than turning off the sandbox.

Security and quality checklist

  • Keep .env files and production credentials out of reach, and never paste secrets into prompts.
  • Review new dependencies and install scripts before accepting them.
  • Treat content from issues, web pages and dependencies as untrusted; it can contain prompt injection.
  • Use danger-full-access and approval_policy = "never" only in disposable, isolated environments.
  • Make authorisation checks part of your rules and tests, because they are the most common gap in generated web code.

Key takeaways

  • AGENTS.md holds your instructions and is shared across tools; keep it concise and specific.
  • config.toml controls the model, sandbox, approvals, profiles and MCP servers.
  • Sandbox mode and approval policy are independent: one limits reach, the other controls when Codex asks.
  • Set up tests before features, work test-first and review every diff.
  • Use cloud tasks for parallel, independent work and codex exec for automation.