Guide
Give Claude Code a Fresh Start Without Losing Progress
Long Claude Code sessions can accumulate stale assumptions, failed debugging paths, and irrelevant conversation history. /compact frees context by summarizing the current conversation, but sometimes the cleaner move is to write the important state into a project file and start a new conversation. This workflow gives the new session the facts it needs without carrying every earlier turn forward.
- 1
Inspect the real project state
- 2
Write a verified handoff.md
- 3
Review it for gaps and secrets
- 4
Run /clear or start a new session
- 5
Verify the state and continue
Goal
The exact outcome and definition of done.
State
Changed files, Git status, checks run, and what currently works.
Failures
Dead ends, exact errors, and approaches not to repeat blindly.
Next move
One clear first action for the fresh session, followed by verification.
Official references
How to use it
- 1
Ask the current session to create the handoff
Run this before clearing the conversation. It tells Claude to inspect the real working state instead of writing a handoff from memory. The result should be a handoff.md file in the project root, with no passwords, API keys, tokens, or other secrets.
Before this session ends, create or update a file named handoff.md in the project root. Write it for a new Claude Code session that has no access to this conversation. First inspect the current project state using the available read-only checks, including the working directory, git status, git diff, recent git history, relevant files, and the latest test or build results. Do not guess, and do not claim a check passed unless you actually ran it. Include these sections: # Goal The exact outcome we are trying to achieve. # Current state What currently works, what is incomplete, and where the task stands. # Files being worked on Every relevant file path, what changed, and why it matters. # Changes already made A concise list of implemented changes, including important decisions and assumptions. # Failed attempts and dead ends What was tried, the exact error or result, why it failed, and what should not be repeated without new evidence. # Verification completed Tests, builds, lint checks, browser checks, or manual checks actually run, with their results. # Next steps An ordered list beginning with the single best next action. Include remaining verification and the definition of done. # Risks and open questions Anything uncertain, blocked, security-sensitive, destructive, or requiring user approval. # Restart prompt A short prompt the user can paste into a fresh Claude Code session. Keep the file concise but operationally complete. Preserve existing work. Do not modify any project file other than handoff.md while creating the handoff. Never include credentials, tokens, private keys, secret environment values, or personal data.
Claude - 2
Review the file before clearing anything
Open handoff.md and check that the goal, changed files, failures, test results, and next action are accurate. Make sure it does not contain secrets. If important work is still only in Claude's explanation and not in the filesystem, save or commit it before starting fresh.
- 3
Start with empty conversation context
Run /clear to start a new conversation with empty context, or exit and launch a new Claude Code session from the same project folder. /clear preserves the previous session so you can still return to it with /resume, but the new conversation begins without its message history.
/clear
Claude - 4
Load the handoff into the fresh session
Paste this into the new session. It requires Claude to verify the filesystem and Git state before continuing, so an inaccurate or outdated handoff does not become the new source of truth.
Read handoff.md, then independently inspect the current working directory, git status, git diff, recent git history, and every file named in the handoff. Treat the repository and test results as the source of truth if they conflict with the document. Before editing anything, give me five concise bullets covering: the goal, current state, relevant files, failed approaches not to repeat, and the single best next step. Then continue from the first incomplete step. Preserve all existing work, do not repeat a failed approach without new evidence, and run the relevant verification before declaring the task complete.
Claude - 5
Remove or refresh stale handoffs
A handoff is a point-in-time snapshot. Update it before the next session switch, or delete it after the task is complete so a future agent does not follow outdated instructions. If the file should remain local only, add it to the project's ignore rules after checking with your team.
Tips
- Use /context to see what is filling the context window before deciding whether /compact is enough.
- /compact is useful when you want to keep the same conversation; /clear is useful when you want empty conversation context for a new task or clean restart.
- A handoff should report facts from the filesystem, Git, and test output—not just Claude's memory of the conversation.
- Record failed approaches with the exact error and why they failed so the new session does not loop back to them.
- Never put API keys, passwords, tokens, private keys, or secret environment values in handoff.md.
- For risky or unfinished work, make a normal Git checkpoint before switching sessions when that fits your team's workflow.
Want every new prompt and tool I share, in your inbox? Free, every Tuesday.
Join the newsletter