Plan Mode is a Claude Code feature that flips the agent into a read-only state where it analyzes your codebase, drafts a step-by-step execution plan, and waits for your approval before writing a single file — and it’s the single biggest leverage feature most founders never use. Yesterday I gave Claude Code a 4-line prompt asking it to migrate my entire /blog route to /journal with 301 redirects, sitemap updates, and internal-link rewriting. Plan Mode came back 47 seconds later with a 14-step plan covering 23 files. I rejected step 11 (it was going to modify a file I didn’t want touched), Claude regenerated, I approved, and the migration shipped in 8 minutes.
Without Plan Mode, that same task would have either succeeded (with me unable to course-correct mid-flight) or failed in a way that left my repo in a half-migrated state with broken redirects. Plan Mode is the difference between “trusting the agent” and “trusting the plan, then trusting the agent to follow the plan.”
This article is the tutorial I wish I’d had on Plan Mode in January 2026. If you’ve read my Claude Code first 30 days, this is the day 14+ upgrade.
What is Plan Mode?
Plan Mode is a state in Claude Code where the agent operates with read-only filesystem access. It can:
- Read files
- Run commands that produce output (grep, ls, cat, npm list, etc.)
- Search the codebase
- Output a structured plan
It cannot:
- Edit files
- Create files
- Delete files
- Run commands that mutate state (rm, mv, git commit, npm install with
--save)
The plan is the deliverable. Once you approve it, Claude Code drops out of Plan Mode and executes the approved steps. You can also reject the plan, modify it, or send Claude back to refine it.
Plan Mode was introduced in Claude Code v1.4 (early 2026) and has been refined through several patch releases. As of May 2026, it’s the default suggestion any time you trigger a task that involves “complex” file changes (Claude Code prompts you).
When to use Plan Mode
The honest rule: any task that touches 3 or more files, or involves refactoring code you didn’t write yourself, deserves Plan Mode.
| Task type | Plan Mode? | Why |
|---|---|---|
| Single-file edit you can describe in one sentence | Skip | Obvious change, plan is overhead |
| Multi-file refactor (2+ files) | Yes | Plan catches scope creep |
| Migration (route, schema, naming) | Always | High blast radius if wrong |
| Bug fix where you understand the root cause | Skip | Direct edit is faster |
| Bug fix where you DON’T understand the root cause | Yes | Let Claude investigate before changing |
| Adding a new feature touching 3+ files | Yes | Plan surfaces dependencies you missed |
| Updating dependencies / config | Yes | High blast radius |
| Writing a single function from scratch | Skip | Direct prompt is fine |
| Writing a complete module / new file | Yes | Plan ensures structure matches your repo conventions |
| Content generation (blog post, README) | Skip | Single-file output, Plan adds no value |
The pattern: Plan Mode is most valuable when (a) you’re uncertain what the agent will touch or (b) the cost of touching the wrong thing is high. For low-blast-radius single-file work, skip it.
The 4-step Plan Mode routine
This is the workflow I run every time. It takes 90-120 seconds for a normal task; 5-10 minutes for a complex migration.
Step 1 — Trigger Plan Mode
Two ways:
# Method 1: Shortcut
Shift+Tab inside any Claude Code session
# Method 2: Slash command
/planBoth put Claude Code into the read-only state. The terminal usually shows a small banner like [PLAN MODE — read-only] so you know you’re in it.
State your task in natural language. Be specific. The same prompt rule that applies in normal Claude Code applies here, just more so: vague prompts produce vague plans.
Bad: “Migrate blog to journal.” Good: “I’m renaming the
/blogroute to/journalacross this Astro project. I need: (1) the new route created with same content collection, (2) 301 redirects inastro.config.mjsfor old URLs, (3) internal links in articles updated, (4) the sitemap regenerated, (5) thellms.txtupdated. Show me the plan before touching anything.”
The second prompt produces a useful plan. The first produces a useless one.
Step 2 — Review the plan
Claude Code outputs a numbered list of steps. Each step typically includes:
- What action will be taken
- Which file(s) it touches
- Why (brief reasoning)
- Any dependencies on previous steps
A real plan from my repo (May 2026, slug migration):
PLAN — /blog → /journal migration
Step 1: Read all 47 .mdx files in src/content/blog/ to inventory internal links
Step 2: Create new collection schema at src/content/journal.ts mirroring blog.ts
Step 3: Move all 47 .mdx files from src/content/blog/ to src/content/journal/
Step 4: Update src/pages/journal/[slug].astro to use the journal collection
Step 5: Add 301 redirects in astro.config.mjs for all 47 old URLs
Step 6: Update internal links in all 47 articles from /blog/ to /journal/
Step 7: Update src/pages/sitemap.xml.ts to reference journal collection
Step 8: Update public/llms.txt URLs (47 entries)
Step 9: Update components/Footer.astro link reference (1 occurrence)
Step 10: Run build, verify 0 broken links via @astrojs/check
Step 11: Verify all 47 redirects return 301 via curl test script
Step 12: Update sitemap submission in robots.txt (no change needed)
Step 13: Stage all changes, commit with message "feat: /blog → /journal migration"
Estimated time: 4-6 minutes
Files touched: 51 (47 articles + 4 config files)
Risk: Medium. Mitigations: 301 verification step, build check step.
Reversible? Yes. Single revert commit restores all changes.Read every step. If a step references a file you didn’t expect, that’s the signal to intervene.
Step 3 — Request edits (this is the magic)
If anything in the plan is wrong, missing, or excessive, you tell Claude Code in plain English. The agent regenerates the plan.
Example interactions I’ve had:
“Skip step 8 — the llms.txt update is already handled by a separate cron job.”
“Add a step after step 4 to run TypeScript check before continuing.”
“Step 6 should preserve the existing internal-link structure where pages link to specific section anchors, not just the page itself.”
“Replace step 11 with a Lighthouse check instead of curl, I want LCP confirmed too.”
Each edit triggers a re-plan. You can iterate 3-5 times before the plan is right. Don’t approve until it is.
Step 4 — Approve and execute
When the plan looks correct, type approve (or the prompt Claude Code shows you — UI changes occasionally). Claude Code exits Plan Mode and executes the steps in order. You watch it work in your terminal. If any step fails, Claude Code stops and reports the failure rather than blindly continuing.
After execution, Claude Code typically runs a verification pass (build, tests, lint) and reports results. If verification fails, it does NOT auto-retry — it stops and waits for your input.
This is the pattern: humans approve the strategy, agents execute the strategy, humans review the results. The plan is the contract between you and the agent.
The 5 mistakes I made before I learned to plan
Mistake 1 — Skipping Plan Mode “because it’s just a small change”
I refactored my astro.config.mjs in February 2026 without Plan Mode. The change was “small” — add 4 redirects. Claude Code added 4 redirects AND removed a custom integration block it thought was unused. The integration was my image pipeline. Production deploy failed. I spent 35 minutes rolling back and re-adding what was deleted.
Plan Mode would have shown me “Step 2: Remove custom integration block at lines 47-52.” I would have caught it. The “small change” rule isn’t safe enough.
Mistake 2 — Approving plans without reading every step
I shipped 3 plans in one morning without reading them carefully. By the third, Claude Code had added a step to “update the test suite to reflect the new behavior” — which actually meant deleting 6 tests that no longer passed. The tests were correct; the behavior change was a bug. I had to restore them from git.
Read every step. Always.
Mistake 3 — Not editing the plan
The first 30 plans I approved, I either approved or rejected them as-is. It took me a month to realize you can edit plans. Once I did, I was iterating 2-4 times per complex task before approving. The output quality went up 40% qualitatively. Don’t be passive with Plan Mode — actively shape the plan.
Mistake 4 — Using Plan Mode for content writing
Plan Mode is for code, not for content. I tried using it for writing a 2,500-word article. Claude Code came back with a plan like “Step 1: Draft introduction. Step 2: Write H2 section. Step 3: …” That’s not useful. The plan adds overhead without clarity. For content, just write the brief and let the agent draft.
The line: use Plan Mode when execution involves discrete, ordered file changes. Skip it when output is a single artifact.
Mistake 5 — Not chaining Plan Mode with subagents
The most powerful pattern I discovered in month 3: Plan Mode + subagents. Plan Mode generates the strategy. Each step in the plan can be assigned to a different subagent. A migration plan might look like:
Step 4 → @researcher subagent (read all 47 articles, output link map)
Step 6 → @editor subagent (update internal links per link map)
Step 11 → @verifier subagent (run curl tests, output report)Claude Code orchestrates the chain. Each subagent has scoped responsibility. The plan ties them together. This is the pattern that makes Claude Code feel like a team instead of a tool.
A real Plan Mode session, end-to-end
For concreteness, here’s the actual session I ran last Tuesday on a real 500k.io task.
My prompt: “I want to add a dateModified field to all 47 articles in src/content/journal/. The value should come from each file’s most recent git commit timestamp. Update the schema, the article frontmatter, and ensure the schema validates after.”
Plan Mode output (paraphrased for brevity):
PLAN — Add dateModified field to all articles
Step 1: Read src/content/journal.ts to find current schema
Step 2: Add `dateModified: z.coerce.date().optional()` to schema
Step 3: For each of 47 files in src/content/journal/, run `git log -1 --format=%aI <file>`
Step 4: Update frontmatter of each file with `updatedAt: <git timestamp>`
Step 5: Run `astro check` to validate
Step 6: If any file fails, report and pause
Step 7: Commit with message "feat: add dateModified field to journal articles"
Files touched: 48 (1 schema + 47 articles)
Estimated time: 90 seconds
Reversible? Yes, single revert.My edit: “Use publishedAt as fallback if git history is shallow or missing for a file. Don’t fail on those, fall back gracefully.”
Re-planned with that edit, I approved. Execution took 84 seconds. All 47 files updated. Schema validated. Single commit. I reviewed the diff for 3 minutes, pushed.
Total Plan Mode overhead: ~2 minutes (writing prompt, reading plan, editing once, reading re-plan). Total execution: 84 seconds. Total task: 4 minutes. Without Plan Mode, I would have either typed the same prompt blind (and lost time when the schema didn’t validate) or done it manually (45-60 minutes).
When NOT to use Plan Mode (the honest list)
Plan Mode is great. It’s not always great. Cases where I skip it:
- Pure content writing. Article drafts, READMEs, marketing copy. Plan adds overhead, no value.
- Trivial single-file edits. “Add a function called
slugifytosrc/lib/utils.ts.” Just say it. - Exploration / questions. “How does this codebase handle authentication?” That’s a question, not a task. Use the chat-style mode.
- When you don’t have time to read the plan carefully. If you’re in a rush and would approve any plan blindly, you’ve defeated the point. Skip Plan Mode and do the work yourself (which forces you to think) or wait until you have 5 minutes.
The line: Plan Mode is a forcing function for human attention. If you’re not going to give it attention, don’t trigger it.
Plan Mode + the 30-day Claude Code routine
If you’ve read Claude Code first 30 days, here’s how to layer Plan Mode in:
- Day 1-7: Don’t use Plan Mode yet. Get the basics down first.
- Day 8-14: Try Plan Mode on 2-3 multi-file tasks. Get comfortable with the read-review-edit-approve loop.
- Day 15-30: Make Plan Mode default for anything touching 3+ files. By day 30, the muscle memory is set.
- Beyond day 30: Plan Mode + subagent chains. This is where the leverage compounds.
For the wider Claude Code ecosystem, see Building Your First MCP Server and Claude Code beginner guide 2026.
The honest verdict on Plan Mode
Plan Mode adds 30-60 seconds to every task that uses it. That’s the cost.
The save: I’ve avoided at least 5 multi-hour cleanup sessions in the last 90 days because Plan Mode caught something I would have missed. The conservative ROI is 50x. The actual ROI is probably 100x for any founder running real workflows.
If you’re not using Plan Mode in Claude Code, you’re paying the same $100/month subscription and getting roughly 60% of the value. The other 40% lives in the 30 seconds you’d save by skipping it. Don’t skip it.
FAQ
What does Plan Mode actually do in Claude Code?
It flips Claude Code into a read-only state where it can analyze your codebase, propose a sequence of changes, and present the plan for your approval — but it can't edit a single file until you accept the plan. Think of it as 'commit to a strategy before you commit to code.' Triggered with the Shift+Tab shortcut or the /plan slash command.
When should I use Plan Mode vs just typing a task?
Use Plan Mode for any task that touches 3+ files, requires understanding the existing code, or involves a refactor. Skip Plan Mode for trivial single-file edits where the change is obvious. The cost of Plan Mode is ~30-60 extra seconds. The save is the time you'd lose unwinding a bad multi-file edit.
Does Plan Mode use more tokens than regular mode?
Yes, slightly. Plan Mode reads more of your codebase to build the plan, which uses tokens. On Max 5x at flat-rate pricing, this doesn't matter. On per-token pricing, expect ~20-40% more token use for the planning phase. The savings on rework usually offset it.
Can I edit the plan before approving?
Yes. Once Claude Code outputs a plan, you can reply with edits ('skip step 3,' 'add a test before step 2,' 'use library X instead of Y'). The plan re-generates. You can iterate 3-5 times before approving. After approval, Claude Code executes the steps in order.
What's the most common Plan Mode mistake?
Approving a plan without reading the steps carefully. The plan is the only checkpoint before Claude Code starts editing. If step 4 says 'refactor `lib/db.ts`' and you didn't realize that file is your entire database layer, you've just authorized a much bigger change than you intended. Read every step. Reject if anything is unclear.