What Is Plan Mode in a Coding Agent?

Quick answer
Plan mode is a read-only phase in which the agent investigates and proposes a sequence of steps without changing files.
You approve, edit, or reject the plan before any edits happen, which is the cheapest point to correct the approach.
A useful plan names the files it will touch, the commands it will run, and how it will verify the result.
Plan mode does not guarantee a good plan; it makes a bad plan visible before it becomes a diff.
Use it for multi-file changes and unfamiliar codebases, and skip it for one-line fixes where the plan is the change.

What does plan mode change about agent behaviour?

In plan mode the agent may read files, search, and run read-only commands, but it does not write. It produces a proposed sequence of actions instead. The next step only happens after you accept the plan or edit it.

The value is timing. A wrong assumption costs one paragraph to fix at the plan stage, and a reverted branch, a re-run, and a review later if it is discovered after implementation.

What should a good plan contain?

The files it will modify and why, the commands it will run, the tests that prove the change works, and anything it is unsure about. Uncertainty is the most useful part: it tells you where the agent is guessing before it guesses in code.

A plan that says “update the authentication flow” is not a plan. A plan that names the middleware, the session table, and the two tests it will add is reviewable.

1. Read src/auth/session.ts and middleware/requireUser.ts
2. Add an expiry check in requireUser before the role check
3. Add a test for an expired session in test/auth.test.ts
4. Run: npm test -- auth
5. Verify: expired token returns 401, valid token still returns 200
Open question: should refresh tokens be rejected in the same path?

When is plan mode worth the extra turn?

Use it when the change spans several files, when you do not know the codebase, or when the task has more than one reasonable interpretation. The extra turn buys a chance to reject the wrong interpretation before it exists as code.

Skip it for changes where the plan is longer than the diff: renaming a variable, fixing a typo, bumping a dependency. Process that costs more than the work it guards is just delay.

What does plan mode not protect you from?

It does not stop a bad plan that reads well. An agent can describe a plausible sequence that misses a constraint in your system, and approval makes it your constraint to have missed. Read the plan against the spec, not against the prose.

It also does not bound what happens during implementation. Approving a plan is not approving every command, so permissions still matter. Keep destructive commands behind approval regardless of how good the plan is.

Where this bites vibecoders
Plan mode is easy to treat as a formality: the agent writes five confident bullets, you press approve, and the real decisions happen later in the diff. The habit that pays is reading the plan for the files it does not mention, because that is where the surprise edits come from.

Where AI coding assistants get this wrong

Writing a plan that names outcomes without naming files or commands.
Approving a plan without checking what it leaves out.
Using plan mode for trivial edits and then ignoring the plan.
Treating plan approval as approval for any command during implementation.
Letting the agent plan against its own assumptions instead of the spec.
Skipping the verification step in the plan.

Checklist

Ask for a plan before multi-file changes.
Check the file list against what you expect.
Make the agent state its open questions.
Require the test command in the plan.
Reject plans that describe outcomes instead of steps.
Keep destructive commands behind separate approval.

FAQ

Is plan mode the same as asking for a plan in the prompt?

Functionally similar, but plan mode enforces it: the harness prevents writes while the plan is under review. A prompt-only request can be ignored mid-run, and some agents will start editing before they finish describing the approach.

Should plan mode be the default?

Default it on for unfamiliar repositories and multi-file work, and off for small edits. A permanent plan step on one-line fixes trains you to approve without reading, which removes the benefit everywhere else.

Can I edit the plan instead of rejecting it?

Usually yes, and that is the best use of the feature. Correct the file list, add the missing test, and remove the step you do not want. An edited plan is a specification the agent will follow.

Does a plan make the change safe?

No. It makes the approach reviewable before implementation. Safety still comes from permissions, sandboxing, tests, and reviewing the actual diff.