Plan with Codex: a decision-complete plan before any edit

The Codex planning section is three guides for developers and tech leads that turn a goal into an approved plan before Codex edits a file: mapping an unfamiliar codebase, designing a system, and starting a new project. Each guide uses Codex’s Plan mode (/plan), in which Codex explores without editing, asks what it cannot find out, and ends with a proposed plan.

You asked Codex to “add rate limiting”, and the diff wraps every route in middleware your API gateway already provides. Nobody agreed on the shape first. Planning moves your review to a one-page plan with testable acceptance criteria, so the diff has to match a contract instead of your memory.

Prerequisite: Codex CLI installed, signed in, and opened in a repository you trust. If it is not, start with the Codex quick start. Commands on this page were checked against Codex CLI 0.157.1.

Which Codex planning guide do you need?

Your situation	Start with	What you leave with
You joined a repository and do not know where anything lives	Understand an unfamiliar codebase with Codex	An architecture overview and traced request flows
You must choose between designs, or split a service out	System design with Codex	An evidence map, an ADR, and a CI rule that enforces it
You are starting from an empty directory	Start a new project with Codex	A scaffolded repository with AGENTS.md and a setup script

Start a Codex planning session in Plan mode

Plan mode is one of Codex’s two collaboration modes (the other is Default). In the instructions bundled with CLI 0.157.1, Codex in Plan mode reads files and runs non-mutating checks, asks only what exploration cannot answer, and ends with a <proposed_plan> block that should be “decision complete”: the implementer has no choices left to make.

Those rules are model instructions, not a sandbox. To block writes, start the session read-only, and raise effort: Codex’s bundled default model, GPT-6 Astra, runs at low effort by default. OpenAI’s preferred control is a permission profile (beta, CLI 0.138.0 and later); the built-in :read-only profile blocks writes. In a terminal at the repository root:

codex -c default_permissions=":read-only" -c model_reasoning_effort="high"

The legacy form, codex -s read-only -c model_reasoning_effort="high", also works. Use one or the other, not both: OpenAI says the profile and legacy sandbox systems “do not compose”.

Then type /plan to switch to Plan mode and paste your planning prompt. When Codex proposes a plan, the CLI asks Implement this plan? and offers three answers: implement it (switch to Default mode and start coding), stay in Plan mode, or start a fresh thread with the plan. Choose No, stay in Plan mode until the plan passes the checks below. The other two labels are Yes, implement this plan and Fresh thread with this plan. Because the session is read-only, switch permissions with /permissions before you choose to implement.

To give Plan mode its own effort level for every session, set the key in ~/.codex/config.toml (the key exists in CLI 0.157.1):

plan_mode_reasoning_effort = "high"

Raise effort before you change model. The models hub lists the current models, effort levels, and prices.

Plan mode is not the update_plan tool

update_plan is a separate progress-checklist tool, off by default since CLI 0.152.0. Enabling it does not give you Plan mode.

How do you check a Codex plan without reading every line of the result?

Before you approve, confirm that the plan has these five parts, each checkable by a tool:

1. Acceptance criteria that each map to a named test, written to fail before implementation. See executable acceptance criteria.
2. Citations as path:line for every claim about existing code, so grep or a second run can confirm them.
3. Files in scope and out of scope. Existing tests and migrations belong on the out-of-scope list.
4. Verification commands, exactly as CI runs them: test, typecheck, lint.
5. Rollback: how the change is reverted or switched off.

After implementation, sign off on evidence: the new tests went from red to green, CI passes, codex review --base main finds nothing blocking, and the diff touches only files in scope. The developer approves a feature plan; a tech lead approves anything that changes an architecture decision. The reasoning is in evidence, not diffs.

Copy-paste prompt: a Codex plan you can verify

Plan this change; do not edit anything: add per-API-key rate limiting
(100 requests per minute) to the public REST endpoints.

Explore the code before asking me anything. Then produce a plan with
exactly these sections:
1. Current state: how requests reach the handlers today, with path:line
   citations for every claim.
2. Acceptance criteria: 3-6 Given/When/Then statements, each mapped to the
   name of a test that fails before the change and passes after it.
3. Files to change, and files you must not touch (existing tests, migrations).
4. Steps in order, each small enough to review on its own.
5. Verification: the exact test, typecheck, and lint commands CI runs.
6. Rollback: how to switch the limit off without a deploy.
Ask me only questions the repository cannot answer.

Plan mode does not write files, so copy the proposed plan into docs/plans/rate-limiting.md yourself; the file survives /compact, a new session, and a handover. Then check it with a fresh read-only run that has no memory of the planning conversation:

codex exec -c default_permissions=":read-only" -c model_reasoning_effort="high" \
  -o docs/plans/rate-limiting.review.md "$(cat prompts/plan-review.md)"

Copy-paste prompt: challenge the plan before you approve it (prompts/plan-review.md)

Review docs/plans/rate-limiting.md against this repository. Change nothing.
- Check every path:line citation and list any that are wrong.
- Name any caller, background job, or config value that reads the code the
  plan changes but is missing from the plan.
- For each acceptance criterion, say how it could pass while the feature is
  still broken.
- Flag any step that edits a file on the out-of-scope list.
Output Markdown: a verdict (APPROVE or REVISE) on the first line, then findings.

A REVISE verdict goes back into the planning session; approve only after an APPROVE you agree with.

What goes wrong when you plan with Codex?

Symptom	Likely cause	Recovery
The plan is a generic outline	The prompt named a goal, not constraints	Require the sections in the first prompt and name the files that matter
The plan cites files or functions that do not exist	Claims written from assumption	Run the review prompt; reject any plan with a wrong citation
Codex edited files during planning	The session was not in Plan mode, or ran with write access	Start with -c default_permissions=":read-only" (or the legacy -s read-only), type /plan, and restore the files with git restore
The plan is shallow on a hard problem	Effort stayed at the low default	Set plan_mode_reasoning_effort = "high" and plan again
The plan ignores your project rules	Untrusted projects do not supply AGENTS.md (since CLI 0.150.0)	Trust the repository, then restart the session
Implementation drifts from the approved plan	The plan lived only in the conversation	Save it to docs/plans/ and start each session with “Follow docs/plans/X.md; stop and ask before deviating”

Where to go after the plan is approved

• Spec-driven development: make the spec, not the code, the thing people review.
• Build with Codex: execute the approved plan with context, isolation, and gates.
• The method’s plan stage: how intent.md feeds the plan.
• The same stage in other tools: plan with Claude Code and plan with Cursor.

Understand an unfamiliar codebase with Codex Map the repository before you plan any change