Plan mode

Plan mode is a permission mode that lets Claude Code read and explore but not change your files, so it proposes a plan you approve before any edit.

Last updated: 29 Sep, 2026 · Claude Code

The cheapest correction is the one made before anything is written, and plan mode is where you check its thinking first.

In plan mode it does everything except change your source: it reads files, runs commands to explore, and writes out what it intends to do. Edits stay blocked until you approve the plan.

Planning a vectorless RAG notebook in plan mode

The video presses Shift+Tab until the status bar reads plan mode on, then asks for new work: "hey i want to create some new jupyter notebook on vectorless rag using python and page index library. Please make a detailed and save it in plan.md so that we can see it".

Claude replies that plan mode lets it write only its own plan file, and offers to drop a copy at plan.md in the repository once the plan is approved. Then it researches before it plans: web searches on vectorless RAG and PageIndex, a fetch of the PageIndex cookbook notebook, and an Explore subagent that reads the existing notebooks to match their style. When the next part of the video opens, the notebook exists and plan.md sits in the repository beside it.

Saving the plan to plan.md

That last request is a habit worth copying. A plan that stays in the session disappears with it; a plan.md in the repository can be read by a teammate, reviewed in a pull request, and handed to a new session tomorrow. Add "save the plan to plan.md" to any planning prompt whose result you want to keep.

The rest of this lesson uses plan mode on this course's project.

Turning it on

Three ways in, and they all reach the same place. Press Shift+Tab in a session until the status bar reads plan mode on. Prefix a single prompt with /plan when only that one prompt needs it. Or start the whole session in it.

claude -p "Plan how you would add tests for shorten.py. Do not write any files." \
  --permission-mode plan

Plan complete. Ready for review.

Drafted comprehensive test plan for shorten.py covering:
- **next_code()**: Code sequence generation (a0, a1...z0, z1, etc.)
- **shorten()**: URL shortening with store.save() calls
- **expand()**: URL retrieval with store.find()
- **Integration test**: End-to-end roundtrip validation

Uses pytest + mocked store for isolation. ~12 unit tests + 1 integration test planned.

Plan at `/Users/you/.claude/plans/plan-how-you-would-swift-dijkstra.md` ready for approval.

Two things happened there and neither one was an edit. It read the project well enough to name the three functions, and it wrote the plan to a file of its own rather than to your repository. Nothing in the project changed.

Reading a plan properly

A plan is worth more than the code it produces, because it is short enough to read closely. Ask the same three questions of every plan.

• Is it solving the problem you have, or a nearby one that is easier?
• Does it touch files you did not expect? That is usually a misunderstanding, not ambition.
• Does it say how it will check the work? A plan with no verification step produces code that has never been run.

The plan above fails the first question. Twelve tests and ninety five per cent coverage on a twenty line file is more than this project needs, and none of it mentions the bug from the overview. That is worth saying back before approving, and saying it is cheaper now than after the tests exist.

Approving

When the plan is ready it asks how to proceed. You can approve it and let it start editing, approve it and switch the session to auto mode, or keep planning and tell it what to change. Approving leaves plan mode, because planning is a phase of the work rather than a setting to stay in.

Related

• Previous: Permissions
• Next: Rewind and checkpoints
• Reference: Claude Code docs