Save a plan to disk and resume it in a fresh session

A plan approved in Claude Code’s plan mode lives in the conversation that produced it, and conversations are fragile. They get compacted (summarized in place to free context window), cleared with /clear, and closed along with the laptop. A plan that exists only in the context window can quietly vanish before it is built. This page gets it onto disk and shows the two ways back to it.

The plan in question is for a small TypeScript payments service, where POST /payments must become idempotent so a retried request is never charged twice. Currently checkIdempotency records a key as seen at the first check, before the payment finishes. The approved approach changes src/utils/idempotency.ts to record a key only after completion, and to require the Idempotency-Key header at the route. That fix was never going to land in one sitting: research today, implementation tomorrow, review after that. Days between sessions is exactly the condition under which an in-window plan disappears.

Get the plan out of the window

The direct move is Ctrl+G at the approval menu. It opens the plan in your editor, and an open file there is one Save As away from being a file you own. Write it to docs/idempotency-plan.md - a proposed addition; the repo has no docs/ directory, so this creates one. From that moment the agreed approach is independent of any session: compaction cannot summarize it away, /clear cannot lose it, and next week you can read it without resurrecting the session that produced it.

Make the file the first build step

Once you have approved and the session is in a build mode, there is a cleaner habit that makes persistence automatic rather than remembered: make writing the plan to disk the first implementation step. The shape of that instruction, and of the work it starts, is illustrative:

> before you start, write the plan we agreed to docs/idempotency-plan.md
  as a checklist, then work through it one item at a time, checking
  each off. run npm test when you're done and report the result.

  ⏵ Write docs/idempotency-plan.md
  ⏵ Edit src/utils/idempotency.ts   ...

Now the file is two things at once: the durable artifact, and a live progress tracker. If the session dies halfway through the build, the checklist shows exactly what is done and what remains. When a decision matters, write it where the context window cannot lose it.

One decision to make consciously: when to run the implementation. Later chapters of this course read the payments service in your working copy, with this defect still in place, so nothing ahead assumes you landed the fix. Land it whenever you like: this session, tomorrow’s resumed one, or the cloud session the next page covers. If a later exercise meets ground you already fixed, that slice comes back clean, confirming your work rather than contradicting it.

Resume tomorrow

Because the plan is on disk, coming back is two independent moves, and you can use either or both. Resume the conversation: the session you approved in carries a title generated from the plan’s content, so claude --resume lists it under a readable name rather than an opaque ID, with the full history intact. The resume lesson in Sessions & context covers the mechanics.

Or re-seed: start a fresh session and point it at the file - read docs/idempotency-plan.md and continue from the first unchecked item. No old context, no compaction baggage, just the plan and the code. For a long build this is often the better half of the pair, because the window stays lean; the checklist, not the history, is what the work actually needs.

Make planning the default

If almost every change in a repo deserves a plan first, and a payments service is a fair candidate, you can stop reaching for Shift+Tab (the shortcut that cycles into plan mode) at all:

.claude/settings.json

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

Every terminal session in the project now starts in plan mode: research and proposal are the default posture, and building is the deliberate second step you approve into. The key is permissions.defaultMode, documented in the settings reference, and plan takes effect from project settings - unlike auto and bypassPermissions, which must come from user or managed settings to apply.

One documented quirk worth a sentence: conversations started by the VS Code extension do not read the project setting for their starting mode. There the default is claudeCode.initialPermissionMode, per the permission-modes reference.

Plan mode now works end to end inside the terminal: research, review, approve, persist, resume. One surface remains. The idempotency plan is a file you can commit and push, and there is a way to run it somewhere your laptop is not required. Take it to the cloud with Claude Code on the web.