Claude Planner: How Plan Mode Works in Claude Code

A Claude planner isn't a separate product — it's Plan Mode in Claude Code, a read-only mode where Claude researches your codebase, asks clarifying questions, and writes a step-by-step Markdown plan without touching a single file. You enter it by pressing Shift+Tab twice or typing /plan; nothing gets edited or executed until you approve.

What a Claude planner actually is

Search "claude planner" and every useful result points at the same feature: Plan Mode in Claude Code, Anthropic's agentic coding tool. Anthropic never shipped a standalone planner app. What it shipped is arguably better — a switch that turns an agent that does things into an agent that proposes things. So when we say Claude planner in this guide, we mean plan mode, the feature Google is quietly resolving your search to.

Flip that switch and Claude Code loses its hands. It can still read any file in your project, search the codebase, trace call sites, and ask you questions — but file edits and shell commands stay locked until you approve a plan. The output of a plan-mode session isn't a diff. It's a numbered strategy you can read in two minutes.

We build and maintain this site with Claude Code daily, and plan mode is the feature we'd least want to lose. Not because the plans are brilliant every time — sometimes they're wrong — but because a wrong plan costs us one paragraph of feedback, while a wrong implementation costs an afternoon.

How to use Plan Mode: Shift+Tab, /plan, and flags

There are five ways to switch the Claude planner on, and knowing more than one matters, because terminals love to steal keyboard shortcuts.

Two of these earn a special mention. The Alt+M fallback exists because plenty of Windows terminals intercept Shift+Tab — if the mode indicator doesn't change when you press it, that's why. And the settings.json default is how you make planning non-optional for a whole team: commit it to the repo, and every session in that project starts in research mode.

The plan file: Markdown you can read, edit, and keep

Everything the Claude planner produces is refreshingly boring technology: a Markdown file that Claude writes into the plans folder inside your .claude directory. No proprietary format, no lock-in — numbered steps, the files each step touches, and usually a note on how to verify the result.

That plain-text choice has three practical consequences we lean on constantly:

1. You can edit it directly. Press Ctrl+G and the plan opens in your editor. Delete step 4, reword step 6, save — Claude works from the revised version. Editing the file is faster than arguing with the model in chat.
2. You can keep it. Plans survive the session as ordinary files. We paste the final plan into pull request descriptions, and reviewers consistently tell us it's the most useful part of the PR.
3. You can hand it off. A plan written for Claude is also a perfectly good brief for a human. More than once we've had plan mode produce the strategy and a colleague implement it by hand.

Why plan-first ships better code

The case for the Claude planner workflow isn't ideological; it's economic. Three observations from our own usage make it concrete:

1. A rejected plan costs a paragraph; a rejected diff costs an afternoon. Reviewing twenty lines of stated intent takes two minutes. Reviewing a 400-line diff that went in the wrong direction takes an hour — and reverting it, cleaning up, and re-prompting eats the rest of the day.
2. Read-only research is cheap insurance. Because plan mode physically cannot edit files or run commands, you can point it at code you're scared of — auth, payments, deploy scripts — and let it explore at zero risk. That guarantee comes from Claude Code's permission system, not from the model's good intentions.
3. Tokens flow one way. A wrong-direction execution burns tokens on edits, failed test runs, and reverts, then burns them again on the retry. Approving a plan first means the expensive execution pass runs once, pointed the right way. Our rough accounting: a rejected plan costs a few thousand tokens; a rejected implementation costs tens of thousands.

There's a quality effect on top of the economics. Separating "decide what to do" from "do it" gives the model room to reason before it commits — the same reason senior engineers sketch on a whiteboard before they type. Planning quality tracks reasoning ability, so model choice matters more here than anywhere else: Claude Opus 4.8 leads SWE-bench Pro at 69.2%, and hairy migration plans are exactly where that edge shows. We keep Claude Sonnet 5 as our default and escalate for the hard ones — the full reasoning is in Claude Sonnet vs Opus.

The Claude planner workflow, start to finish

Here's what a real session looks like, using a task from our own backlog: moving this site's in-memory rate limiter to Redis so it works across server instances.

1. State the goal, not the steps. "Move our rate limiter from in-memory to Redis so it survives restarts and coordinates across instances." Resist the urge to dictate the approach — the research pass is the point.
2. Claude researches. It reads the limiter module, greps for every call site, checks how the login throttle and the AI-request throttle consume it, and looks for an existing Redis connection in the config.
3. It asks before it assumes. Good clarifying questions are the tell of a good planning run. "Should failed-login counts survive a deploy?" was one we hadn't thought to ask ourselves.
4. The plan arrives. Numbered steps, files touched per step, a test strategy, a rollback note. Read all of it. Edit it with Ctrl+G, or reply with corrections in plain English.
5. Approve and execute. Claude drops out of plan mode, implements step by step, and you review diffs exactly as you would in any other session.

The planning phase for that task took about four minutes. The clarifying question in step 3 caught a design decision we would otherwise have discovered in code review — or worse, in production.

When to skip the planner

Plan mode is friction on purpose, and friction is the wrong default for trivial work. Our rule of thumb: if you'd sketch the approach before handing the task to a junior developer, plan first. If you'd just say "fix the typo," don't. The Claude planner earns its keep on risky changes and turns into pure overhead on tiny ones.

Worth knowing if you're tool-shopping: planning discipline is a differentiator, not table stakes. Cursor's agent plans too, but the control surface differs enough that we wrote a separate comparison in Cursor vs Claude Code.

Plan mode vs the auto modes

Claude Code's plan mode is one of three permission modes, and together they form a dial that runs from "propose everything" to "just go."

The pattern we've settled on after a year of daily use: plan in plan mode, execute in auto-accept, review the diff at the end. Shift+Tab cycles between modes fast enough that switching becomes muscle memory. The approved plan acts as the contract — auto-accept is only scary when the agent is improvising, and a Claude planner session ends with an agent that isn't.

Claude pricing at a glance

For the full breakdown of every plan, see our how much Claude costs guide.