Codex plan mode is a read-only planning state in OpenAI's Codex CLI. While it is on, Codex explores your repository and drafts a step-by-step plan, but it does not write or run any code until you approve that plan. OpenAI added plan mode to Codex in late 2025. Before that, Codex engineers approximated it with a plan.md file, a workflow that still works well for long tasks and is covered below.
What is Codex plan mode?
Plan mode separates thinking from doing. In its default mode, Codex starts acting on your request right away: it reads files, edits code, and runs commands. That is great for small tasks and risky for big ones, because the most expensive failures in agentic coding come from a wrong first step compounding over an hour of autonomous work.
In plan mode, Codex is limited to reading. It studies the codebase, asks clarifying questions, and produces a reviewable plan: the intended approach, the files it will touch, and the order of operations. You iterate on that plan in plain language until it matches what you actually want. Only when you approve it does Codex begin implementation.
How do you turn on plan mode in Codex?
- Open the Codex CLI in your repository.
- Press Shift+Tab in the composer to cycle modes until plan mode is active.
- Describe the task. Codex will explore the code and propose a plan instead of editing anything.
- Push back on the plan: ask why it chose an approach, point out constraints it missed, ask it to list open questions.
- Approve the plan to let Codex switch to execution and implement it step by step.
If you delegate work to Codex through GitHub instead of the CLI, there is no interactive planning loop. In that case, write the plan into the issue itself before tagging the agent. Our guide to running Codex from GitHub covers that setup.
How do you use a plan.md file with Codex?
The plan.md workflow predates plan mode and remains the best tool for multi-hour tasks. On September 19, 2025, Alexander Embiricos of OpenAI's Codex team shared the tip: for long tasks, many OpenAI engineers first ask Codex to write a markdown file with a plan and todos, iterate on that file, and only then let it go. Some users reported Codex running autonomously for more than 40 minutes on the back of a good plan file.
A plan file beats an in-conversation plan for three reasons:
- It survives crashes. If the session dies mid-task, the next session reads plan.md and resumes.
- It forces atomic todos. Breaking work into the smallest units that need no further input is what lets the agent run unattended.
- It manages context. The plan lives on disk, not in the conversation, so a long task does not drown in its own history.
Here is a prompt template for that workflow:
I need to build [YOUR FEATURE]. Before writing any code, create a `plan.md` file with:
1. **Architecture Plan** - tech stack, key decisions, and why
2. **Structured Todo List**
Break down the implementation into the smallest atomic units that allow it to run without input
- Phase 1: ...
- Phase 2: ...
3. **Session Recovery Notes**
Include detailed notes about:
- Current project state and what's been completed
- Any critical decisions made so far
- Where to resume if this session crashes
Be specific and actionable. This plan will guide the entire implementation.
Ask me any questions before you start about anything that's not concrete and specific enough in the plan.
During implementation, tell Codex to keep plan.md updated: mark todos done, record decisions, and note where to resume. The file becomes both the roadmap and the audit trail.
How does Codex plan mode compare to Claude Code plan mode?
Claude Code shipped the pattern first: a read-only mode toggled with Shift+Tab that blocks all file edits while you develop a plan together. Codex adopted the same idea in late 2025, so the day-to-day experience is now similar in both tools. The practical differences as of July 2026:
- Claude Code pairs plan mode with extended thinking keywords for harder problems; the combination is described in our Claude Code workflow guide.
- Codex culture leans on the plan.md file convention for very long autonomous runs, as described above.
If you use both tools, the transferable habit is identical: never let an agent start a large task without a plan you have read.
FAQ
Does Codex have a plan mode?
Yes. As of July 2026 the Codex CLI includes a plan mode that keeps the agent read-only while it drafts a plan for your approval. Before late 2025 it did not, and users prompted Codex to write a plan.md file first instead. Both approaches work and combine well.
What is plan.md in Codex?
plan.md is a convention, not a special Codex feature. It is a markdown file you ask Codex to create before coding, holding the architecture plan, a todo list broken into atomic steps, and session recovery notes. Codex treats it like any other file in the repo, which is exactly why it survives session restarts.
When should you skip plan mode?
For small, unambiguous tasks: a rename, a one-file bug fix, a test you can describe precisely. Planning overhead only pays off when the task spans multiple files, multiple decisions, or more than a few minutes of autonomous work.