Skip to content

Complete Guide to Codex Plan Mode (2026): Stop AI Drift with Plan→Execute

Codex CLI Complete Guide

For / Key Points

Audience:

  • Developers who want to separate planning from implementation in Codex CLI
  • Teams that need a quick mental model for /plan versus Read-only
  • Readers comparing current docs with older collaboration_modes guides

Key Points:

  • The current official planning entry point is /plan [description]
  • /plan handles design, while Read-only controls approvals and execution scope
  • Older feature-flag or /collab-first walkthroughs should be treated as historical guidance

Codex now has a clearer Plan→Execute path, which makes it easier to reduce drift and accidental implementation changes.

Official path as of April 17, 2026

In the current OpenAI docs, Codex planning is documented as the built-in slash command /plan [description]. The current Config Reference does not list collaboration_modes, so older setup guides that treat a feature flag as the official path are no longer a safe default.12 This article uses the current /plan flow as the primary path and treats older flag-based instructions as historical context.

For Claude Code users

If you already rely on a Plan workflow in Claude Code, jump to Appendix 1.

Why Plan Mode Matters: Process Separation Beats Prompt Poetry

Most LLM coding accidents happen because requirements drift while coding. Plan mode addresses this with process separation:

  • Plan (Design): Lock in what to do, what NOT to do, steps, and verification upfront
  • Execute (Implementation): Implement without breaking the Plan
  • When in doubt, return to the Plan and document the reason for the change (no unauthorized pivots)

Plan mode is prompt-level, not a runtime sandbox

Plan mode tells the model not to make changes, but that rule is prompt-level rather than runtime-enforced.5 For critical work, combine it with git stash or a throwaway branch. See Pitfall #4 for details.

Try It in 10 Minutes: The Current Official Flow

As of 2026-04-17, the current official entry point documented by OpenAI is /plan [description].1

1) Check your version

codex --version

Use the latest CLI behavior and current docs as your source of truth. Plan-related UI text can change quickly, so your local build matters more than old screenshots.

2) Run /plan inside the session

/plan fix the auth bug

The current slash command docs explicitly list /plan [description]. Use that built-in command as your starting point instead of older community instructions.1

3) Add Read-only when you need stronger guardrails

The official docs also describe approval modes that you can switch from /permissions.

  • /plan: draft the plan first
  • Read-only: a conservative approval mode that keeps Codex consultative until you approve a plan3

This distinction matters. /plan is about planning first. Read-only is about restricting execution until approval.34

4) Follow the current UI when you move to implementation

The docs clearly establish /plan as the entry point, but the exact UI text that appears after planning can vary by version. Prefer the current session UI over old screenshots or older /collab walkthroughs.

Current Docs vs. Older Community Advice

As of 2026-04-17, the safest split is:

  • Current official planning path: /plan [description]
  • Current official safety policy: /permissions → Read-only
  • Older guidance to treat cautiously: collaboration_modes setup steps, /collab as the main entry point, and UI walkthroughs that depend on older feature-flag behavior

In practice, that means the current slash command docs clearly document /plan, while the current config reference does not surface collaboration_modes as the main setup path.12 For a public guide, the safer reading order is to treat /plan as the baseline and keep older feature-flag or /collab-first advice in the background.

Practical Plan Templates: 3 Types (Copy-Paste Ready)

In Plan mode you only paste and fill; you do NOT implement here. Once the plan is fixed, return to implementation and build from it.

Plans that grow too long slow things down. Set limits.

Template A: Minimal (For Small Changes / 5–10 Lines)

  • Objective (1 line)
  • Changes (max 3)
  • Impact scope (files/modules)
  • Verification (command or perspective)

Example:

Objective: Convert audit logs to JSON for stable parsing

Changes: Fix logger output keys / Same format on exceptions / No backward compatibility with old format

Impact: api/logger.ts, middleware/log.ts

Verification: unit + e2e, format sample logs with jq

Template B: Solid (Medium-Scale / When Specs Are Unstable)

  • Goal / Non-goal
  • Steps (Step 1..N)
  • Compatibility (breaking changes yes/no)
  • Rollback plan
  • Test plan

Filled example (replace with yours)

Goal: Switch payment API to gateway v2
Non-goal: Do not change checkout UI
Steps: Step1 swap token issuance to v2 / Step2 add webhook verification / Step3 delete v1 code
Compatibility: Mobile app <1.8 not supported (show error)
Rollback: Flag PAYMENTS_V2=false to revert to v1
Tests: unit(payments/*), e2e(card/3DS/failure cases)

Template C: Accident-Proof (Infrastructure / Permissions / Monitoring / Billing)

  • Risk (High/Medium/Low) with reasoning
  • Affected stakeholders
  • Monitoring/alerts/metrics changes
  • Execution steps (decision criteria & recovery)

Filled example (infra change)

Risk: Medium (privilege escalation misconfig could leak data)
Stakeholders: SRE, Security, Billing
Monitoring/Alerts: CloudWatch AuthzDenied threshold 5→3
Execution:
 1) Apply policy v3 to IAM role billing-writer
 2) Confirm AssumeRole succeeds in logs
 3) Run canary invoice PDF; if it fails, revert to policy v2

Advanced Techniques: Reverse Interview and PLANS.md

Two additions make Plan mode more useful in real work.

1. Use a reverse interview prompt

If your task is still fuzzy, ask Codex to interrogate the ambiguity before proposing the plan:

"I want to add feature X, but the requirements are still fuzzy. Challenge my assumptions and ask me the questions needed to turn this into an implementation plan."

That pattern works well when you know the direction but do not yet have a stable spec.

2. Store planning templates in the repo

For teams with recurring workflows, keep files such as PLANS.md or execution-plan-template.md in the repository and instruct Codex to use them while planning. This works especially well for repetitive review, migration, or rollout processes.

Stop Wandering: Plan→Execute "Single Lane" Workflow

The recommendation is to fix the "boundary between Plan and implementation" operationally.

  1. Agree on the Plan

    • Define success criteria (Done) upfront
    • Lock in steps and verification with templates

  2. Implement

    • Implement following the Plan
    • If requirements shift mid-way, return to the Plan and append the reason for the change

  3. Verify and Done

    • Execute the verification defined in the Plan — complete when satisfied

Recommended mantra:

"Success criteria is X. Step1→Step2. When in doubt, return to the Plan."

Common Pitfalls

1) Taking old setup guides at face value

Search results still surface older guides from the feature-flag era. The current official docs put the planning entry point on /plan, so use that as the baseline and treat older collaboration_modes instructions as historical context.12

2) Plans growing too long and slowing down

Plans break down when "writing" becomes the goal. Stick to Templates A/B/C and respect the limits.

3) Handoff is vague, so execution defaults to "business as usual"

Include the bridge statement every time: success criteria, steps, and "return to the Plan when in doubt."

4) Plan mode is prompt control, not a runtime block

Plan mode tells the model not to write or modify files, but this constraint is enforced at the prompt level only. There is no runtime sandbox that physically blocks mutations.5

In practice, the model almost always respects the instruction. However, for high-stakes changes:

  • Use a throwaway branch or git stash before entering Plan mode
  • Review /status after each plan to confirm no unintended file changes
  • Don't rely on Plan mode as a substitute for code review or CI gates

Appendix 1: Tips for Porting Claude Code's Plan Workflow to Codex

The three main reasons Claude Code's Plan works well in practice:

  • Write Non-goals first (lock in "what NOT to do")
  • Define verification upfront (Done criteria don't drift)
  • The more changes grow, the more you document change reasons in the Plan (becomes a decision log)

Porting these directly to Codex makes the Plan's value more apparent.

Appendix 2: The "Just Right" Granularity for Plans (Decision Criteria)

  • Fixes that take 5 minutes: Template A (keep it short)
  • Changes spanning half a day or more: Template B (compatibility and rollback)
  • Areas where accidents hurt: Template C (operator perspective)

Appendix 3: Making It Work for Teams (Minimal Rules)

  • Attach a "Plan (Template A or above)" before PR/review
  • If the Plan changes, append "reason for change" to the Plan before continuing implementation
  • Judge Done by the Plan's verification items (don't end on a feeling)

FAQ

How do I start Plan mode in current Codex versions?

Use /plan [description] inside the session. That is the current built-in slash command documented in the official Codex CLI docs.1

Is /plan the same thing as Read-only?

No. /plan is the command that drafts the plan first. Read-only is the conservative approval mode you can select from /permissions when you want Codex to stay consultative until you approve a plan.34

Can Plan mode still modify files?

Plan mode tells the model not to mutate files, but that protection is prompt-level rather than runtime-enforced.5 For high-risk work, still use git isolation or a disposable branch.

Why does this article not use collaboration_modes as the main setup path?

Because the current official slash command docs document /plan, while the current config reference does not present collaboration_modes as the active setup path.12

  1. Codex CLI slash commands ↩↩↩↩↩↩↩

  2. Codex config reference ↩↩↩↩

  3. Features - Codex CLI ↩↩↩

  4. Agent approvals & security - Codex ↩↩

  5. openai/codex issue #11115 ↩↩↩