Skip to content

Plan Mode and /review

Plan mode lets Codex explore your codebase without modifying anything. It researches, thinks, proposes — but doesn’t touch files until you approve.

What Plan Mode Does

In plan mode, Codex:

  • Reads files
  • Searches code
  • Runs read-only commands
  • Creates a plan
  • Waits for your approval

It cannot:

  • Edit files
  • Write new files
  • Run destructive commands

Think of it as a research phase before the work phase.

Activating Plan Mode

Two ways:

Keyboard shortcut: Press Shift+Tab to cycle through modes: Plan → Pair → Execute

Slash command:

/plan

The status bar shows current mode.

When to Use Plan Mode

Use for:

  • Changes touching 3+ files
  • Architectural decisions
  • Unfamiliar codebases
  • Risky refactors
  • Understanding legacy code

Skip for:

  • Single-line fixes
  • Typo corrections
  • Simple renames
  • Routine changes you understand

Don’t waste time planning a one-line bug fix. Do plan before restructuring a module.

Plan Workflow

  1. Enter plan mode (Shift+Tab or /plan)
  2. Describe what you want
  3. Codex explores and proposes a plan
  4. Review the plan
  5. Approve or adjust
  6. Switch to execute mode (Shift+Tab again)
  7. Codex implements the plan

Example:

/plan

Refactor the auth module to use JWT instead of sessions

Codex will:

  • Read current auth implementation
  • Find all session usages
  • Identify affected files
  • Propose migration steps
  • List potential breaking changes

You review, then press Shift+Tab to switch to execute mode. Codex implements what you approved.

The /review Command

/review asks Codex to examine code changes. Different from plan mode — it’s specifically for reviewing diffs.

Review Options

Type /review to open an interactive menu with four presets:

  1. Review against a base branch — Compare current branch against main/master
  2. Review uncommitted changes — Review your working directory diffs
  3. Review a commit — Examine a specific commit’s changes
  4. Custom review instructions — Provide your own focus (e.g., security, performance)

For non-interactive usage (CI/CD), use the codex exec review subcommand with arguments like base-branch main or commit abc123.

What Review Covers

Codex looks for:

  • Logic bugs
  • Missing edge cases
  • Security vulnerabilities
  • Test coverage gaps
  • Style inconsistencies
  • Breaking changes

Output is a prioritized list. Critical issues first.

Review Model

By default, review uses your current model. Override in config:

review_model = "gpt-5.4"

Use a stronger model for reviews if you want deeper analysis.

Resuming Sessions

Plans persist as part of your session history. Resume a previous session:

codex resume --last

Or resume a specific session by ID:

codex resume <session-id>

Plan Mode in Codex App

The desktop and web app includes a diff panel that shows Git diffs with inline comments. You can approve individual files, stage or revert specific chunks.

Best Practices

Plan for the unknown. Unfamiliar codebase? Start in plan mode. Let Codex map out the territory first.

Be specific. “Improve performance” is too vague. “Reduce database queries in the user list endpoint” gives Codex something concrete to plan.

Question the plan. Before executing, ask:

  • Does this touch unexpected files?
  • Are there missing steps?
  • What could break?

Iterate on plans. Say “also consider X” or “don’t touch Y”. Refine before executing.

Plan Mode Limits

Plan mode is prompt-enforced, not sandboxed. The model follows instructions not to modify files, but there’s no hard technical block.

In practice, it works. The model respects plan mode constraints. But for truly sensitive work, combine plan mode with read-only sandbox:

sandbox_mode = "read-only"

This adds a hard barrier.

Combining Plan and Review

Good workflow for PRs:

  1. /plan — Research what needs changing
  2. Approve and Shift+Tab — Switch to execute mode
  3. /review — Catch issues before committing
  4. Fix any review findings
  5. Commit

Two checkpoints: plan before coding, review before shipping.