THE IDEA
Here’s what you need to know.
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.
See the visual breakdown
- 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
PUT IT INTO PRACTICE
Follow the steps.
Tick off each step as you go. Your progress is saved on this browser.
- STEP 01
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.
- STEP 02
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.
- STEP 03
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
- STEP 04
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.
- STEP 05
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.
A FEW THINGS THAT HELP
Get more out of it.
- 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.