Course · Claude Code · Planning

Enter plan mode to research before you change code

Plan mode is the Claude Code setting in which the agent researches and proposes changes without making them. This page covers how to enter it, what it allows while the agent reads your code, and the one configuration where its edit-block does not hold.

The task used throughout is a redesign in a small TypeScript payments service: make POST /payments idempotent, so a client that retries a completed request is never charged twice. The current helper in src/utils/idempotency.ts records the client’s Idempotency-Key as seen at first check, before the payment finishes, and the function meant to record completion, markProcessed, is never called. The route in src/index.ts does not require the header at all; it passes it as optional to processPayment in src/payments/processor.ts, where the conditional dedup lives. The test suite is green, and it includes a duplicate-key test that passes because a second call with the same key is rejected.

Green suite plus a design-heavy ticket is exactly when the agent should not start editing. With no failing test to steer by, its first edit commits it to an interpretation - require the key or not, mark at check or at completion - and a wrong guess shows up as a diff you have to unpick instead of a sentence you get to correct. So the first move is a mode change, not a prompt.

Three ways in

There are three ways into plan mode, and they differ in how long the posture lasts:

# the ladder - cycle to the plan rung
[Shift+Tab]    default → accept edits → plan

# one prompt, planned, then back to where you were
/plan research how POST /payments handles idempotency

# the whole session, planned from the first prompt
claude --permission-mode plan

Shift+Tab cycles through the permission modes your version and configuration offer; the status bar shows the active one. Current documentation puts plan right after accept-edits (the rung that auto-applies file edits) on that cycle, and pressing it again leaves plan mode without approving anything. The /plan prefix is the lighter instrument: it runs one prompt in the posture, then the session returns to whatever mode it had. Useful when a single question deserves research in the middle of other work.

claude --permission-mode plan is for tasks you already know are big. The session starts in the posture and stays there until you approve a plan or cycle away, so every prompt gets the research treatment until you decide otherwise. All three paths land in the same place: a session that can read your code and reason about it, and cannot change it.

The think-first posture is not unique to Claude Code. The other agents on this site carry their own versions, with different entry points and different strictness. The stepper below walks the stages: switch in, explore, a blocked edit attempt, the plan, the gate, execution. Follow the Claude Code column; the other tools are there for contrast. Its blocked-edit stage shows the normal case, where the mode’s blocks hold; the bypassPermissions exception in the next section names the one configuration where they do not.

1 / 6You switch into the posture

Shift-Tab

A session toggle on the active agent - cycle into Plan mode mid-conversation. /plan on a single prompt is the lighter cousin: one prompt in the posture without switching modes - the prefix requests the plan, the mode enforces it.

What the mode allows, and what it blocks

In plan mode, reads are unrestricted: the agent can open every file, follow imports, and search the tree. Shell commands are reviewed by the safety classifier when auto mode - the permission mode where most actions run without asking, with a classifier reviewing each one - is available in your configuration: approved commands run, rejected ones are blocked. Without auto mode available, commands outside the built-in read-only set prompt you instead.

Source edits are the point of the mode: they stay blocked until you approve a plan. One exception matters, and Permissions & modes covers it in full: in an interactive session where bypassPermissions (the mode that skips permission checks entirely) appears in your mode cycle - available to switch to, even if you never switch - the plan-mode blocks are not enforced, even while plan mode is the active mode. The agent is still instructed to plan, but edits and commands can run without prompting, so check whether your cycle offers bypassPermissions before treating plan mode as a fence.

Pointed at the ticket, a research pass reads the files named above plus a few around them. Here is the shape of such a pass over the real source - an illustrative transcript, not a captured run:

> [Shift+Tab]   # plan mode on

> the duplicate-payment handling needs a redesign. research how
  POST /payments handles idempotency today and propose a fix.
  do not edit anything yet.

  ⏵ Read  src/index.ts
  ⏵ Read  src/payments/processor.ts
  ⏵ Read  src/utils/idempotency.ts
  ⏵ Read  tests/payments.test.ts

  ## Current behavior
  The route passes an optional Idempotency-Key header to
  processPayment. No key means no dedup happens at all.
  checkIdempotency records the key on first check, before the
  payment runs; markProcessed is never called.

  ## Proposed approach
  1. Require Idempotency-Key on POST /payments, reject when absent
  2. Check the key without recording it; call markProcessed only
     after a payment completes
  3. ... [full plan continues]

Every line of that sketch maps to a fact stated above: the optional header in src/index.ts, the conditional dedup in src/payments/processor.ts, the mark-on-first-check in src/utils/idempotency.ts, and the unused markProcessed sitting next to it. That checkability is the artifact plan mode exists to produce. The agent did the reading and committed to an approach, and committed nothing else.

What the mode allows shifts with versions and configuration, which is why this page links instead of memorizing: the permission-modes reference carries the current rules for reads, commands, and the approval gate.

What you hold now is a researched proposal and an unchanged codebase. That is not the same as zero risk taken: reads and commands still ran, and the edit-block is only as strong as the permission posture under it, with bypassPermissions as the documented exception. The honest claim is narrower and more useful: the design decision is on the table before any code expresses it, so correcting it costs a sentence instead of a diff. Now decide what happens to that plan.