Module 8 — Plan mode, checkpoints, sessions and worktrees: working without fear

Module 7 locked down what Claude is allowed to do. This module handles the next question: what to do when Claude does something I did not want, or when I want to try two leads in parallel without one polluting the other? Four safety nets stack:

• Plan mode prevents writing until a plan is validated.
• Checkpoints rewind code and conversation to a point before the accident.
• Sessions keep conversations so you can resume them, name them, split them (/branch) or copy them into the background (/fork).
• Worktrees isolate a whole session inside a separate git checkout.

Plan mode: think before writing

Plan mode tells Claude to research and propose changes without applying them: Claude reads files, runs exploration shell commands, drafts a plan; edits stay blocked until approval (except in bypassPermissions).

You enter plan mode with Shift+Tab (cycle), /plan (switch for one turn), /plan <description> (switch and start the described task), or claude --permission-mode plan on launch. Shift+Tab again exits without validating.

For shell commands during planning: if auto is available and useAutoModeDuringPlan is on (default), the classifier judges each command — exploration goes through, writes are refused. Otherwise every command outside read-only asks, even if the sandbox auto-allow is on. In bypassPermissions, no guard.

When the plan is ready, Claude presents it and asks what comes next:

• Yes, and use auto mode — approves and switches to auto (becomes Yes, auto-accept edits if auto is unavailable, or Yes, and switch to BYPASS PERMISSIONS if the session was launched with that mode).
• Yes, manually approve edits — approves and returns to Manual to validate each edit.
• No, keep planning — stays in plan mode to iterate.

Ctrl+G opens the plan in your external editor before you decide; if showClearContextOnPlanAccept is enabled, one option approves and clears the planning context. Accepting a plan gives the session a generated title from the plan.

To make plan the default in a project: permissions.defaultMode: "plan" in .claude/settings.json. The VS Code extension reads claudeCode.initialPermissionMode in user settings instead. The /ultraplan command (send to a web session) has been retired; use local /plan.

Checkpoints: rewind without fear

At every user prompt, Claude Code captures the state of the files touched by its edit tools; it keeps up to the 100 most recent. /rewind (aliases /checkpoint, /undo) or Esc twice with an empty input opens the menu. If the input has text, the double Esc clears it and stores it in history.

Each checkpoint offers, depending on what was captured:

Option	Effect
Restore code and conversation	Rewinds files and conversation.
Restore conversation	Rewinds the conversation, keeps the code.
Restore code	Rewinds the files, keeps the conversation.
Summarize from here	Compresses the conversation starting at this point (frees context).
Summarize up to here	Compresses up to this point, keeps what follows intact.

After a conversation restore or a "Summarize from here", the original prompt is put back in the input. To steer a summary, highlight the option and type in the add context (optional) field before pressing Enter.

What is not rewound: files changed by Bash (rm, mv, cp), subagent edits (except a foreground-forked skill with background: false), concurrent external changes, symlinks/hardlinks (Claude Code skips them with Restored the code, but skipped N files). Snapshots are purged after about 30 days; cleanupPeriodDays extends retention. If a /clear happened inside the same process, the menu adds a /resume <session-id> (previous session) entry to fall back to the pre-clear conversation (v2.1.191+).

Sessions: name, resume, branch out

A session is a conversation tied to a folder, continuously saved under ~/.claude/projects/<project>/<session-id>.jsonl (movable via CLAUDE_CONFIG_DIR). Five ways to resume it:

Command	Effect
claude --continue	Resumes the current folder's most recent interactive session.
claude --resume	Opens the picker.
claude --resume <id-or-name>	Resumes directly (the ID is searched in the project, its worktrees, then every other project — v2.1.223+).
claude --from-pr <number>	Picker filtered on sessions tied to that PR.
/resume	Switches to another conversation from an active session.

What is restored: full history, model, agent (--agent), goal (/goal), non-expired scheduled tasks, permission mode (subtle rules depending on the entry path). An originating bypassPermissions never auto-restores — you have to re-pass it on launch.

Name your sessions. claude -n <name> at startup, /rename <name> mid-session (the name shows on the prompt bar), Ctrl+R on a picker line. An already-taken name gets a suffix like auth-refactor-graceful-unicorn (v2.1.232+).

The picker (/resume alone or claude --resume): ↑/↓ to navigate, Space to preview, Ctrl+R to rename, Ctrl+A to widen to all projects, Ctrl+W to all worktrees, Ctrl+B to filter by git branch. Pasting a PR URL (GitHub/GitLab/Bitbucket) in the search finds the session that created it.

Seven commands drive the life of a session:

• /clear [name] — clears the context, starts a new conversation. The name labels the previous one in /resume. Recoverable via rewind (previous session) as long as the process is running. Aliases: /reset, /new.
• /branch [name] — copies the conversation and switches into it; the original stays intact. "Allow for this session" grants are preserved (same process). CLI equivalent: claude --continue --fork-session.
• /fork [prompt] — copies the conversation into a new background session and leaves you here. The copy receives the instruction to create its own worktree before editing.
• /export [file] — exports in readable text; without an argument, dialog (clipboard or file).
• /recap — one-line summary (400 characters max). An automatic recap also shows on return after three minutes away (can be disabled in /config, Session recap).
• /add-dir <path> — widens access to a folder (Tab completes). Triggers DirectoryAdded hooks. The .claude/ of the added folder is not discovered.
• /cd <path> — moves the session into another folder (the transcript follows), to be distinguished from /add-dir which only widens.
• /diff — opens the diff panel on the working tree, up to date after each edit.

Worktrees: parallelize without stepping on each other

A git worktree is a separate folder with its own branch but sharing the .git of the main repo. A session inside a worktree isolates its edits: one session codes auth while another fixes a bug, without ever touching the same files.

claude --worktree feature-auth

Without a name, Claude generates one (bright-running-fox, etc.). The worktree is born under .claude/worktrees/<name>/ on a branch worktree-<name> — add that to your .gitignore. Interactive runs require workspace trust. Inside a session, Claude can create or enter a worktree via the EnterWorktree tool; any target outside .claude/worktrees/ prompts for approval, and only bypassPermissions skips that guard.

Isolation enforced by Claude Code — four non-disableable checks on every tool call:

1. Edit, Write, NotebookEdit aimed at the main checkout: refused.
2. Bash/PowerShell/Monitor command whose cwd resolves into the main: refused.
3. Command that redirects git toward the main (git -C, GIT_DIR, cd before git): refused.
4. Command whose form does not let us statically verify where git goes: refused.

The same rules cover every subagent launched from the isolated session. The sandbox lets writes into the shared .git through, so git commit works.

Parameters:

• worktree.baseRef: "fresh" (default) branches from the remote's default branch; "head" branches from the local HEAD to carry work in progress.
• Branch from a PR: claude --worktree "#1234" (quotes required). GitHub or GitLab URLs accepted.
• .worktreeinclude at the project root (.gitignore syntax) copies gitignored files — .env, .env.local, config/secrets.json — into every new worktree.
• isolation: worktree in a subagent's frontmatter freezes its isolation (module 10).

Cleanup — on exit of a --worktree session, if the worktree is clean and the session unnamed, it is deleted automatically; otherwise it prompts. A periodic sweeper removes subagent and background-session worktrees older than cleanupPeriodDays, except for unpushed work, an active lock, or a manual git worktree add.

Running example: refactoring Kiosque payments

Friday. Karim has to add a second payment provider to Kiosque behind a flag, without breaking Monday's demo. He opens:

claude --worktree paiement-v2

The worktree is born on worktree-paiement-v2 from a fresh main (.worktreeinclude has copied .env). Karim types:

/plan Add a second payment provider behind the PAY_V2 flag, without breaking the old one.

Claude explores app/paiements/, writes a seven-step plan. Ctrl+G — Karim reformulates step 4 in his editor. He picks Yes, manually approve edits. Auto title: "Add PAY_V2 behind a flag".

Three edits later, a test breaks. Esc twice, select the prompt from two turns ago, Restore code and conversation. The original prompt returns to the input, he reformulates: "the previous attempt broke the webhooks — start with the test that reproduces the bug". This time it lands.

In parallel, Lea explores an alternative in a second terminal, starting from work in progress (worktree.baseRef=head in her settings.local.json):

claude --worktree paiement-v2-alt

She names her session paiement-alt. Halfway through, /branch etage-callback copies the conversation and switches into it, the original stays in /resume. Around 5 pm, Karim wants to ask Claude about the tests without polluting his session: /fork Write me a table of the existing integration tests and their blind spots. The copy goes to the background (visible in claude agents), his session stays on the refactor.

Monday, the demo runs on main, worktree-paiement-v2 is ready to merge, paiement-v2-alt is archived, and /export release-paiement.md captures the key conversation for the PR. Three leads, zero file conflicts, zero overwrites.

Summary

• Plan mode (Shift+Tab, /plan, --permission-mode plan): blocks edits until validation. The classifier judges shell commands if useAutoModeDuringPlan is active; Ctrl+G opens the plan in the editor; approving assigns an auto title.
• Checkpoints: capture on every prompt (last 100). /rewind or Esc+Esc (empty input) offer restore code / conversation / both, or summarize. Bash-driven changes, non-foreground-forked subagents, symlinks and external changes are not rewound.
• Sessions: --continue, --resume, --from-pr, /resume. Name with -n, /rename. /clear clears, /branch copies and switches, /fork copies into the background, /export archives, /recap summarizes, /add-dir widens, /cd moves, /diff shows.
• Worktrees (--worktree <name> or EnterWorktree): each session in a separate git checkout. worktree.baseRef picks fresh or head, --worktree "#1234" branches from a PR, .worktreeinclude copies gitignored files, isolation: worktree locks a subagent, and Claude Code refuses any write that would target the main checkout.

Next module: Hooks: automate and lock Claude's behavior — how to intercept every event (before/after a tool, a prompt, a settings edit, the creation of a worktree) to add validations, measures and automation.