INTLO— back to the INTLO LABS home pageALL CONCEPTS
07 / 20Workflow6 MIN READ

Plan Mode

Plan mode is a permission mode in which Claude reads your codebase and proposes an approach, while Claude Code blocks the edits until you approve the plan.

A plan populating as a checklistA read-only panel fills row by row with plan steps, each gaining a check mark. An approval control sits at the bottom, showing that edits stay blocked until the plan is approved.PLAN · READ-ONLYno editsAPPROVEKEEP PLANNING

What it is

Plan mode is one of six permission modes, alongside default (labelled Manual), acceptEdits, auto, dontAsk, and bypassPermissions. In plan mode Claude reads files and runs shell commands to explore, then writes a plan. Edits stay blocked until you approve it. The status bar shows ⏸ plan mode on.

What runs without asking during planning depends on your setup. With auto mode available and useAutoModeDuringPlan on, which is the default, the classifier reviews shell commands instead of prompting you: approved commands run, rejected ones are blocked. Without it, commands outside the built-in read-only set prompt for approval. Sessions with bypass permissions available skip both paths and are not blocked from editing at all — Claude is still instructed to plan, but a write it attempts goes through.

Plan mode is not a different model or a different prompt style; it is a gate. Claude Code appends the planning instructions as conversation messages, which is why entering and leaving plan mode does not invalidate the prompt cache — unless you use the opusplan model setting, which switches models at each toggle and therefore starts a fresh cache each time.

What it does for you

  • It separates "understand the problem" from "change the code", so a wrong assumption surfaces in a paragraph you can correct instead of in eighteen edited files you have to revert.
  • It gives you an artifact to argue with. The plan is text: you can edit it in your editor with Ctrl+G before Claude proceeds.
  • It keeps research out of the main context window. During planning Claude delegates codebase research to the built-in Plan subagent, so the exploration output fills a separate context window.

How it works

  1. 01You enter plan mode

    Press Shift+Tab to cycle default → acceptEdits → plan, prefix a single prompt with /plan, or launch with claude --permission-mode plan.

  2. 02Reads are free, writes are blocked

    Claude reads files and runs read-only commands without prompting. Edit, Write, and NotebookEdit are blocked. Writes to protected paths such as .git and .claude are prompted rather than auto-approved.

  3. 03Shell commands take one of two paths

    With auto mode available and useAutoModeDuringPlan on, the classifier decides. Otherwise anything outside the read-only set prompts — including when the sandbox’s auto-allow mode is on, because plan mode deliberately skips that substitution.

  4. 04Research is delegated to the Plan subagent

    Codebase exploration runs in a separate context window with Write and Edit denied, so the main conversation stays small and read-only.

  5. 05Claude presents the plan for approval

    You choose Yes, and use auto mode (or Yes, auto-accept edits when auto mode is unavailable), Yes, manually approve edits, or No, keep planning. Press Ctrl+G to open the plan in your editor first.

  6. 06Approval exits plan mode into the mode you picked

    Claude starts editing immediately. Approving also names the session from the plan content, unless you already set a name with --name or /rename. With showClearContextOnPlanAccept enabled, the list gains a first option that approves the plan and clears the planning context in one step. To plan again, cycle back with Shift+Tab or prefix the next prompt with /plan at any point.

How to implement it

  1. 01Enter plan mode before describing the change

    Press Shift+Tab until the status bar reads ⏸ plan mode on, then state the task. Entering after Claude has started means the first edits already happened.

  2. 02Ask for the parts you actually need to check

    Say which files you expect to change, what the migration path is, and what could break. A plan that only lists steps hides the assumptions you wanted to catch.

  3. 03Read the plan against the code, not against the prompt

    The failure mode is a plan that is internally coherent and wrong about your codebase. Check the file paths and function names it names actually exist.

  4. 04Edit the plan rather than re-prompting

    Press Ctrl+G to open it in your editor, fix the wrong step, and save. That is faster than describing the correction in prose.

  5. 05Pick the approval mode to match the risk

    Choose manual approval for anything touching auth, migrations, or infrastructure. Choose auto mode when you trust the direction and want the run uninterrupted.

Examples

Planning an auth migrationbash
# Start the session in plan mode
claude --permission-mode plan

# Or enter it for one prompt from inside a session
/plan migrate session auth to signed JWTs without logging anyone out

# Or cycle into it: Shift+Tab until the status bar reads "⏸ plan mode on"
Start in plan mode, or make it the default for a project that warrants it.
.claude/settings.jsonjson
{
  "permissions": {
    "defaultMode": "plan"
  },
  "useAutoModeDuringPlan": true
}
Make plan mode the default for a repository where unplanned edits are expensive.
The prompt that makes a plan usefulmarkdown
Migrate session auth from server-side sessions to signed JWTs.

Before proposing steps, answer these from the code, not from convention:

1. Which files read `session[:user_id]` today, and which of them are hot paths?
2. Where is the session cookie set, and what else rides on that cookie?
3. What happens to a request that arrives mid-deploy with an old session
   cookie and hits a new instance?
4. Which tests assert on session state directly and will need rewriting?

Then give me the migration in stages that each ship independently. For every
stage, name the files you would change and the one thing that would tell me
the stage went wrong in production.
A plan is only as good as what you asked it to be specific about.

Use it when

  • A migration that touches many files, where the order of the steps matters more than any single edit.
  • Work in a codebase you have not read, so the plan doubles as a map of what is involved.
  • Any change to authentication, permissions, billing, or migrations, where a wrong assumption is expensive.
  • A task where you suspect the request is ambiguous and want the ambiguity surfaced before code is written.
  • Handing work to a teammate: the approved plan is a reviewable description of what is about to happen.

Avoid it when

  • The change is one file and you already know which one. Planning adds a round trip and a plan you will skim.
  • You are exploring rather than deciding. Plain read-only questions get answers faster without the plan-and-approve ceremony.
  • You are iterating on something you will revert anyway. Checkpointing already lets you undo, and /rewind truncates back to a cached prefix rather than building a new one.
  • The session has bypass permissions available. Plan mode’s blocks are not enforced there, so it gives you the ceremony without the guarantee.

Common mistakes

  • SYMPTOMClaude edits files while you thought you were planning.

    FIXCheck the status bar for ⏸ plan mode on. In a session with bypass permissions available, plan mode does not block writes at all — start that session without the bypass flag.

  • SYMPTOMYou approve a plan, then realise one step was wrong and re-explain it in prose.

    FIXPress Ctrl+G at the approval prompt to open the plan in your editor and fix the step directly, before Claude proceeds.

  • SYMPTOMThe plan is confident about files and functions that do not exist.

    FIXAsk the planning prompt to quote the code it is reasoning about. A plan that cites file:line can be checked; a plan written from convention cannot.

  • SYMPTOMEvery plan-mode toggle makes the next turn slow and expensive.

    FIXThat is the opusplan model setting: it resolves to Opus during planning and Sonnet during execution, so each toggle is a model switch and starts a fresh prompt cache. Pin a single model instead.

  • SYMPTOMRead-only exploration keeps stopping for permission prompts.

    FIXPlan mode deliberately skips the sandbox auto-allow substitution. Enable auto mode with useAutoModeDuringPlan, or add allow rules for the specific exploration commands you use.

Best practices

  • Enter plan mode before your first sentence about the task, not after Claude has started.
  • Ask the plan to answer specific questions from the code, and to cite file:line for each answer.
  • Require staged steps that ship independently, with a failure signal named for each stage.
  • Edit the plan with Ctrl+G instead of arguing with it in prose.
  • Match the approval mode to the blast radius: manual approval for auth, migrations, and infrastructure.
  • Set "defaultMode": "plan" in a repository’s .claude/settings.json when unplanned edits there are routinely expensive.

Try it in five minutes

Watch plan mode block a write, then approve into a mode you chose.

  1. 1.In any repository, run claude --permission-mode plan and confirm the status bar shows ⏸ plan mode on.
  2. 2.Ask: "Add a --verbose flag to the CLI entry point." Claude reads files and proposes a plan instead of editing.
  3. 3.Ask it directly to write the change now. The edit is blocked and Claude says so.
  4. 4.Press Ctrl+G, add a line to the plan requiring a test, and save.
  5. 5.Approve with Yes, manually approve edits and watch the mode change in the status bar as the first edit prompt appears.

Related concepts

Verified against code.claude.com/docs/en/permission-modes on 2026-08-09. See content/SOURCES.md for the full table.

← / → MOVE BETWEEN CONCEPTS