Codex CLI Best Practices: AGENTS.md, Approval Modes and Review

The best practices for Codex CLI all aim at one thing: a run you can review quickly and undo cleanly. Keep AGENTS.md short and specific, with the exact build and test commands. Choose the sandbox and approval mode for each task instead of leaving the widest one on. Ask for a plan before anything difficult. Give each session one task, on its own branch or worktree. Read the diff and run /review before you commit. Keep secrets out of the files and environment Codex can see. And write down what was done somewhere other than the terminal, so tomorrow’s session starts from facts.

OpenAI’s own Codex best practices guide↗ (opens in a new tab) makes most of these points, and this page follows it where it is specific. For the commands themselves, see the Codex CLI commands reference; for first-time setup, Codex CLI setup.

1. Keep AGENTS.md short and specific

Codex reads AGENTS.md automatically at the start of every task, so it is where rules you would otherwise repeat in each prompt belong. OpenAI’s guide puts it plainly: a short, accurate file beats a long one full of vague rules. Start with what Codex cannot guess.

• The exact commands to build, test, lint and type-check, with the flags your project needs.
• Where things live, in a few lines, and what never to touch.
• What done means: which checks must pass before it says it has finished.
• How work is tracked and how commits are written.

Run /init for a first draft, then cut it down to what is true. Add a rule only after Codex gets something wrong twice; the guide suggests asking Codex for a short retrospective at that point and folding the lesson into the file. When one file grows too long, keep the root short and point to separate files for planning or review. Worked examples, by project type, are in AGENTS.md examples.

2. Choose the approval and sandbox mode per task

Two settings decide how much Codex does without you. The sandbox mode sets what commands can technically reach; the approval policy sets when Codex stops to ask. OpenAI’s agent approvals and security page↗ (opens in a new tab) lists the combinations, and each suits a different kind of task.

# Exploring or planning: read, never write
codex --sandbox read-only --ask-for-approval on-request

# Normal work in a repository (the Auto preset)
codex --sandbox workspace-write --ask-for-approval on-request

# CI or a script that must not stop to ask
codex exec --sandbox read-only --ask-for-approval never "summarise the failures"

• Start new repositories and unfamiliar code in read-only. Codex itself recommends read-only for folders that are not under version control.
• Use workspace-write with on-request for everyday work. Codex can edit and run commands in the folder, and asks before it writes elsewhere or uses the network.
• Use never only with a sandbox that already limits the damage, and only for jobs you have run by hand first.
• Leave --yolo and danger-full-access for a disposable container or VM. The docs call it not recommended outside one.
• Prefer --add-dir for one extra folder over widening the whole sandbox.

Inside a session, /permissions changes the mode and /status shows what is active. The desktop app and IDE extension call the everyday mode Ask for approval, and offer Approve for me, which sends eligible requests to an automatic reviewer instead of to you; the permissions page↗ (opens in a new tab) notes that changing who reviews does not widen the sandbox. Note that untrusted is no longer a valid approval policy, so older guides that recommend it are out of date.

3. Plan before it writes

For anything ambiguous or multi-step, switch to plan mode with /plan or Shift+Tab. Codex gathers context, asks questions and proposes steps before touching a file. Correcting a plan costs a sentence; correcting a finished diff costs a review. OpenAI suggests four parts for the prompt itself:

• Goal: what should change.
• Context: the files, errors or examples that matter. @ adds a file path.
• Constraints: conventions, boundaries, what must not change.
• Done when: the tests that pass, or the bug that no longer reproduces.

4. One task per session

The guide lists one chat for a whole project as a common mistake: context fills with old decisions and results get worse. Keep one session for one coherent piece of work. Start the next with /new, branch an idea with /fork, and use /compact when a long session needs room. /rename gives a session a name you can find with codex resume later. Before you start, work on a feature branch with a clean git status, so the diff is only this task.

5. Review every diff

Do not accept work you have not read. /diff shows every change, including new untracked files. /review asks Codex for a second pass focused on behaviour changes and missing tests, and offers four targets: against a base branch, uncommitted changes, one commit, or your own instructions. Outside a session, codex review --uncommitted does the same job in a script.

codex review --uncommitted
codex review --base main "check the migration is reversible"

If your team has review rules, keep them in a file and reference it from AGENTS.md, so every review applies the same checks. Set review_model in config.toml if you want reviews on a different model from the one that wrote the code. Then run the tests yourself: a review guides you, it does not replace them.

6. Use worktrees for parallel runs

Two sessions editing the same checkout will trip over each other; the guide names it as a common mistake. Give each parallel task its own Git worktree: a second working folder on its own branch, sharing one repository. Start Codex inside each. Git’s worktree documentation↗ (opens in a new tab) covers the details.

git worktree add ../app-csv-export -b fix/csv-export
git worktree add ../app-login-copy -b feat/login-copy
cd ../app-csv-export && codex
# when merged:
git worktree remove ../app-csv-export

The desktop app can create worktrees for you, and Codex cloud runs each task in its own container, which is the same idea on someone else’s machine. Coordinating several agents at once is covered in orchestrating coding agents.

7. Keep secrets out

• Never put keys or passwords in AGENTS.md. It is committed and read by every agent.
• Codex stores your sign-in in ~/.codex/auth.json as plain text unless you set cli_auth_credentials_store = "keyring". Treat the file like a password.
• By default, variables named with KEY, SECRET or TOKEN are not filtered from the commands Codex runs. Set ignore_default_excludes = false under [shell_environment_policy] to filter them.
• Keep network access off unless a task needs it. Web pages and issue text can carry instructions meant for the agent; see indirect prompt injection.
• Give MCP servers only the tools a task needs, with enabled_tools in the server’s table.

cli_auth_credentials_store = "keyring"

[shell_environment_policy]
ignore_default_excludes = false

8. Record the work

A terminal transcript is a poor record. It scrolls away, it lives on one machine, and it cannot tell the next session what is finished. Put the list of work on a board and have Codex update it as part of the task. With fenbs connected over MCP, add three lines to AGENTS.md: read the task from Next Up with fenbs_get_context and fenbs_list_items, move it to In Progress with a comment on the plan, and when done set testStatus to tested, partly, failed or needs-check, with testNotes saying what was actually run, before moving it to Completed. Every change is recorded in the board’s history under the assistant’s name, on your behalf, so a review starts from the task rather than from the scrollback. Connection steps are on Codex CLI on fenbs.