CodexLog

Appearance

Plan-First Mode (Codex CLI) ​

Plan-First Mode is the Codex CLI workflow where you separate analysis and planning from execution. Instead of letting the agent edit or run commands immediately, you first switch approvals to Read Only, get a structured plan, and then deliberately grant execution rights. This improves safety, reviewability, and predictability. OpenAI's docs explicitly suggest Read Only "when you just want to chat, or if you want to plan before diving in." (OpenAI Developer)

What it does (in practice) ​

  • No edits or command runs until you allow it. In Read Only, Codex won't modify files or run commands; you use it to analyze, outline steps, and review diffs before allowing action. For out-of-scope or network actions, Codex will ask for approval. (OpenAI Developer)
  • You control the switch. Toggle approval modes at any time with the /approvals command: Read Only → plan; Auto → safe local execution with approvals for risky actions; Full Access → broad permissions (use sparingly). (OpenAI Developer)

How to activate ​

At the Codex prompt:

/approvals
# choose: Read Only

Now ask Codex to plan only:

"Plan the fix for the failing e2e test:
- identify root cause
- outline minimal changes
- propose test adjustments
- estimate risk and rollback steps
Do not apply changes yet."

When you're satisfied with the plan, switch to Auto (or selectively approve prompts) and proceed. (OpenAI Developer)

Before Plan-First (why it matters) ​

Relying solely on natural-language prompts like "don't make changes, just suggest" can work, but results may vary in format and verbosity. Plan-First replaces that uncertainty with a mode that keeps Codex in analysis-only until you explicitly move on. The CLI is designed around approvals to keep potentially dangerous actions gated. (OpenAI)

With Plan-First (what you get) ​

  • Structured output: Ask Codex to return numbered options, trade-offs, and risk notes—then iterate on the plan.
  • Predictable flow: Analysis → plan → approval → execution.
  • Speed & cost relief: Planning often needs fewer edits/rollbacks, saving tokens and time. Documentation encourages this pattern: plan in Read Only, then execute using approvals. (OpenAI Developer)

Example prompt

"Evaluate shader hot spots:
- list top 3 complexity drivers
- propose alternatives with trade-offs (speed delta, scope of edits, risk)
- recommend the least risky path with test plan
Don't change files yet."

Hybrid planning (mix models deliberately) ​

Codex lets you switch models on the fly. A pragmatic pattern is:

  1. Plan with a stronger model (e.g., GPT-5-Codex at higher reasoning)
  2. Execute with a lighter model (e.g., GPT-5 or o4-mini) for routine edits/tests

Use /model inside the session, or --model at startup; exact defaults and reasoning levels are in the docs. (There's no automatic "plan model → exec model" toggle; you decide when to switch.) (OpenAI Developer)

/model gpt-5-codex
# …plan in Read Only…
/approvals  # switch to Auto when ready
/model o4-mini
# …apply low-risk edits and run tests…

What can Codex do in Read Only? ​

  • Analyze repository structure and write plans (chat/analysis).
  • Ask for approval before venturing outside the working dir or using network.
  • Refrain from edits/command runs until you change approvals. This behavior follows the CLI's documented approval modes and boundaries. (OpenAI Developer)

Tip: Keep plans consistent by pinning your project rules in AGENTS.md and explicitly asking Codex to read and follow it at session start. OpenAI publishes AGENTS.md as a first-class guide format for coding agents. (GitHub)

Exiting Plan-First safely ​

  • Move from Read Only → Auto to allow local edits/commands in the working directory, with approval prompts when stepping out of scope or using network.
  • Only use Full Access when you're monitoring closely (for example, during a long refactor you've already reviewed). The docs caution to exercise care here. (OpenAI Developer)

Execution checklist

- Confirm the plan (steps, tests, rollback)
- Switch /approvals to Auto
- Ask for a small, reviewable diff
- Require a PR-style explanation (what/why/impact/rollback)
- Run tests; if green, commit

Scripting a plan-first pipeline ​

Codex also supports a non-interactive exec mode—useful for CI smoke checks:

bash
# Planning step: produce a plan artifact (no edits)
codex exec "Plan a minimal-risk fix for flaky test X; output as markdown; no changes."

# Review artifact, then:
codex "Apply step 1 only and show the diff. Wait for approval."

The CLI documents exec for scripting. Approvals still gate risky actions even when scripted. (OpenAI Developer)

Why this is the Codex way ​

OpenAI emphasizes approval-gated computer use: the agent can read/modify/run code, but you approve what crosses risk boundaries (outside working dir, network, etc.). Plan-First via Read Only is the simplest way to get predictable analysis, then controlled execution. (OpenAI)

Sources ​

  • Codex CLI docs (approval modes, /approvals, /model, exec, OS support): "Codex CLI" page. (OpenAI Developer)
  • OpenAI announcement (safety & approvals across CLI/IDE): "Introducing upgrades to Codex." (OpenAI)
  • AGENTS.md (project-level guidance format for coding agents): GitHub + site. (GitHub)

If you'd like, I can turn this into a VitePress page with short code blocks and a sidebar slug like /mechanics/foundation/plan-approvals.