How Plan Mode Actually Works, and Why You Don't Always Need It

I plan a lot. Plans on plans, every day, on real work — it’s basically become the reflex before I do anything with an LLM.

And at some point I caught myself doing something dumb. I hit Shift+Tab, cycled into plan mode, out of pure habit. Not because the task needed it. Because my thumb needed it. Then I caught myself doing it again on the same day, for a task I could’ve just described in one sentence, and I stopped and asked myself: what does this button actually change? Not what I think it changes. What does it actually do, mechanically, right now, in the session I’m sitting in.

I didn’t have a good answer. I had a vibe. “Plan mode is when Claude thinks more.” That was it. That was the whole model in my head.

So I did the unfashionable thing. I sat down and read the documentation. Like I used to do with actual manuals, before “just ask the AI” became the manual. And what came out of that reading is this article — because the gap between what I believed and what’s actually true was bigger than I expected, and some of it changes how I’d tell you to use this thing.

Three dials, not one

Here’s the thing I had wrong at the root. I was treating “how smart is this session behaving” as one knob. It’s three.

Effort controls how much the model reasons. Permission mode controls how much it asks you before doing something. Context controls how much of the conversation it still remembers clearly. Three separate levers, three separate commands — /effort, Shift+Tab, and /clear / /compact / /rewind — and none of them is a stand-in for the other two.

Plan mode lives on the permission axis. Not the effort axis. It is not “the mode where Claude thinks harder about your problem.” It’s the mode where Claude is only allowed to look, not touch. That’s a different thing entirely, and conflating the two is exactly the mistake I was making with my thumb on Shift+Tab.

What the permission modes actually are

Shift+Tab cycles through three of them: default (labelled Manual — reads only, everything else asks), acceptEdits (reads, edits, and the boring filesystem stuff — mkdir, mv, rm, sed — inside your working directory, other shell commands still prompt), and plan (reads and explores, doesn’t touch sources).

There are two more you won’t see in that cycle unless you set them up going in: auto, where a separate classifier reviews every action instead of you, and bypassPermissions, which turns all of that off. There’s also dontAsk, which only runs pre-approved tools — that one’s for CI, not for a human sitting at the keyboard. And bypass specifically only shows up in your Shift+Tab rotation if you launched the session with it already enabled. You can’t discover your way into it mid-session. Fair enough.

What plan mode is actually doing while you sit there

Plan mode reads files, runs shell commands to poke around, and writes you a plan. It does not touch your sources. Edits stay locked until you say yes.

You get in with Shift+Tab, obviously. But there’s a second way in that I’d bet most people reading this don’t use: prefix a single prompt with /plan. That one plans once, using whatever context the session already has, and then — this is the part I like — it returns you to whatever mode you were in before, on its own. No manual toggling back. It’s a scalpel, not a mode switch.

Approving a plan exits plan mode, and it drops you into whichever mode the approval option describes. There are four of them: approve and run in auto mode, approve and review each edit manually, send the plan to the browser for a heavier review pass, or just keep planning. Small thing, easy to miss: Ctrl+G opens the plan in your actual text editor so you can edit it by hand before anything runs. Almost nobody does this. It’s the fastest fix available when a plan is 90% right and you don’t want to argue your way to the other 10%.

About that earlier piece of mine

Back in May I wrote about bypass, auto-edit, and planning and said bypass was my daily driver, that I’d never run into real danger with it.

I’m not walking that back. I read the docs, I found out something underneath that genuinely surprised me — I’ll get to it — but the core call still holds up for me. Bypass, by definition, asks less. And picking a mode specifically because you want to stay askable for a one-off task is a reasonable trade, not a rookie mistake I made without knowing better.

What changed isn’t the conclusion. It’s the resolution. The picture was incomplete, not wrong. I knew what these modes felt like from the outside. I didn’t know what was actually happening underneath one of them — and that part changes how I’d explain it to you now.

When to just skip the plan entirely

Before any of the underneath stuff, the most useful sentence in the whole doc, and I want to give it room instead of burying it in a list:

“For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly. Planning is most useful when you’re uncertain about the approach, when the change modifies multiple files, or when you’re unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.”

If you can describe the diff in one sentence, don’t plan. Just say the sentence. That’s the whole test, and I’d been failing it on autopilot for weeks.

Replanning: the question I actually went looking for

The thing I actually wanted answered wasn’t “what is plan mode.” It was: do I need to redo the plan every time something changes?

No. And the reason is precise, not vibes: after implementing, the model knows things it didn’t know when it wrote the plan. The traps it found while writing the code. The file that turned out different from what everyone assumed. The judgment calls made on the fly, mid-task. Starting a fresh session throws all of that away. That’s not caution, that’s amnesia.

So the actual question is never “should I replan.” It’s: is the old plan still true?

If the change is small enough to say in one sentence — just say it, no plan needed. If it’s substantial but the direction hasn’t changed, stay in the same session and prefix one prompt with /plan. If the plan turned out wrong, or the direction genuinely changed — that’s different. Write down what you learned somewhere it’ll survive, then /clear and start over clean. And if you’ve corrected the same thing twice in one session, that’s the same case wearing a disguise. Same cure.

The docs put it better than I would:

“If you’ve corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.”

And here’s the part that ties back to the three-dials thing: permission modes have nothing to do with any of this. Auto and bypass remove prompts. The plan decides what to do. You can run a very detailed, carefully-argued plan in bypass. You can run zero plans at all in Manual. They don’t know about each other.

What actually survives after the plan is written

I assumed there was some kind of index — “the files touched by this plan” — that Claude would consult later. There isn’t. There are four different things, with four different lifespans, and they age at wildly different rates.

The plan file itself survives everything — closing the session, /clear, restarting your machine. It’s just a text file. The session context survives until you /clear it or it gets compacted, which is lossy by nature. The checkpoints survive closing the terminal — you can /rewind back to one — but they only capture changes made through Claude’s own file-editing tools. Anything you did through a Bash command or an outside process doesn’t show up there. Not a replacement for version control, and it was never trying to be.

The real record of what got touched is git log and git diff. Forever. Everything else is a convenience. Git is the ledger.

Auto versus bypass, and why my instinct wasn’t crazy

Auto mode puts a separate, smaller classifier model between every action and its execution. Reads and edits inside your working directory skip it entirely — the overhead lands on shell commands and anything touching the network.

By default it blocks the stuff you’d want blocked: piping curl into bash, sending sensitive data out, production deploys, force pushes, git reset --hard, terraform destroy, writing to secret managers, merging a PR no human approved. By default it allows local file work, installing dependencies already declared in a lockfile, read-only requests, and — this one surprised me — pushing to any branch, including the one everyone treats as sacred.

Denials aren’t questions, they’re blocks. Claude gets the denial back as a result, is told to treat the boundary in good faith, and usually just routes around it. If it gets blocked three times running, or twenty times total, auto mode gives up and goes back to prompting for everything until you approve the thing that tripped it.

Now the numbers, because they’re the reason the whole feature exists. The classifier only ever sees your messages and the tool calls — Claude’s own reasoning and the tool outputs get stripped out first, on purpose, so the agent can’t argue its way past its own gatekeeper. Two passes: a fast single-token filter, then slower chain-of-thought reasoning only when the fast pass flags something. That combination drops the false-positive rate from 8.5% to 0.4%. The honest number on the other side: a 17% false-negative rate on genuinely overeager actions. Roughly one in six gets through. Anthropic says it themselves — it’s not a substitute for careful human review on anything high-stakes.

And the number that explains why this exists at all: without auto mode, people approve 93% of permission prompts anyway. At that rate the prompt has stopped being a review. It’s a reflex you’ve trained yourself into, and it stopped meaning anything a long time before you noticed.

So: bypass genuinely asks less than auto. No classifier means no denials, which means nothing ever interrupts you. It isn’t smoother because it’s smarter. It’s smoother because nobody’s checking. My instinct that this feels different from auto was correct — I just didn’t have the mechanism to explain why.

Now the actual gotcha — the one thing underneath that genuinely surprised me, verbatim from the docs:

“In sessions with bypass permissions available, Claude Code also doesn’t enforce plan mode’s blocks. Claude is still instructed to plan without editing, but a file edit or shell command it attempts during planning runs without prompting.”

Read that twice. If bypass is available in your session, your plan mode is an instruction to the model, not a wall in the system. It holds because the model chooses to respect it. Nothing underneath is stopping it. That’s the single most useful sentence in the entire doc, and it’s sitting quietly in the middle of a paragraph where nobody would think to look for it.

Rules you write yourself are the actual wall — evaluated before the classifier ever runs, and they hold in auto and in bypass both:

{ "permissions": { "ask": [
  "Bash(git push *)",
  "Bash(gh pr create *)",
  "Bash(gh pr merge *)"
]}}

An instruction in CLAUDE.md nudges Claude and the classifier both, but it’s advisory. A rule like the one above is the guarantee. The docs say it flat:

“Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or CLAUDE.md shape what Claude tries to do, but they don’t change what Claude Code allows.”

One more wrinkle worth a line: telling Claude mid-conversation “don’t push” or “wait for me before you deploy” does make the classifier respect it — but it’s not saved anywhere as a rule. It’s read fresh off the transcript every time. Which means a compaction that quietly drops that message can make your boundary disappear without either of you noticing.

Effort, quickly

Effort has five settings — low, medium, high, xhigh, max — set with /effort, or just run the command bare and it opens a slider. It’s not a “think more” switch on top of everything else, it acts on all the tokens: low effort means fewer tool calls and straight to the action, high effort means more calls and Claude actually narrating its plan before it moves. Changing it mid-conversation kills your prompt cache, so pick it going in, not halfway through. And if you just want more reasoning for one turn without touching the session setting — write ultrathink anywhere in the prompt. That’s scoped to the one turn. It doesn’t stick.

Context is the constraint underneath everything

I’ve written a whole piece on this so I’ll keep it tight here. The docs frame it better than I would’ve guessed:

“Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills.”

Two failure shapes worth naming because you’ll recognize them immediately once you hear them named: the kitchen-sink session — one task, then an unrelated one, then back to the first — fixed by /clear between unrelated things. And the correcting-in-circles session — fixed by the same rule as replanning: two failed corrections, /clear, better prompt.

Worth a line each: /context shows what’s actually eating the space. /compact <instructions> summarizes with a focus instead of a generic squash. Esc Esc or /rewind takes you back to a checkpoint. /btw <question> answers a side question without ever entering the conversation history at all. And subagents — they go explore in their own separate context and hand you back only the summary, which is exactly why the docs call them one of the most powerful tools you have when context is the thing actually running out.

So

Three levers, not one. Plan mode is a permission mode, not a thinking mode — it decides what Claude’s allowed to touch, not how hard it thinks about touching it. The question after implementing was never “should I plan again.” It’s “is the old plan still true.” And underneath all of it, in bypass, your plan mode is a promise the model keeps because it wants to, not a lock the system enforces.

I still like bypass for the small stuff. That part didn’t change. I just know now that it’s a handshake, not a wall — and there’s a difference between choosing that on purpose and not knowing it was ever the deal.

If you could describe the diff in one sentence: stop reading, go say the sentence.