Claude Code plan mode: how to use it and when it pays off

What plan mode actually restricts

In plan mode Claude keeps every read tool and loses the ability to write to your source. It can still run shell commands, which is what makes the research useful: it can run git log, list a directory, or grep for a symbol. What it cannot do is leave a change behind.

Three ways to enter it

# Interactive, already gated
claude --permission-mode plan

# Non-interactive: produce a plan, change nothing
claude -p --permission-mode plan "how would you add rate limiting to the public API?"

Making it the default

If you want plan mode to be the starting posture for a repository rather than a habit you have to remember, set it in that project’s settings file. Put it in ~/.claude/settings.json instead to make it your personal default everywhere.

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Plan mode is one rung on a ladder

People conflate plan mode with permissions in general. They are the same system: plan is one of the permission modes, and the mode sets the baseline that your allow, ask, and deny rules then layer on top of.

The other thing worth knowing: permissions.allow rules do not pre-approve writes to protected paths. The protected-path check runs before allow rules are evaluated, so an Edit(.claude/**) entry in your settings does not change what happens when Claude tries to edit its own configuration mid-plan.

The approval prompt

When the plan is ready, Claude presents it and asks how to proceed. The choices are not yes and no.

• Yes, and use auto mode. Approves and starts executing with the classifier reviewing actions rather than prompting you. Where auto mode is unavailable this option reads Yes, auto-accept edits instead.
• Yes, manually approve edits. Approves the approach and puts you back in the loop on each change.
• No, keep planning. Stays in plan mode and takes your objection as input. This is the option people forget exists, and it is the one that makes plan mode a negotiation instead of a gate.

Approving exits plan mode and switches the session into whichever mode the option describes, with the plan and all the research still in context. Claude does not re-explore, which is a large part of why plan mode is cheaper than it looks on paper.

Edit the plan before you approve it

Press Ctrl+G at the approval prompt to open the proposed plan in your default text editor. You can delete a step, add a constraint, or rewrite the whole thing, and Claude proceeds from your version. This is faster than three rounds of "no, not like that" and it produces a plan you actually own.

When it earns its keep

The failure it prevents

The expensive failure with agents is not bad syntax, it is a plausible wrong approach executed thoroughly. An agent that decides to add a caching layer where you wanted a query fix will write clean, tested, well-named code that solves the wrong problem. You then have to read all of it to discover that.

The honest cost

Plan mode adds a research and proposal round trip before any work happens. On a one-line fix that round trip is pure overhead: you pay tokens and wall-clock time to be told what you already knew. The break-even is roughly the point where you would not be able to review the resulting diff in one sitting.

Getting plans worth approving

A vague request produces a vague plan, which is worse than no plan because it looks like agreement.

/plan Add idempotency keys to the payments endpoint in @internal/payments/handler.go.
Constraints: reuse the existing Redis client, no new dependencies, 24h key TTL.
Before the steps, list the two approaches you considered and why you dropped one.
End with the files you will touch and which are covered by tests.

After approval

Two habits are worth building around the approval boundary.

• Commit at plan boundaries. If the plan had four steps, four commits give you somewhere to roll back to that is not "the beginning". Ask for this in the plan itself and it happens without you watching.
• Re-plan on surprise. If step two reveals the codebase is not what the plan assumed, cycling back to plan mode with Shift+Tab beats letting the agent improvise its way out. The improvisation is where the plausible-wrong-approach failure comes back.

The Codex equivalent

Codex has no feature called plan mode, but it reaches the same place from the other direction. Where Claude Code gates the write tools, Codex gates the filesystem: start it with a read-only sandbox and it can research and propose without the ability to modify anything.

codex -s read-only "how would you restructure the billing package? do not change anything"

The difference in feel is that Claude Code produces a discrete plan artefact with an approval prompt attached, while Codex produces a message you then act on yourself by restarting with a writable sandbox. The Claude flow is better when you want the plan reviewed by somebody else; the Codex flow is better when you were going to make the call yourself anyway.

Questions people ask

Keep reading