ES · Leer en español Explore for free

Recipe · Basic · 10 min

Claude Code plan mode: plan before touching any code

Use Claude Code plan mode: enter with Shift+Tab or /plan, edit the plan with Ctrl+G, save it in your repo and plan with Opus using opusplan.

Cover: Claude Code plan mode: plan before touching any code

Tested with Claude Code 2.1.316 · reviewed

See the files on GitHub Free · MIT license

The problem

You ask Claude Code for a change that touches several files and it starts editing before understanding the code. By the time you see the approach was wrong, there is work to undo and you have used up limit. In code you don't know, migrations or refactors, a wrong direction is expensive.

The solution

Plan mode makes Claude investigate and propose changes without applying them: it reads files, runs exploration commands and writes a plan, but does not edit your code until you approve it. Here you will see how to enter and exit, how to approve, reject or edit the plan (Ctrl+G), where it is saved, how to combine it with opusplan and with the option to clear context on approval, and when it is not worth it.

1. What plan mode does exactly

In plan mode Claude can read files, run commands to explore and write a plan, but it does not edit your source code: edits stay blocked until you approve the plan. The only documented exception is interactive terminal sessions that have bypassPermissions available in the mode cycle; since 2.1.299 Claude Code warns once in that case.

What about shell commands while planning? If auto mode is available and useAutoModeDuringPlan is on (it is by default), the classifier reviews commands instead of asking you: approved ones run and rejected ones are blocked, except deletions of critical paths, which always ask. If auto mode is not available or you set useAutoModeDuringPlan to false, it will ask permission for any command that is not in the built-in read-only set (more on modes in Claude Code permissions).

In the documentation's mode table, plan is listed as "Reads, plus classifier-approved commands" and its recommended use is "Exploring a codebase before changing it".

2. Enter and exit: Shift+Tab, /plan and --permission-mode plan

There are four ways in:

  1. Shift+Tab cycles through modes; from auto, the first press goes to manual (default) and then the cycle continues default → acceptEdits → plan. You know you are in because the bar shows "⏸ plan mode on". On Windows, if the runtime does not enable VT input mode, the shortcut is Alt+M.
  2. /plan followed by the task enters and starts planning in one step: /plan fix the authentication bug.
  3. From the command line: claude --permission-mode plan (also with -p for runs without an interface).
  4. As a project default: "permissions": {"defaultMode": "plan"} in .claude/settings.json. VS Code sessions do not read that setting and use claudeCode.initialPermissionMode in your VS Code user settings.
claude --permission-mode plan          # the whole session starts in plan
claude --model opusplan                # plan with Opus, execute with Sonnet
# inside the session:
#   Shift+Tab (Alt+M on some Windows)  -> ⏸ plan mode on
#   /plan fix the authentication bug
#   Ctrl+G  -> edit the proposed plan in your editor

To exit without approving anything, press Shift+Tab again. If you are looking for ultraplan: the /ultraplan command was removed (2.1.222) and the documentation says to use plan mode instead.

3. Approve, keep planning or edit the plan with Ctrl+G

When the plan is ready, Claude presents it and asks how to continue:

Approving leaves plan mode and switches the session to the mode the chosen option indicates. To plan again, go back with Shift+Tab or start the next message with /plan.

The trick almost nobody uses: Ctrl+G opens the proposed plan in your default text editor so you can fix it directly (remove steps, reorder, add "don't touch the migration") before Claude starts. When you accept a plan, the session also gets a title generated from the plan, unless you have already named it. Tip: if you choose "manually approve edits" the first time you work in a repository, you will see each change before it is written.

4. Where the plan is saved and why it matters

Plans are Markdown files. By default they are saved in ~/.claude/plans (in our test: ~/.claude/plans/crea-el-archivo-nuevo-txt-silly-dream.md). With the plansDirectory key you can save them inside the project, with a path relative to the root. If the path leaves the root or uses backslashes on Linux or macOS, Claude Code falls back to ~/.claude/plans; write docs/plans, which also works on Windows.

Project .claude/settings.json to always start in plan and save plans in the repo:

{
  "permissions": {
    "defaultMode": "plan"
  },
  "plansDirectory": "./docs/plans"
}

Having it on disk has two advantages. First: the plan survives compaction, because the documentation says it is re-injected from disk when compacting, so it is not lost in long sessions (see /clear vs /compact). Second: you can version it with git next to the code, review it with your team or reuse it as a lightweight spec. Recent versions also restore plan mode when resuming with --continue, --resume or from the /resume picker.

5. Plan with Opus and execute with Sonnet: opusplan

The opusplan model alias uses opus while you are in plan mode and switches automatically to sonnet when executing. Turn it on with /model opusplan or claude --model opusplan. That way you reason about the architecture with the most capable model and write the code with a cheaper one.

There is a hidden cost the documentation explains: each model has its own cache, so each entry into or exit from plan mode with opusplan is a model switch and starts with an empty cache. Use it when there is little back and forth (you plan once, implement for a good while), not if you enter and leave plan mode every few minutes (see usage limits). If your organization restricts models with availableModels, opusplan uses the most recent allowed Opus.

Another option so you don't drag along what was explored: turn on showClearContextOnPlanAccept in ~/.claude/settings.json and the approval menu will have "Yes, clear context and …" first, which approves, clears the conversation and starts implementing with only the plan, showing how much context planning used.

{
  "showClearContextOnPlanAccept": true
}

6. When to use it and when not (and how to ask for a good plan)

Use it for changes across several files, code you don't know, migrations, refactors and anything where a wrong direction is expensive. The costs documentation recommends it precisely to avoid redoing work when the initial approach is wrong. You don't need it for a one-line change, renaming a variable or fixing an obvious bug: there the plan adds a round trip.

To ask for a good plan, give context and exit criteria: what you want, what must not be touched, how it is checked (tests, command) and to ask if anything is unclear.

/plan I want <goal>.
Context: <files or modules involved>.
Don't touch: <what cannot change>.
Done when: <tests or command that must pass>.
Before proposing the plan, read the relevant code and ask me anything that is unclear.
The plan must list files to change, steps in order, risks and how to verify each step.

Watch out with agent teams: according to the costs documentation, they use about 7 times more tokens when teammates work in plan mode, because each one keeps its own context (see subagents). And if Claude is already heading the wrong way after you approve, press Esc to stop it and /rewind (or Esc twice) to go back to an earlier point in the conversation and the code.

Check it

Quick test in a throwaway repository, to check that nothing is written in plan mode:

mkdir -p /tmp/plan-test && cd /tmp/plan-test && git init -q
claude -p --permission-mode plan --model haiku "Create the file new.txt with the text hello."
ls            # new.txt does NOT exist
ls ~/.claude/plans | tail -1   # the plan is saved

We did it on 1 Nov 2026 with Claude Code 2.1.316 on Linux: Claude wrote the plan, did not create the file and the plan was saved in ~/.claude/plans/<name>.md. We have not recorded the interactive part yet (Shift+Tab with the indicator, Ctrl+G, the three approval options, showClearContextOnPlanAccept and opusplan), and we could not check Alt+M on Windows: we describe those as the documentation does.

Why it works

Plan mode is one more permission mode: Claude Code blocks the editing tools while it is active and lets through reading and the commands the classifier or you approve. The plan is written to a file, so it doesn't depend on the conversation: it survives compaction and you can edit it with Ctrl+G. Sources: plan mode in permission modes, plansDirectory, showClearContextOnPlanAccept, opusplan, caching when switching models, interactive mode, commands and the CHANGELOG.

Common mistakes

FAQ

How do I turn on plan mode?

Shift+Tab until you see "⏸ plan mode on", /plan <task>, or claude --permission-mode plan. On some Windows setups the shortcut is Alt+M.

How do I leave plan mode without approving?

Press Shift+Tab again to move to the next mode in the cycle.

Where is the plan saved?

In ~/.claude/plans by default; change it with plansDirectory (a path relative to the project root).

Can I edit the plan before it starts?

Yes: Ctrl+G opens it in your editor. Or choose "No, keep planning" and tell it what to change.

What happened to ultraplan?

It was removed in 2.1.222; the documentation says to use plan mode instead.

Can Claude run commands in plan mode?

Yes, to explore. With auto mode available, the classifier decides; otherwise it asks you about anything that is not read-only. Code edits stay blocked until you approve (except with bypass available in the terminal).

Is opusplan cheaper?

Usually, because execution runs on Sonnet, but each switch between planning and executing is a model switch that empties the cache. It pays off with little back and forth.

The whole library