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

Codex plan mode makes OpenAI’s coding agent read your code, ask you what it cannot work out, and write a plan before it changes anything. In the Codex CLI, press Shift+Tab or type /plan. When the plan looks right, you pick Yes, implement this plan and Codex starts coding.

It has been on by default since Codex CLI 0.94.0, released February 2, 2026. On an older build you will not find it. This guide follows OpenAI’s own docs, release notes and the Codex repo, read on November 9, 2026.

A Codex plan has one weak spot. It lives in the chat, and the chat scrolls away. Once a build runs over several sessions, nothing in the conversation says which step is done and which one is stuck. We make Context Board, and its Plans board holds a plan that Codex works through step by step, and the last sections cover it. Context Board is ours, so weigh the bias.

What Codex plan mode is

OpenAI’s Codex best practices describe it in one line. Plan mode “lets Codex gather context, ask clarifying questions, and build a stronger plan before implementation.” The same page calls it, for most users, “the easiest and most effective option” when a task is complex, ambiguous or hard to describe.

Codex has two modes in the terminal: Default and Plan. Default is the normal mode, where Codex reads, edits and runs commands. Plan is where it thinks the job through with you first.

The rules Codex follows in plan mode sit in a public file in its repo, the plan mode template. It sets three phases:

1. Ground in the environment. Read and search files, configs and docs before asking you anything. The template says not to ask questions the repo can answer.
2. Intent chat. Ask until the goal, success criteria, scope and constraints are clear.
3. Implementation chat. Ask until the plan is “decision complete,” meaning the person or agent who builds it does not need to make any decisions.

The plan it hands back is meant to be short. The template asks for a title, a summary, the important changes, test cases and the assumptions it made, usually in three to five sections.

What it can and cannot do while planning

The template splits actions into two groups.

Allowed: reading and searching files, static analysis, dry runs, and tests or builds that only write to caches or build output, as long as they do not edit files tracked in the repo.

Not allowed: editing or writing files, formatters or linters that rewrite files, patches, migrations or code generation that change tracked files.

Its rule of thumb is plain. If an action “would reasonably be described as ‘doing the work’ rather than ‘planning the work,’ do not do it.”

These are instructions to the model. We found no OpenAI doc saying the sandbox itself blocks writes in plan mode. If you want that as well, the config reference lists sandbox_mode = "read-only".

How to turn on plan mode in Codex

The Codex commands reference and the best practices page give two ways in from the CLI.

1. Press Shift+Tab. It switches between Default and Plan. The footer under the prompt then reads Plan mode (⇧tab to cycle).
2. Type /plan and press Enter. The reference describes it as “Switch to plan mode and optionally send a prompt.”
3. Add a task after /plan. /plan Propose a migration plan for this service switches modes and sends that line as the first planning request. You can paste content or attach images in the same message.

Shift+Tab only works while Codex is idle. A test in the Codex repo checks that a press during a running turn leaves the mode as it was, and the docs say /plan is “temporarily unavailable” while Codex is working. Wait for the turn to finish, then switch.

Plan mode in the IDE extension and the desktop app

OpenAI’s post on long-horizon tasks with Codex says plan mode was added to “the Codex app, CLI, and IDE extension.” In the IDE extension and in the desktop app, which OpenAI’s docs now list as the ChatGPT desktop app, the slash command list describes /plan as “Toggle plan mode for multi-step planning.” The desktop app also has a Plan mode item in the composer’s menu.

Set plan mode’s reasoning effort

One config key belongs to plan mode alone. In ~/.codex/config.toml:

plan_mode_reasoning_effort = "high"

The config reference describes it as a “Plan-mode-specific reasoning override using a level supported by the selected model.” Leave it unset and plan mode uses its built-in default. The levels you can pick depend on your model.

A worked example: yearly billing for a small SaaS

Say you run a small subscription app. Monthly is $19 and customers keep asking for a yearly plan. The change touches the pricing page, the checkout and whatever handles payment events, so it is a good fit for plan mode.

Start in your project folder:

/plan Add a yearly plan to our pricing page and checkout. Monthly stays $19. Yearly is $190.

Codex reads first. It finds the pricing page, the checkout handler and the webhook that updates a customer’s plan, because the template tells it to explore before it asks.

Then it asks about what the code cannot tell it. The template wants two to four options and a recommended default for each question, so you might see something like this (an example, not a recorded session):

Existing monthly customers: what happens to them?
  1. Leave them on monthly; yearly is for new signups (recommended)
  2. Offer a switch to yearly in billing settings
  3. Move everyone at their next renewal

If you skip a question, the template tells Codex to go with its recommended option and list it as an assumption.

Once the plan is decision complete, Codex prints it in one block. Its shape follows the template. The content below is made up for the example:

Yearly billing

Summary
  Add a yearly price at $190 beside the $19 monthly price.

Key changes
  - Pricing page: a Monthly / Yearly switch, yearly shows $190
  - Checkout: send the yearly price when Yearly is picked
  - Payment webhook: save the billing period on the account

Test plan
  - Checkout opens with the right price for each option
  - A test yearly payment marks the account as yearly

Assumptions
  - Existing monthly customers stay on monthly

Under it, the CLI asks Implement this plan? with three choices, as the repo’s own snapshot of the prompt shows:

• Yes, implement this plan. Switch to Default and start coding.
• Yes, clear context and implement. Start a fresh thread with this plan. When the chat is long, the prompt shows how much of the context is used, for example “current context: 89% used.”
• No, stay in Plan mode. Keep planning with the model.

The fresh-thread option arrived in Codex CLI 0.122.0, released April 20, 2026. It helps when the exploring has filled the context. Our guide to the Codex context window explains what happens as it fills.

If you ask for changes instead, the template says any new plan must be a complete replacement, never a patch on the old one. So you always read one whole plan.

When Codex plan mode came out

The release notes in the Codex repo on GitHub show how it arrived.

That explains a common question from late January, when people on 0.90 could not find plan mode. It was a beta then. From the 0.94.0 release on, it is there for everyone.

Codex plan mode vs Claude Code plan mode

Both tools have a plan mode, and both use Shift+Tab and /plan. They differ in the details. The Claude Code column comes from Anthropic’s permission modes page, read the same day.

The biggest practical difference is the questions. Codex is told to ask many of them and to give each one options. Claude Code’s plan mode leans on reading and writing the plan. Neither is better for every job. If you use both tools, our Claude Code plan mode guide covers the Anthropic side in full, and Claude Code vs Codex covers price and limits.

Common problems with Codex plan mode

Plan mode is missing

You are on a build older than 0.94.0, where plan mode was a beta or off by default. Update Codex the way you installed it. The Codex README lists the install script, npm install -g @openai/codex and brew install --cask codex.

Shift+Tab or /plan does nothing

Codex is in the middle of a turn. Mode switches only happen while it is idle, and the CLI shows “Cannot switch collaboration mode while a turn is running.” if you try. Let the turn end, then switch.

Codex is stuck in plan mode

This one is a known bug. Issue #10185, “Mode switch Plan -> Code still behaves like Plan,” was opened in January on 0.92.0 and is still open. Users report it in later versions too, the most recent on 0.155.0 in October. You switch back to Default, ask Codex to go, and it says it is still in plan mode.

The reporter’s workaround is to press Shift+Tab into Plan and back again. One commenter says restarting the desktop app cleared it. A related report, #10565, was closed as a duplicate of the same issue.

No “Implement this plan?” prompt

The repo’s tests show when the prompt is skipped: when Codex gave no proposed plan, when you have messages queued, or when you sent a new message after the plan. The template also tells Codex not to ask “should I proceed?” itself. So if the prompt does not appear, press Shift+Tab to go back to Default and tell Codex to implement the plan above.

You want a stronger model for planning

There is no plan_model setting. Issue #13206 asks for one and is still open. Today you can raise plan_mode_reasoning_effort, or switch models with /model before you plan and switch back after. Planning still runs the model, so it counts toward your usage like any other work. Our guide on how to check Codex usage shows where to watch it.

Where a Codex plan stops: it lives in the chat

A Codex plan is a block in the conversation. When you implement it, Codex builds from the chat. That works for a change you finish in one sitting.

A bigger build strains it:

• The chat scrolls away. The plan is far up the scroll, and the next session starts without it unless you start from the fresh-thread option.
• There is no step status. The plan says what to build. It does not say which part is done, which one Codex stopped halfway through, or which one is blocked.
• Questions live in the session that asked them. To answer one, you go back to that terminal.
• Usage runs out mid-build. The five-hour window ends, and the next session has to work out where things stand. Our guide to Codex usage limits explains the windows.

OpenAI hit the same thing. In its long-horizon post, the run that worked kept the plan outside the chat: milestones with acceptance criteria in a plans.md file, and “a live status/audit log” in documentation.md. That is a plan with step status, kept by hand in files.

Put the plan on a Plans board instead

A Context Board Plans board is that plan and its status, kept outside any one chat. You write the plan with your agent before anything is built, then hand it to Codex in your project.

What is on it, from the board’s own docs:

• An Overview. The goal, who it is for, what done looks like, and a diagram of how the steps fit.
• One page per step. What it does, how it works, its tasks as to-dos, and the files it touches.
• Needs you. The questions only you can answer, at the top, with the agent’s pick marked. Click an answer or type your own, and the agent that asked gets it.

When the plan is ready, Hand off gives you the words to paste into Codex or Claude Code in your project. It reads the plan and starts on the first step that is not built. As it works, it marks each step: being worked on, done with what proves it, or blocked when it needs you. Tasks tick as they get done.

When Codex needs a call from you, the question waits on the plan instead of in a terminal you closed. Context Board also tells you through the browser that a plan question needs you, even with the board closed. And when a session ends halfway, Hand off again starts the next one from where the build stands, in Codex or in Claude Code.

To give Codex the board, link your computer with the one line from Connect, or run this and click Allow in the browser:

codex mcp add context-board --url https://board.contextbolt.com/mcp

Use plan mode and the board together. Plan mode is how Codex thinks through the step in front of it. The Plans board is where the whole build lives while sessions come and go. One scope note: the board does not write code. Its own chat plans with you, and Codex or Claude Code does the building.

Context Board is free for 3 days, then $12 a month for the whole workspace. The same board can show what is left of your Codex limits beside the plan, on the Codex usage widget.

Codex plan mode, quick reference

Next time a change touches more than a couple of files, start it with /plan and answer Codex’s questions before it writes a line. When the build will outlast one session, put the plan on a Plans board and hand it to Codex from there.