Plan mode separates exploration from execution: Claude Code reads files and drafts an implementation plan but makes no edits until you approve it. Turn it on with Shift+Tab mid-session or claude --permission-mode plan at startup. Anthropic’s recommended loop is explore → plan → implement → commit. But reverse-engineering the harness shows plan mode is mostly a short injected prompt plus a markdown plan file the agent edits — prompt reinforcement, not a hard tool lockdown.
Definitions
Plan mode — a Claude Code permission mode in which the agent reads, searches, and plans but makes no edits to your codebase until you approve the plan.
Permission mode — the harness setting that governs which actions Claude may take without asking. Plan mode is one; the default (ask-per-write) and auto (a classifier gates writes) are others.
Enable it
| Method | Command / key | Effect |
|---|---|---|
| Startup flag | claude --permission-mode plan | Begin the session read-only |
| Mid-session toggle | Shift+Tab | Flip into plan mode on the fly |
| Edit the plan | Ctrl+G | Open the plan in your text editor before Claude proceeds |
In plan mode Claude reads files and proposes a plan but touches nothing on disk. When the plan is drafted, Ctrl+G opens it in your $EDITOR for direct editing before you approve — so you correct the spec, not the diff.
The workflow: explore → plan → implement → commit
Letting Claude jump straight to code risks solving the wrong problem. Anthropic’s recommended four phases separate research from execution:
1 — Explore (plan mode). Point Claude at the relevant code and let it read.
read src/auth and explain how we handle sessions and login.
also check how we load secrets from env.2 — Plan (plan mode). Ask for a concrete implementation plan, then edit it with Ctrl+G.
I want to add Google OAuth. What files change? What's the session
flow? Write a plan.3 — Implement (default mode). Exit plan mode and let Claude code against the plan.
implement the OAuth flow from your plan. write tests for the callback
handler, run the suite, and fix any failures.4 — Commit (default mode).
commit with a descriptive message and open a PR.Separating the read-heavy explore phase from implementation is the same discipline as delegating research to a subagent: keep exploration out of the window that does the work. For how those reads accumulate in the first place, see how Claude Code’s agentic loop fills your context window.
When to use it — and when to skip
The rule of thumb: if you could describe the diff in one sentence, skip the plan.
| Use plan mode | Skip it |
|---|---|
| The approach is uncertain | Fixing a typo or adding a log line |
| The change spans multiple files | Renaming a single variable |
| You’re unfamiliar with the code | Scope is clear and the fix is small |
Plan mode is useful but adds overhead. Spend it where the uncertainty is highest, not on one-line diffs.
What the harness actually enforces
Plan mode feels like the tools are hard-locked to read-only. They aren’t. Armin Ronacher’s reverse-engineering of the harness found that plan mode is, in his words, “just a rather short predefined prompt” — the tools “turn into read-only” by instruction, not by technical restriction. The write (edit-file) tool stays available; in fact the agent uses it to edit one file while “read-only”: the plan itself.
- The plan is a file. It lives as markdown in Claude Code’s plans folder. While planning, the agent edits exactly that file and nothing else in your tree.
- The injected prompt has its own four phases — distinct from the user-facing workflow above: Initial Understanding (read code, ask clarifying questions) → Design (draft approaches with context) → Review (check alignment with the original intent) → Final Plan (concise, executable steps with the critical file paths).
- Exit reads the plan back. Approving the plan makes the harness read the plan file from disk and start executing against it. The exit is gated to code-implementation tasks, not the research phase.
The practical takeaway: plan mode’s read-only promise is behavioral, not sandboxed. If you need a hard guarantee that nothing is written — an untrusted repo, a destructive tool — reach for OS-level sandboxing or permission rules, not plan mode alone.
Plan mode vs a DIY markdown handoff
Because the mechanism is a prompt plus a markdown file, Ronacher argues you can approximate it without switching modes: iterate on a visible markdown file on disk, asking Claude clarifying questions until the plan is solid.
| Aspect | Plan mode | DIY markdown handoff |
|---|---|---|
| Enforcement | Tools flip read-only by prompt; exit gates on approval | Normal tools stay live; your discipline gates edits |
| Plan artifact | Markdown in the hidden plans folder; edit via Ctrl+G | A visible markdown file you own and version |
| Approval | Built-in approve / reject UI on exit | You read and edit the file yourself |
| Best for | The standard flow — one keystroke, built-in gate | Full transparency and control over the handoff |
The one thing the DIY route can’t cheaply replicate is the built-in approval UI on exit. Everything else — the plan, the phased prompt — is reproducible with a file and a good prompt.
Bottom line
Use plan mode to force a read-only explore-and-plan pass before Claude touches code; it’s the cheapest way to avoid building the wrong thing. Just know the read-only guarantee is prompt-enforced, not sandboxed, and the plan is only a markdown file. For the bigger discipline of controlling what enters the window during that explore pass — the context engineering that beats a bigger window — plan mode is one lever among several.