Claude Code Plan Mode: Plan First, Then Track the Work

Plan mode is one of Claude Code’s permission modes↗ (opens in a new tab). In it, Claude reads files, runs commands to explore, and writes a plan, but does not edit your source until you approve that plan. You enter it by pressing Shift+Tab until the status bar shows ⏸ plan mode on, by starting a prompt with /plan, or by launching with claude --permission-mode plan. When the plan is ready, you approve it, keep planning, or edit it yourself. The plan is saved as a file on your machine, which is fine for one session and not much use to anyone else, so the last step is to put it on the cards the work belongs to.

How to enter plan mode

• Shift+Tab cycles the permission modes during a session. From auto mode the first press switches to manual; after that the cycle runs manual, accept edits, plan, and back. Watch the status bar: plan mode shows as ⏸ plan mode on.
• /plan enters plan mode from the prompt↗ (opens in a new tab). Add a description and it starts on it straight away: /plan fix the auth bug.
• claude --permission-mode plan starts a whole session in plan mode.
• To make it the default for a project’s terminal sessions, set permissions.defaultMode to plan in the project’s .claude/settings.json. The VS Code extension does not read project settings for this; set claudeCode.initialPermissionMode to plan in your VS Code user settings instead.

{
  "permissions": {
    "defaultMode": "plan"
  }
}

What plan mode can and cannot do

Plan mode is about edits. Claude reads files without asking, as it does in manual mode, and it can run shell commands to explore. What happens to a command depends on your session: if auto mode is available and the useAutoModeDuringPlan setting is on, which it is by default, a classifier reviews commands instead of asking you; otherwise, commands outside the built-in read-only set ask for approval. Edits to your source stay blocked until you approve a plan.

Four limits are worth knowing before you rely on it:

• It is not enforced in every session. In an interactive terminal session started with bypass permissions available, Claude is still told to plan without editing, but an edit or command it attempts during planning runs without a prompt. Outside an interactive terminal, including claude -p runs and the VS Code chat panel, plan mode keeps its blocks.
• Your deny rules↗ (opens in a new tab) still apply, in every mode. Plan mode sits on top of your permission rules, not in place of them.
• It is not a review of the plan’s quality. Plan mode stops Claude acting before you have read what it intends; whether the plan is right is still your call.
• The documentation describes plan mode in terms of edits to your source and shell commands. If you have connected tools that write somewhere else, such as a task board over MCP, do not treat plan mode as the control for them. The scopes you gave that connection are.

Approving a plan, and leaving without one

When the plan is ready, Claude presents it and asks how to proceed. The choices are:

• Yes, and use auto mode: approve and let Claude continue in auto mode. If auto mode is not available to your session, this reads Yes, auto-accept edits.
• Yes, manually approve edits: approve, and review each edit as it comes.
• No, keep planning: stay in plan mode and tell Claude what to change.

Press Ctrl+G at that point to open the plan in your text editor and change it directly before Claude proceeds. If you turn on the showClearContextOnPlanAccept setting, the list gains a first option that approves the plan and clears the planning conversation, so the work starts with the plan and not the hour of exploring that produced it.

Approving exits plan mode and switches the session to the mode you picked, and Claude starts editing. To leave plan mode without approving anything, press Shift+Tab again. To plan again later, cycle back or start your next prompt with /plan. If you used /ultraplan in the past, it has been removed; the documentation↗ (opens in a new tab) points to plan mode instead.

Where the plan goes

Plan mode writes the plan to a file↗ (opens in a new tab). By default that is under ~/.claude/plans; set plansDirectory to a path inside the project, such as ./plans, to keep plans beside the code. Claude Code also treats the plan as something to keep: when a long session compacts its conversation, the plan written in plan mode is re-injected from disk rather than summarised away.

That is good for the session and not much further. A plan file in your home folder is invisible to a colleague, to your other machine, and to the Claude Code session you start next week, which has no way of knowing which of forty plan files belongs to which job. A plan is also written once and then overtaken: step three turns out to be two steps, step five turns out to be unnecessary. The file does not know.

Turning an approved plan into cards

The fix is to give the plan a home that other people and other sessions read: the card for the work. A useful rule of thumb is one card per outcome someone could check, not one card per step. A plan to “add CSV export” might be one card; a plan to “rebuild the import pipeline” is usually three or four.

On fenbs each task has two boxes, and they map onto planning neatly. The Problem box says what is wrong or missing, why it matters and where; it is written once, when the card is filed. The Plan box says how it will be done: the steps, the files, the traps and how it will be checked. It starts empty and is rewritten whenever something is learnt. Plan mode produces the second box. Keep it out of the first, or the original description of the problem is lost the first time the plan changes.

The simplest way to get there is to ask for the breakdown as part of the plan, so you approve the cards and the plan together, and have filing them be the first thing Claude does after approval:

/plan Rebuild the CSV import so bad rows are reported, not dropped.
End the plan with a "Cards" section: one card per outcome I could check,
each with a kind (feature, enhancement or bug), a one-line problem,
and its share of the plan.
After I approve, before you edit any file:
1. fenbs_search for each card; if one exists, update its plan instead.
2. Create the rest with fenbs_create_item: note = the problem,
   plan = that card's steps, files and how it will be checked.
3. Move the first card to In Progress and comment what you are starting.

Over MCP, the Problem box is note and the Plan box is plan. fenbs_update_item replaces the whole plan when you pass one, so when Claude learns something halfway through, it rewrites the plan on that card rather than appending to it, and the change is recorded in the board’s History with who made it. fenbs_create_item also checks for likely duplicates before filing and answers created: false with the matches if it finds any, which keeps a plan from filing the same card twice.

Keeping the plan honest as the work runs

• Before a card moves to In Progress, its Plan box should say what is about to be done. If plan mode produced it, that is already true.
• When the plan changes, the card changes. One line in CLAUDE.md does it: “If the approach changes, rewrite the plan on the card before carrying on.”
• When a card reaches Completed, the comment says what actually changed and the Testing field says how it was checked. The plan says what was intended; the comment and Testing say what happened.
• Next session, start from the board, not the plan file. fenbs_get_item returns the problem, the current plan and the comments, which is everything the old plan file had and everything it missed.

Plan mode and the board do different jobs. Plan mode makes Claude think before it acts, inside one session. The card makes the thinking available after the session has ended, to whoever picks the work up next. For the full rhythm of reading and writing the board, see a task-tracking workflow for Claude Code.