Codex cheat sheet

A scannable Codex reference: 16 short snippets across 9 topics, each linking back to the lesson it came from.

At a glance

Quick snippets

What Codex is and how to set it up

Install and configure

# install the CLI, then authenticate with your account
npm install -g @openai/codex
codex --version
codex                     # first run walks through sign-in

# sanity check: ask a question that needs no file access
codex exec "list the top-level directories and describe the build system"

Install and configure

# ~/.codex/config.toml - the shape of the settings that matter first.
# Key names move between releases; run the tool's own help to confirm yours.
model = "gpt-5-codex"

# how much the agent may do without asking
approval_policy = "on-request"     # ask when it wants to leave the sandbox
sandbox_mode = "workspace-write"   # read-only | workspace-write | danger-full-access

# project instructions live in the repository, not in your home directory:
#   AGENTS.md at the repo root, and per-directory AGENTS.md files deeper in the tree

Full lesson: What Codex is and how to set it up →

Using Codex in a real workflow

The review loop

git diff --stat                     # scope first: which files moved
git diff                            # then read the whole patch, not the summary
pytest -q                           # the project's own gate, run by you
ruff check . && mypy src            # cheap verification the repository already has
git add -p                          # stage deliberately, hunk by hunk
git commit -m "Add cursor pagination to the orders API"

Full lesson: Using Codex in a real workflow →

Reviewing output and its limits

Review the diff, then verify

# the checks that catch the common failures
git diff --stat                          # unrelated files touched?
git diff -- tests/                       # assertions removed, loosened or skipped?
git diff -- package.json requirements.txt pyproject.toml    # new dependencies?
grep -rn "skip\|xfail\|@Ignore" $(git diff --name-only)    # disabled tests

# then run the real gate on a clean checkout of your own branch
git stash list && pytest -q && npm test

Full lesson: Reviewing output and its limits →

Approval modes and sandboxing

The approval policy decides when it asks

# choose per invocation instead of editing a global config
codex --sandbox read-only --ask-for-approval untrusted "summarise how authentication works in this repo"
codex --sandbox workspace-write --ask-for-approval on-request "add the missing index to the orders migration"
codex --sandbox danger-full-access --ask-for-approval never   -C /tmp/scratch-container "generate a throwaway benchmark script"   # inside a container

# inspect what is actually in force before trusting it
codex --help | head -40
codex exec --help | head -40

Escalation and its side effects

# make the escalation unnecessary by preparing the environment first
python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt          # done by you, outside the agent run
pre-commit install --install-hooks       # hooks cached before the agent works

# now the agent's task needs no network and no writes outside the workspace
codex --sandbox workspace-write --ask-for-approval on-request \
  "run the test suite, fix the failing assertions in tests/test_reports.py, \
   do not add dependencies and do not modify tests other than that file"

Full lesson: Approval modes and sandboxing →

Writing AGENTS.md project instructions

Generating and shaping the file

# let the agent draft a first version from what it can see
codex
> /init

# then edit it by hand: the draft is a starting point, not a specification
git add AGENTS.md && git commit -m "Add AGENTS.md with build and test instructions"

How the files combine

# nested files let a monorepo carry local rules without one giant root file
repo/
  AGENTS.md                  # build, global conventions
  services/api/AGENTS.md     # python service specifics
  web/AGENTS.md              # node, pnpm, component conventions
  infra/AGENTS.md            # terraform: plan before apply, never apply unattended

# verify what the agent is actually reading for a given path
codex --sandbox read-only "list every instruction file you are following and where it is"

Full lesson: Writing AGENTS.md project instructions →

Configuration with config.toml and profiles

Named profiles

# select a profile for a run
codex --profile review "explain the retry logic in src/client.py and list its edge cases"
codex --profile implement "add exponential backoff to that retry loop"

# override a single key for one run without editing anything
codex -c model_reasoning_effort="high" "why does the nightly job occasionally double-process records?"
codex -c sandbox_mode="read-only" "summarise what changed in the last 20 commits"

# profiles are also usable from the environment for scripted runs
CODEX_PROFILE=ci codex exec "run the linter and report the failures"

Project trust and version drift

# capture the effective configuration for the record
codex --version > .codex-version.txt
codex --help > .codex-help.txt     2>&1

# verify a specific setting took effect by asking the agent to state it
codex -c sandbox_mode="read-only" "state your current sandbox mode and approval policy, then stop"

# after an upgrade, diff the help output against the recorded one
diff <(cat .codex-help.txt) <(codex --help 2>&1) | head -40

Full lesson: Configuration with config.toml and profiles →

Prompting Codex effectively

A task with a boundary

Weak:    "improve the checkout flow"

Better:  "Add a 10-minute reservation timer to the checkout page.
          - new component: src/components/ReservationTimer.tsx, following the
            pattern in src/components/CountdownBanner.tsx
          - show remaining time, switch to an expired state at zero
          - do not change the payment code or the API contract
          - add tests in src/components/__tests__/ReservationTimer.test.tsx
          - done when npm test passes and the component renders in Storybook"

Plan first, then implement

# 1. ask for a plan and nothing else
codex --sandbox read-only "Read src/billing/ and propose how to add proration to
  plan upgrades. List the files you would change, the new functions, and the
  tests you would add. Do not write any code yet."

# 2. correct the plan in a follow-up rather than restarting
#    "Do not introduce a new decorator; extend the existing PlanChange model."

# 3. only then authorise the implementation, quoting the plan
codex "Implement the plan we agreed, exactly: modify src/billing/plan_change.py
  and src/billing/proration.py, add tests/test_proration.py. Stop when
  pytest tests/test_proration.py passes. Change nothing else."

Iterating well

Good follow-ups, in order:

"pytest fails: TypeError: plan_change() got an unexpected keyword argument
 'effective_from' at src/billing/plan_change.py:88. Fix that call site only."

"Keep the public signature of PlanChange unchanged; the upgrade path relies on it."

"Good. Now add the test for the downgrade case to the same file, then stop."

Full lesson: Prompting Codex effectively →

Extending Codex with MCP servers

Registering a server

# inspect what the agent can actually call, before trusting a task to it
codex --sandbox read-only "list every tool you have available, grouped by server, and stop"

# confirm which servers started and which failed
codex -c model_reasoning_effort="low" "report the status of each MCP server, then stop"

Context cost and tool selection

# keep the base configuration clean and add servers per profile
[profiles.docs]
model_reasoning_effort = "low"
sandbox_mode = "read-only"
mcp_servers = ["docs"]

[profiles.implement]
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
mcp_servers = ["docs", "repo_metrics"]
# the deployment server is deliberately absent from every profile

Full lesson: Extending Codex with MCP servers →

Debugging and troubleshooting runs

Getting visibility

# ask for the reasoning and the tool calls to be shown
codex --help | grep -i -E "verbose|debug|log"     # confirm the flags for your version

codex -c hide_agent_reasoning=false "explain why the test at line 40 fails, \
  showing the commands you ran and their output"

# capture a run for later inspection
codex exec --json "run the test suite and report failures" 2>&1 | tee run.jsonl

# where session and log files live for the version you have
ls -la ~/.codex 2>/dev/null
ls -la ~/.codex/log 2>/dev/null | tail -20

Full lesson: Debugging and troubleshooting runs →

FAQ

Related cheat sheets

AI Basics AI Agents Math for AI Machine Learning scikit-learn TensorFlow

Last refreshed 2026-09-27.