Claude Code plan mode: plan first, then let it build

Claude Code plan mode is the simplest way to stop an agent from charging off in the wrong direction. Instead of editing files straight away, Claude explores your code, asks what it needs to know and writes a plan. You read it, push back, and only when it looks right do you let it build. This guide covers how plan mode works today, how to turn it on, when it’s worth it and how to combine it with subagents and CLAUDE.md.

Everything here was checked against Anthropic’s permission modes docs and common workflows in October 2026.

What is Claude Code plan mode?

Plan mode is one of Claude Code’s permission modes. In it, Claude can:

• read files and search the codebase,
• run shell commands to explore, such as listing files or reading git history,
• ask you clarifying questions,
• write a plan.

What it doesn’t do is edit your source code. The plan is a proposal, not a change. While plan mode is on, the status bar shows ⏸ plan mode on.

The point is to separate thinking from doing. In the default mode, Claude often starts editing after a quick look around. On small tasks that’s exactly what you want. On a large change it means you find out about a wrong assumption after ten files have been touched.

How to enter plan mode

There are three ways in, depending on how long you want to stay.

Shift+Tab: switch the current session

Press Shift+Tab to cycle through permission modes. The order is:

1. Default (Claude asks before edits and commands)
2. Accept edits
3. Plan mode
4. Bypass permissions, only if you started with it enabled
5. Auto mode, only if it’s available to you

Then it wraps around to default. Stop when the status bar shows plan mode. Press Shift+Tab again to leave plan mode without approving anything.

/plan: plan a single prompt

Type /plan before a prompt to plan just that request:

/plan migrate the session store from Redis to Postgres

This is handy when you mostly work in default mode and only want a plan for the occasional big task.

Start a session in plan mode

claude --permission-mode plan

If you want every session to start in plan mode, set it as the default in .claude/settings.json:

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

In the VS Code extension, set claudeCode.initialPermissionMode to "plan".

Plan mode compared with the other modes

Plan mode is the only one where edits wait for a whole plan, not a single change. For the riskier end of the scale, see skipping permissions in Claude Code.

Shift+Tab, permission modes and the rest of the shortcuts are collected in the Claude Code commands cheat sheet.

What happens when the plan is ready

When Claude finishes planning, it shows the plan and asks how to proceed. The options are:

• Yes, and use auto mode: approve and let Claude work with auto mode’s safety checks. If auto mode isn’t available, this reads “Yes, auto-accept edits” instead.
• Yes, manually approve edits: approve, but review each edit as it comes.
• No, keep planning: send feedback and get a revised plan.

If you turn on the showClearContextOnPlanAccept setting, an extra first option approves the plan and clears the planning conversation, so the build starts with a clean context that holds only the plan.

Approving exits plan mode. A few other things worth knowing:

• Ctrl+G opens the plan in your editor so you can edit it directly before approving.
• Plans are saved as files, in ~/.claude/plans/ by default, or in a folder you set with plansDirectory.
• Accepting a plan gives the session a generated title, which makes it easier to find later.

Shell commands during planning

Exploring often means running commands. If auto mode is available and useAutoModeDuringPlan is on, which it is by default, a classifier reviews those commands the way it would in auto mode. Otherwise, anything outside a set of read-only commands asks for your approval first. Either way, plan mode isn’t a sandbox for arbitrary commands; it’s a mode where Claude doesn’t edit your code.

When to use plan mode

Plan mode is worth it when a wrong first step is expensive.

A good rule of thumb: if you’d sketch the change on paper before doing it yourself, ask Claude for a plan first.

Plan mode also helps when you’re learning a codebase. Ask “how does authentication flow from the login form to the session store?” in plan mode and Claude explores and explains without the risk of touching anything.

A plan-then-execute workflow

Anthropic’s own recommended loop has four steps: explore, plan, implement, commit. In practice it looks like this.

1. Explore

Enter plan mode and point Claude at the area:

Read src/billing and the tests under tests/billing.
Explain how invoices are generated and where taxes are applied.
Don't propose changes yet.

Correct anything it gets wrong now. Misunderstandings are cheapest at this stage.

2. Plan

Ask for the plan with the constraints that matter:

Plan how to add per-country tax rates.
Keep the public API unchanged, add a migration, and list the tests you'd add.

A good plan names the files it will change, the order, the risks and how it will verify the result.

3. Push back

Don’t approve the first draft by reflex. Pick “No, keep planning” and say what to change: “Do the migration in a separate step”, “Don’t touch the PDF renderer”. Or press Ctrl+G and edit the plan yourself.

4. Execute

Approve. If you trust the plan, “Yes, and use auto mode” lets Claude work through it without stopping at every edit. If the change is risky, choose manual approval.

5. Verify and commit

Ask Claude to run the tests it listed in the plan. If something went wrong, Escape stops Claude, and /rewind (or pressing Escape twice) takes you back to an earlier checkpoint. Once it passes, commit.

For a bigger change, save the plan file and start the build in a fresh session. The plan becomes the prompt, and the build starts with a context full of decisions, not exploration.

Use a stronger model for planning

The opusplan model alias uses Opus while you’re in plan mode and switches to Sonnet for execution. You get Opus-level reasoning for the decisions and Sonnet’s lower cost for the typing. Set it with /model opusplan. On subscriptions, that also stretches your usage limits.

Plan mode and subagents

Plan mode works well with subagents, and Claude Code already uses them for it.

• The built-in Plan subagent: during plan mode, Claude can hand research to a Plan subagent. It has read-only tools, uses the same model as the main conversation, and does its digging in its own context, so the main conversation only gets the findings. It starts without your CLAUDE.md and without the git status snapshot, and it runs once; it can’t be resumed.
• The Explore subagent: another read-only built-in, tuned for quickly searching and reading the codebase.
• Subagents stay in plan mode: when the main conversation is in plan mode, subagents it starts stay in plan mode too. You don’t get a surprise edit from a helper.

Because research happens in separate contexts, the main conversation stays smaller. That keeps the plan focused and leaves more of the context window for the build.

You can also ask for parallel research directly: “In plan mode, use subagents to look at the API layer, the database layer and the frontend separately, then give me one plan.” One caveat from Anthropic’s cost docs: agent teams with teammates in plan mode use roughly seven times the tokens of a standard session, so save that for changes that justify it.

Plan mode and CLAUDE.md

Plan mode is only as good as the context Claude starts with. That’s where CLAUDE.md comes in. A few lines there make plans noticeably better:

## Planning
- Plans list the files to change, in order, and the tests to add.
- Database changes always get their own migration step.
- Never change public API signatures without calling it out.
- Run `pnpm test` and `pnpm lint` to verify.

Keep two details in mind:

• The built-in Plan subagent doesn’t see CLAUDE.md, so put project-wide rules there for the main conversation, and include anything critical in your prompt when you ask for research.
• Keep CLAUDE.md short. It’s sent on every turn, so a long one costs tokens in every mode. Move long procedures into skills.

If your team always plans before building, make plan mode the default in the shared .claude/settings.json and describe what a good plan looks like in CLAUDE.md. Everyone gets the same behaviour without having to remember it.

Common mistakes

• Approving without reading. A plan you didn’t read is just a slower default mode.
• Planning tiny tasks. For a typo fix, plan mode only adds a round trip.
• Plans that are too vague. “Refactor the auth module” isn’t a plan. Ask for files, order and verification steps.
• Never clearing after planning. Exploration fills the context. For big builds, approve with the clear-context option or start a new session from the plan file.
• Assuming plan mode is a sandbox. It stops source edits; it doesn’t turn the terminal into a safe playground. Review commands as you would anywhere else.

Planning in AgentVera

AgentVera is a desktop app for macOS, Windows and Linux that runs Claude Code and other CLI agents side by side, per project. Each pane is the real Claude Code terminal, so Shift+Tab, /plan and the plan approval options work just as they do on their own. AgentVera adds structure around them:

• Task line: a task moves through Analysis, Plan, Build and Review. Each stage writes its output to a file, such as 02-plan.md, and the next stage starts from it, so the plan travels with the task instead of living in one conversation.
• Flows: chain steps such as research, plan and build, so the same plan-then-execute loop runs the same way every time.
• Auto approval: once a plan is approved, safe reads and tests go through without prompts, while things like git push or rm still ask.
• Checkpoints and replay: the last 60 turns per agent are kept, so you can go back if a build drifts from the plan.

Checkpoints are on the free plan. Task line and auto approval are on Pro and Team. If you’re new to running several agents, start with how to use Claude Code and download AgentVera.

Wrapping up

Plan mode makes Claude explore and propose before it edits. Turn it on with Shift+Tab, /plan or --permission-mode plan, read the plan properly, push back with “No, keep planning” or Ctrl+G, and only then approve. Use it for multi-file changes, unfamiliar code and anything risky; skip it for small fixes. Pair it with a short, specific CLAUDE.md, let the read-only subagents do the digging, and try opusplan to plan with Opus and build with Sonnet.