Jonathon's AI Wiki

Plan Mode — Claude Code Planning Surface

5 min read

Source: wiki synthesis: nate-herk-every-level-of-claude, claude-code-goal-command-walkthrough, nate-herk-codex-1-hour-course

Plan Mode is the Claude Code primitive that separates planning from execution. Toggled with Shift+Tab Shift+Tab, it puts the agent into read-only research mode — Claude reads the codebase, asks clarifying questions, and presents a plan that waits for human approval before any file is touched. It is the L4 “Advanced” surface in Nate Herk’s 5-level Claude Code progression, paired with a hidden Opus Plan setting that lets Opus do the thinking while Sonnet does the typing — “cuts cost in half without losing quality.”

Key Takeaways

  • Read-only planning surface. Plan Mode prevents Claude Code from executing anything during the planning turn — it can read files and search the codebase, but writes, edits, and shell side effects are gated until the user approves the plan. ^[inferred]
  • Shift+Tab Shift+Tab toggle. Cycle through input modes by pressing Shift+Tab twice; the same Shift+Tab chord lands in auto-mode on the first press, Plan Mode on the second (see nate-herk-every-level-of-claude for the L4 mode cycle).
  • Approval gate before execution. Claude reads the relevant files, surfaces clarifying questions if the goal is ambiguous, drafts a plan, and waits. Nothing is written to disk until the user accepts. This is the structural difference between “vibe coding” and the agentic-engineering pattern Karpathy describes.
  • Hidden Opus-Plan / Sonnet-Execute setting. The hidden setting routes the planning turn through Opus (smart, expensive) and the execution turns through Sonnet (cheap, fast). Per the Nate Herk source: “Cuts cost in half without losing quality.” Smart model where it matters, cheap model for grunt work.
  • Pairs with the /goal command. The claude-code-goal-command-walkthrough walkthrough recommends entering Plan Mode first so the agent can draft a verifiable completion-condition plan, then handing that plan to /goal for a long-running converged session. This prevents the “too open-ended goal → not enough context to work correctly” failure mode.
  • Same primitive shows up in Codex CLI. Nate Herk’s Codex 1-Hour Course describes a near-identical “Plan Mode” toggle in OpenAI’s Codex CLI — same toggle-prevents-execution semantics, same recommendation to “always start here when building something new.”
  • The L4 unlock. Plan Mode is one of the five things that “make L4 click” in the Every Level of Claude framework — alongside CLAUDE.md, sub-agents, worktrees, and the CLI-over-MCP discipline.

How Plan Mode works

  • Toggle in. Press Shift+Tab Shift+Tab at the Claude Code prompt. The input mode indicator flips to Plan Mode. ^[inferred]
  • Read-only file access during the plan. Claude can read files, navigate the directory tree, run searches, and ask the user questions, but cannot write to disk. The clarifying-question flow happens here — Claude surfaces ambiguities before committing to an approach.
  • Plan presentation. Claude returns a structured plan describing what it intends to change, in what order, with which files. The plan is the artifact the user reviews.
  • Approval gate. The user accepts the plan (begin execution), edits it (iterate on scope), or rejects it (re-plan from scratch). Only after approval does Claude leave Plan Mode and start writing. ^[inferred]
  • Clarifying-question flow. Per the Codex-course mirror: “Codex asks clarifying questions, then proposes a plan. Iterate on the plan: edit, refine, change scope. Submit the plan, Codex executes.” Same shape in Claude Code.
  • Verification loops after execution. Plan Mode pairs naturally with the verification loop Boris Cherny calls “the single most important habit” — once the plan executes, Claude tests its own work (screenshots, browser checks, test runs) before declaring done. ^[inferred]

Opus Plan / Sonnet Execute pattern

The hidden cost-optimization setting routes the planning turn to Opus and the execution turns to Sonnet. The rationale, verbatim from the Nate Herk source:

“Opus does the planning, Sonnet does the execution. Smart model where it matters, cheap model for grunt work. Cuts cost in half without losing quality.”

Why this works:

  • Planning is where reasoning quality compounds. A bad plan corrupts every downstream execution turn. Opus’s reasoning depth is highest-value at the plan step.
  • Execution is mechanical token throughput. Once the plan is right, the work is mostly typing — apply the edits, run the tests, format the output. Sonnet handles this at a fraction of the cost.
  • The cost math compounds across long sessions. A /goal-driven run can chew through 40-80 tasks (see claude-code-goal-command-walkthrough). At that volume, swapping Sonnet in for the execution half is the difference between 15 on a single session.

When to override: the Opus-Plan / Sonnet-Execute split assumes the execution work is genuinely mechanical. For tasks where the execution itself needs deep reasoning (complex refactors, security-sensitive edits, hairy migrations), keep Opus on both halves. ^[inferred] The default is the optimization; the override is the exception.

Combine with prompt caching. The Plan Mode prompt prefix (system prompt + tools + CLAUDE.md) is cached. Stable plans → cache hits → another 60-90% cost drop on long sessions. ^[inferred] See nate-herk-every-level-of-claude § L4 power moves for the full cost-optimization stack.

Try It

  1. Open Claude Code in any project and press Shift+Tab twice. Confirm the input indicator flips to Plan Mode before describing the task.
  2. Use the “Plan Mode first, then /goal” sequence for any non-trivial build. Enter Plan Mode → describe the goal → let Claude draft a plan with a verifiable end condition → hand that plan to /goal for the long-running execution.
  3. Enable the Opus-Plan / Sonnet-Execute setting before your next multi-file refactor. Watch the cost on a session you’d normally run on Opus end-to-end; expect roughly half.

Graph View

Backlinks