Skip to content

Codex Plan Mode: How to Use /plan and Shift+Tab (2026)

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 mode versus read-only permissions
  • Readers comparing current docs with older collaboration_modes guides

Key Points:

  • Start Plan mode with /plan [description] or cycle to it with Shift+Tab
  • Plan mode guides Codex to investigate and design before implementation
  • Read-only permissions are a separate runtime restriction, not another name for Plan mode

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

Current official entry points

OpenAI documents two ways to enter Plan mode: use /plan [description] or press Shift+Tab to cycle collaboration modes. Older setup guides that require a collaboration_modes feature flag or lead with /collab should be treated as historical guidance.12

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 and read-only permissions solve different problems

Plan mode changes how Codex approaches the task: it investigates, asks questions, and proposes a plan before implementation. Read-only permissions restrict filesystem writes at runtime. Use both when you need deliberate planning and an enforced no-write boundary.23

Try It in 10 Minutes: The Current Official Flow

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) Enter Plan mode

The most direct route is the slash command:

/plan fix the auth bug

You can also press Shift+Tab until the mode indicator shows Plan. The slash command is convenient when you already have a task description; the keyboard shortcut is useful when you want to switch modes before writing the prompt.12

3) Let Codex inspect and clarify before implementation

Plan mode is most useful when Codex can first inspect the repository, identify constraints, and ask focused questions. State the outcome, non-goals, and verification criteria, but avoid prescribing every implementation detail before Codex has examined the context.

4) Add read-only permissions when writes must be blocked

Open /permissions and select Read-only when you want the sandbox to prevent filesystem writes. This setting is independent of Plan mode: one controls the working approach, while the other controls what operations are allowed.3

5) Review the plan, then move to implementation

Confirm scope, risks, and verification steps before leaving Plan mode. Then follow the current session UI or cycle modes with Shift+Tab to return to an implementation-capable mode. Exact labels can change between CLI releases, so prefer the current interface over old screenshots.

Current Docs vs. Older Community Advice

The safest split is:

  • Current official planning paths: /plan [description] or Shift+Tab
  • Current runtime restriction: /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

The official documentation now presents Plan as a built-in collaboration mode. Use /plan or Shift+Tab as the baseline and keep feature-flag or /collab-first advice in the background.12

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 describe /plan and Shift+Tab as the built-in entry points, so 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) Treating Plan mode as a sandbox

Plan mode is a collaboration workflow, while the sandbox and permissions enforce runtime boundaries. For high-stakes changes:

  • Select Read-only from /permissions when filesystem writes must be blocked
  • 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, or press Shift+Tab until the mode indicator shows Plan. Both routes are documented by OpenAI.12

Is /plan the same thing as Read-only?

No. /plan enters a collaboration mode designed for investigation and planning. Read-only is a separate permission setting that prevents filesystem writes.3

Can Plan mode still modify files?

Plan mode is intended for investigation and planning rather than implementation. If writes must be technically blocked, also select Read-only from /permissions; for high-risk work, keep normal git isolation and review controls in place.3

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

Because the current official docs present Plan as a built-in mode entered with /plan or Shift+Tab, without requiring the older feature-flag setup.12

Summary

Enter Codex Plan mode with /plan [description] or Shift+Tab. Let Codex inspect the relevant context, resolve ambiguity, and define verification before implementation. When planning must occur behind an enforced no-write boundary, select Read-only separately from /permissions.

  1. Switch to Plan mode with /plan - OpenAI ↩↩↩↩↩↩

  2. Codex best practices: Plan mode - OpenAI ↩↩↩↩↩↩↩

  3. Codex security and permissions - OpenAI ↩↩↩↩